@lanexio/parser-query

This page documents @lanexio/parser-query, the LexQuery pattern matching engine for querying nodes in a LexTree by kind name, field, and error status.

• Version: Stable
• Module name: parser-query
• Package: @lanexio/parser-query
• Import path: @lanexio/parser-query
• Layer: 3 (Query)
• Runtime: Universal
• Module format: ESM
• Stability: Stable
• Primary use case: Query nodes in a LexTree by pattern.

Layer contract

Layer 3 dependency rules

This package depends only on Layer 1. It does not import from grammar packs, bridges, or entry packages.

When to use this module

• You need to find nodes in a parsed tree by kind name or pattern.
• You need to filter nodes by field, error status, or wildcard.
• You want to build a kind index for faster repeated lookups.

Module boundary

Boundary	Description
Inputs	Pattern string, LexQueryKindResolver
Outputs	LexQuery (compiled), IterableIterator<LexNode> from matches()
Side effects	None
Determinism	Yes (same pattern + same resolver produce same compiled query)
External dependencies	@lanexio/parser-core
Never-throw guarantee	No: LexQuery.compile() throws LexQuerySyntaxError on invalid patterns. query.matches() never throws.
Security surface	None (no output generation)

Installation

1. Install the package.

   pnpm

   pnpm add @lanexio/parser-query

   npm

   npm install @lanexio/parser-query

   yarn

   yarn add @lanexio/parser-query

2. Import the named export.

   import { LexQuery, type LexQueryKindResolver } from '@lanexio/parser-query';

Peer dependencies

Requirement	Required	Layer	Notes
@lanexio/parser-core	Yes	1	^1.0.0

Basic Usage

import { LexQuery } from '@lanexio/parser-query';
import { HtmlKind } from '@lanexio/parser-grammar-html';

const resolver: LexQueryKindResolver = (name: string) =>
  (HtmlKind as Record<string, number | undefined>)[name];

const query = LexQuery.compile('Element', resolver);

const encoder = new TextEncoder();
const tree = parseHtml(encoder.encode('<div><p>text</p></div>'));

for (const node of query.matches(tree)) {
  console.log(node.kind, node.range);
}

Exports

Export	Type	Description
LexQuery	class	Compiled pattern query. Created via LexQuery.compile().
LexQuerySyntaxError	class	Error thrown for invalid patterns. Has code and offset properties.
LexQuerySyntaxErrorCode	const object	Error code constants: EmptyPattern, UnexpectedToken, UnknownKind, UnsupportedAttribute.
createKindIndex	(resolver: LexQueryKindResolver, kindIds: number[]) => KindIndex	Create a precomputed kind index for faster lookups.

Options

No options object. LexQuery.compile(pattern, resolver) accepts the pattern string and resolver directly.

Return shape

LexQuery

Method	Return Type	Description
matches(tree: LexTree)	IterableIterator<LexNode>	Iterate matching nodes in preorder DFS.
testNode(node: LexNode)	boolean	Test a single node against the pattern.
source	string	The original pattern string.

Exported types

Type	Purpose	Notes
LexQueryKindResolver	Maps a kind name string to numeric kind ID or undefined	(name: string) => number | undefined
KindIndex	Precomputed kind index	Used with createKindIndex
CompiledSelector	Internal compiled selector	Not typically used directly
CompiledLevel	Internal compiled level	Not typically used directly
CompiledPattern	Internal compiled pattern	Not typically used directly

Configuration and Extension

Pattern grammar

Pattern	Description
KindName	Match nodes of the named kind.
*	Match any node.
@fieldName	Match nodes at the named field slot.
[error]	Match only LexError nodes.
A, B	Match either A or B (disjunction).

Kind resolver

The LexQueryKindResolver must be provided by the caller. Typically it is created by casting a grammar’s kind object (like HtmlKind, MdKind) as a Record<string, number>.

Accessibility

Accessibility requirements

• No direct accessibility surface. The query engine operates on AST data structures.

Accessibility checklist

Concern	Status
Generated output semantics	Not applicable (query engine)
ARIA attributes in serialized output	Not applicable
Semantic element round-trip	Not applicable

Security

Security considerations

• Invalid patterns throw LexQuerySyntaxError. The error message includes the pattern text.
• query.matches() never throws on any tree or node.

Threat	Mitigation	Status
Invalid pattern syntax	Throws LexQuerySyntaxError with code and offset	Implemented
Unknown kind names in pattern	Throws LexQuerySyntaxError with code UnknownKind	Implemented

Companion packages

Package	Relationship	Layer	Notes
@lanexio/parser-core	Requires	1	Provides LexTree, LexNode, LexCursor
@lanexio/parser-grammar-html	Enhances	2	Provides HtmlKind for resolvers
@lanexio/parser-grammar-markdown	Enhances	2	Provides MdKind for resolvers
@lanexio/parser-cli	Consumes	6	Uses LexQuery in the query subcommand

Changelog

Version	Date	Status	Notable changes
1.0.0	2026-05-29	Current	Initial stable release. Apache-2.0.

Migration notes

• None.

Related Content

LexQuery Guide: pattern-based tree queries with LexQuery.

Flat AST How the 16-byte node layout works.

Stability Guarantees Never-throw, panic-free, and 3-token recovery.