xlucene-parser / parser / Parser

Class: Parser

Defined in: packages/xlucene-parser/src/parser.ts:33

Parse a xLucene query and provide methods to traverse and manipulate the resulting AST.

The Parser class is the main entry point for parsing xLucene queries. It converts query strings into an Abstract Syntax Tree (AST) that can be traversed, validated, and transformed.

Example

const parser = new Parser('name:John AND age:>=25');
console.log(parser.ast); // Access the parsed AST

// Iterate over term nodes
parser.forTermTypes((node) => {
  console.log(node.field, node.value);
});

Constructors

Constructor

new Parser(query, options?, overrideAST?): Parser

Defined in: packages/xlucene-parser/src/parser.ts:67

Create a new Parser instance.

Parameters

Parameter	Type	Description
query	string	The xLucene query string to parse
options?	ParserOptions	Optional configuration for parsing behavior
overrideAST?	Node	-

Returns

Parser

Example

// Basic parsing
const parser = new Parser('name:John');

// With type configuration
const parser = new Parser('age:25', {
  type_config: { age: 'integer' }
});

// With variable filtering
const parser = new Parser('name:$username', {
  filterNilVariables: true,
  variables: { username: 'John' }
});

Properties

Property	Modifier	Type	Defined in
ast	readonly	Node	packages/xlucene-parser/src/parser.ts:34
filterNilVariables	readonly	boolean	packages/xlucene-parser/src/parser.ts:37
instantiateVariableValues	readonly	boolean	packages/xlucene-parser/src/parser.ts:38
query	readonly	string	packages/xlucene-parser/src/parser.ts:35
typeConfig	readonly	xLuceneTypeConfig	packages/xlucene-parser/src/parser.ts:36

Methods

filterNodes()

filterNodes(ast, fn): Node

Defined in: packages/xlucene-parser/src/parser.ts:180

Recursively filters nodes in an AST based on a predicate function. Handles logical groups, conjunctions, negations, ranges, and function nodes while preserving tree structure and automatically simplifying when possible (e.g., unwrapping single-node conjunctions).

Parameters

Parameter	Type	Description
ast	Node	The root AST node to filter
fn	(node, parent?) => boolean	Predicate function that receives (node, parent) and returns true to keep the node, false to remove it

Returns

Node

New filtered AST containing only nodes that pass the filter criteria. Returns empty node if all nodes are filtered out.

Examples

// Filter out unwanted fields
const filtered = filterNodes(ast, (node) => node.field !== 'unwanted');

// Filter based on parent context
const filtered = filterNodes(ast, (node, parent) =>
  !parent || utils.isLogicalGroup(parent)
);

---

forEachFieldValue()

forEachFieldValue(cb): void

Defined in: packages/xlucene-parser/src/parser.ts:476

Iterate over all field values from term-like nodes.

This method extracts and processes all field values from nodes that contain searchable terms. It's particularly useful for validating values and variables, or for collecting all values used in a query.

Parameters

Parameter	Type	Description
cb	(value, node) => void	Callback function called for each field value

Returns

void

Example

// Collect all literal values
const values: any[] = [];
parser.forEachFieldValue((value, node) => {
  if (value.type === 'value') {
    values.push(value.value);
  }
});

// Validate variable references
parser.forEachFieldValue((value, node) => {
  if (value.type === 'variable') {
    console.log(`Variable ${value.value} used in field ${node.field}`);
  }
});

---

forEachTermNode()

forEachTermNode(fieldValidator, valueValidator): void

Defined in: packages/xlucene-parser/src/parser.ts:498

Parameters

Parameter	Type
fieldValidator	(field) => void
valueValidator	(fieldValue) => void

Returns

void

---

forTermTypes()

forTermTypes(cb, skipFunctionParams): void

Defined in: packages/xlucene-parser/src/parser.ts:436

Iterate over all term-like nodes in the AST.

Term-like nodes include: Term, Regexp, Range, Wildcard, Function, and TermList. This is a convenience method that filters to nodes representing searchable terms.

Parameters

Parameter	Type	Default value	Description
cb	(node) => void	undefined	Callback function called for each term-like node
skipFunctionParams	boolean	true	Whether to skip traversing function parameters (default: true)

Returns

void

Example

// Process all searchable terms
parser.forTermTypes((node) => {
  if (node.field) {
    console.log(`Field: ${node.field}`);
  }
});

// Include function parameters in traversal
parser.forTermTypes((node) => {
  console.log('Term type:', node.type);
}, false);

---

forTypes()

forTypes<T>(types, cb, skipFunctionParams): void

Defined in: packages/xlucene-parser/src/parser.ts:323

Recursively iterate over all nodes of the specified types in the AST.

This method performs a depth-first traversal of the AST, calling the callback function for each node whose type matches one of the specified types.

Type Parameters

Type Parameter
T extends readonly NodeType[] | NodeType[]

Parameters

Parameter	Type	Default value	Description
types	T	undefined	Array of NodeType values to match
cb	(node) => void	undefined	Callback function called for each matching node
skipFunctionParams	boolean	false	Whether to skip traversing function parameters

Returns

void

Example

// Find all term and wildcard nodes
parser.forTypes([NodeType.Term, NodeType.Wildcard], (node) => {
  console.log('Found node:', node.type);
});

// Find logical groups, skipping function parameters
parser.forTypes([NodeType.LogicalGroup], (node) => {
  console.log('Logical group with', node.flow.length, 'conjunctions');
}, true);

---

mapNode()

mapNode(fn): Node

Defined in: packages/xlucene-parser/src/parser.ts:593

Transform the AST by applying a mapping function to each node.

This method performs a deep traversal of the AST, applying the provided function to each node and rebuilding the tree with the results. The function receives each node and its parent, and should return a transformed node.

Parameters

Parameter	Type	Description
fn	(node, parent?) => Node	Function to transform each node

Returns

Node

The transformed AST root node

Example

// Transform all string values to lowercase
const transformedAST = parser.mapNode((node, parent) => {
  if (node.type === 'term' && node.value.type === 'value') {
    return {
      ...node,
      value: {
        ...node.value,
        value: String(node.value.value).toLowerCase()
      }
    };
  }
  return node;
});

---

walkAST()

walkAST(cb): void

Defined in: packages/xlucene-parser/src/parser.ts:386

Recursively walk through every node in the AST and call the callback function for each node.

This method performs a depth-first traversal of the entire AST, visiting every node exactly once. Unlike forTypes() which filters by node type, this method calls the callback for all nodes regardless of their type.

Parameters

Parameter	Type	Description
cb	(node) => void	Callback function called for each node in the AST

Returns

void

Example

// Log all nodes in the AST
parser.walkAST((node) => {
  console.log(`Node type: ${node.type}`);
});

// Search for node properties
parser.walkAST((node) => {
  if (isFunctionNode(node) && node.name === 'knn') {
    hasKNN = true;
    return;
  }
});