lucene

library2.1.1jsnpmunverified

A JavaScript library for parsing, modifying, and stringifying Lucene query strings, built with PEG.js. Version 2.1.1 provides a stable API with a custom AST representation. It offers parse() and toString() functions to convert between query strings and structured objects. Compared to alternatives, it is lightweight and focused on query manipulation. The library is released as npm package and is in active use, though development cadence is low.

npm install lucene

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LUCENE

lucene

searchjavascriptv2.1.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

default

✓ import lucene from 'lucene'

✗ const lucene = require('lucene')

ESM default import works; the package also supports CommonJS require. The default export contains parse, toString, etc.

parse

✓ import { parse } from 'lucene'

✗ const { parse } = require('lucene')

Named exports available via ESM. CommonJS destructuring works too.

toString

✓ import { toString } from 'lucene'

✗ import toString from 'lucene'

toString is a named export, not a default export.

Node

✓ import { Node } from 'lucene'

TypeScript type: Node is a union type representing AST nodes. Not available at runtime.

Demonstrates parse() and toString() with AST modification, showing query manipulation round-trip.

import { parse, toString } from 'lucene'; // Parse a lucene query string into an AST const ast = parse('name:frank OR job:engineer'); console.log(ast); // { // left: { field: 'name', term: 'frank' }, // operator: 'OR', // right: { field: 'job', term: 'engineer' } // } // Modify the AST: change search term if (ast.left && 'term' in ast.left) { ast.left.term = 'franklin'; } // Convert back to string const newQuery = toString(ast); console.log(newQuery); // name:franklin OR job:engineer

Debug

Known issues

gotchaThe AST for simple terms does not include a field property; field may be undefined.

fix

Always check for existence of field before using it, e.g., ast.left.field ?? '*'

affects: >=2.0.0

breakingVersion 2.0 changed the AST structure: left and right nodes now have 'field' and 'term' instead of 'field' and 'value'.

fix

Use properties 'field' and 'term' instead of 'field' and 'value'.

affects: >=2.0.0 <2.0.0

gotchaThe library does not support fuzzy or proximity operators (~N) in queries.

fix

Manually handle fuzzy queries or preprocess them before parsing.

affects: >=2.0.0

gotchaEscaping special characters in terms is limited; certain characters may cause parse errors.

fix

Use backslash escaping for characters like + - && || ! ( ) { } [ ] ^ " ~ * ? : \

affects: >=2.0.0

Errors

Common errors & fixes

Error: Expected "(" or "OR" or "AND" but end of input found.

The query string ends unexpectedly after an operator or incomplete expression.

fix

Ensure the query string is complete, e.g., 'field:value OR field2:value'

TypeError: Cannot read properties of undefined (reading 'field')

AST node may not have a 'left' or 'right' property (e.g., for simple unary expressions).

fix

Check if the node exists before accessing properties: if (ast.left) ...

Error: Lucene query parse error near ':'

Invalid character or syntax near colon, e.g., missing value after colon.

fix

Use proper syntax: 'field:value' or 'field:"value with spaces"'

Upgrade

Version history

2.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

25 hits · last 30 days

node

Resources

githubgit://github.com/bripkens/lucene ↗

packagelucene ↗

homepagehttps://github.com/bripkens/lucene#readme ↗