Registry / database / xlucene-translator

xlucene-translator

library2.5.3jsnpmunverified

The `xlucene-translator` package is a core component within the Teraslice monorepo, specifically designed to convert xLucene syntax queries into various target database query formats. This provides a standardized query language layer, abstracting the complexities of different data backend syntaxes. The current stable version, derived from the Teraslice monorepo, is v3.6.1, with frequent updates that align with the active development cadence of the larger Teraslice project. Its primary differentiation lies in offering a flexible and unified translation interface, which is crucial for applications that need to query data across heterogeneous data stores, such as Elasticsearch or OpenSearch. The package is built for Node.js environments (requiring Node.js >=22.0.0) and ships with comprehensive TypeScript type definitions, enhancing developer experience and type safety.

database data serialization

npm install xlucene-translator

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · XLUCENE-TRANSLATOR

xlucene-translator

databasejavascriptv2.5.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Translator

✓ import { Translator } from 'xlucene-translator';

✗ const Translator = require('xlucene-translator');

The primary class for instantiating a query translator for a specific database dialect. Since v3, this package supports modern ESM imports, but typically provides CJS compatibility. Using named imports is recommended for TypeScript and modern Node.js projects.

QueryConfig

✓ import { QueryConfig } from 'xlucene-translator';

TypeScript interface for configuring translator options, such as the target database dialect and field mappings, crucial for accurate query conversion.

translate

✓ import { translate } from 'xlucene-translator';

✗ import translate from 'xlucene-translator';

A utility function for quick, stateless xLucene query translations without needing to explicitly instantiate the `Translator` class. It is exposed as a named export.

Demonstrates initializing an Elasticsearch translator with a field mapping object and translating two different xLucene queries into their corresponding Elasticsearch Query DSL representations.

import { Translator } from 'xlucene-translator'; interface MyDocumentMapping { field1: { type: 'keyword' }; age: { type: 'integer' }; isActive: { type: 'boolean' }; } // Example field mapping, mimicking an Elasticsearch index mapping const fieldMapping: MyDocumentMapping = { field1: { type: 'keyword' }, age: { type: 'integer' }, isActive: { type: 'boolean' }, }; async function runTranslation() { try { // Initialize the translator for the 'elasticsearch' dialect // The fieldMapping is essential for correct type inference and query generation const translator = new Translator<MyDocumentMapping>('elasticsearch', fieldMapping); const xluceneQuery1 = 'field1:"value example" AND age:>25 AND isActive:true'; const translatedQuery1 = translator.translate(xluceneQuery1); console.log('xLucene Query 1:', xluceneQuery1); console.log('Translated Elasticsearch Query 1:', JSON.stringify(translatedQuery1, null, 2)); const xluceneQuery2 = 'field1:test* OR age:[10 TO 20]'; const translatedQuery2 = translator.translate(xluceneQuery2); console.log('\n-----------------------------------\n'); console.log('xLucene Query 2:', xluceneQuery2); console.log('Translated Elasticsearch Query 2:', JSON.stringify(translatedQuery2, null, 2)); } catch (error: any) { console.error('Translation failed:', error.message); } } runTranslation();

Debug

Known issues

breakingThe `xlucene-translator` package, consistent with its parent Teraslice monorepo, now requires Node.js version 22.0.0 or higher. Running with older Node.js versions will result in environment errors or unpredictable behavior.

fix

Upgrade your Node.js runtime to version 22.0.0 or greater. If using pnpm, ensure your `pnpm` version is also updated to >=10.25.0 to meet engine requirements.

affects: >=3.4.0

gotchaProviding an incorrect or incomplete field mapping configuration to the `Translator` constructor can lead to failed translations or logically incorrect database queries, especially for type-sensitive operations like range queries or full-text searches.

fix

Ensure that the `fieldMapping` object accurately mirrors the schema (including data types) of your target database for all fields used in xLucene queries. This is critical for generating valid and effective database queries.

affects: >=1.0.0

gotchaAs a component of the Teraslice monorepo, `xlucene-translator`'s versioning and release cycle are tightly coupled with the broader Teraslice project. Independent updates to this package might introduce compatibility issues if not aligned with the main Teraslice release strategy.

fix

Always refer to the official Teraslice release notes and changelogs for coordinated updates across its internal packages. Prioritize updating `xlucene-translator` via Teraslice's recommended upgrade paths.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Unknown dialect: 'mongoDB'

The `Translator` constructor was called with a database dialect string (e.g., 'mongoDB') that is not recognized or explicitly supported by the `xlucene-translator` package.

fix

Verify the dialect string against the package's documentation for a list of supported database dialects (e.g., 'elasticsearch', 'opensearch').

Error: Invalid xLucene query syntax near 'my_field:badly-formatted:'

The xLucene query string provided to the `translate` method contains syntax errors, making it impossible for the parser to interpret correctly.

fix

Carefully review the xLucene query for any typos, incorrect operators, missing quotes, or malformed field-value pairs. Consult the xLucene specification for correct syntax guidelines.

TypeError: Cannot read properties of undefined (reading 'type') at Translator.translate

This error typically occurs when an xLucene query refers to a field (e.g., `my_missing_field`) that is not defined in the `fieldMapping` object provided during `Translator` instantiation, or the field lacks a `type` property.

fix

Ensure that every field mentioned in your xLucene query string has a corresponding entry in the `fieldMapping` object, and that each entry includes a valid `type` property (e.g., `{ type: 'keyword' }`).

Upgrade

Version history

2.5.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

40 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/terascope/teraslice ↗

packagehttps://www.npmjs.com/package/xlucene-translator ↗

homepagehttps://terascope.github.io/ ↗