Registry / serialization / llparse-builder

llparse-builder

library1.5.2jsnpmunverified

The `llparse-builder` library, currently at version 1.5.2, is a TypeScript-first package designed to facilitate the creation of high-performance parsers. It provides a fluent API for defining state machines and parsing logic, which are then compiled into a graph structure consumable by the `llparse` runtime. `llparse` itself is a parser generator that emits highly optimized C code (or WebAssembly via LLVM bitcode), making the parsers built with `llparse-builder` suitable for performance-critical applications like HTTP protocol parsing or other binary/text protocols where speed is paramount. The project is actively maintained within the `nodejs` GitHub organization, with recent dependency updates reflecting ongoing care. Its differentiating factor lies in its ability to abstract the complexities of low-level parser generation, enabling JavaScript/TypeScript developers to leverage the extreme performance of C-based parsers without writing C code directly. The release cadence appears to be driven by necessary updates or feature additions rather than a strict schedule.

serialization http-networking

npm install llparse-builder

github ↗package ↗

INSTALL

IMPORT

SIG · LLPARSE-BUILDER

llparse-builder

serializationjavascriptv1.5.2

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.

Builder

✓ import { Builder } from 'llparse-builder';

✗ const Builder = require('llparse-builder');

The primary class for constructing parser graphs. Uses named exports, not default.

Code

✓ import { Code } from 'llparse-builder';

✗ import { LLParseCode } from 'llparse-builder';

Used for defining actions and operations within the parser's state machine, typically accessed via a `builder` instance.

Node

✓ import { Node } from 'llparse-builder';

Represents a state node in the parser graph. Often returned by builder methods like `builder.node()`.

Demonstrates how to define a simple state machine parser for the sequence 'ABC' using the Builder API, including custom functions and error handling.

import { Builder, Code } from 'llparse-builder'; interface ParserContext { onComplete: () => void; onData: (char: number) => void; } const builder = new Builder<ParserContext>('simple_parser'); const start = builder.node('start'); const gotA = builder.node('got_a'); const gotB = builder.node('got_b'); const end = builder.node('end'); // Define custom functions that will be invoked in the C parser builder.addFunction('on_complete', 'void'); builder.addFunction('on_data', 'void', ['uint8_t ch']); // Error codes for the parser builder.addError('ERR_INVALID_CHAR', 1); start .match('A', gotA) .otherwise(builder.error(builder.errors.ERR_INVALID_CHAR)); gotA .match('B', gotB) .otherwise(builder.error(builder.errors.ERR_INVALID_CHAR)); gotB .match('C', end) .otherwise(builder.error(builder.errors.ERR_INVALID_CHAR)); end .invoke(builder.code.invoke('on_complete')) .span(builder.code.span('on_data')) // Example of spanning some data .skip(start); // Loop back to start for continuous parsing // Build the parser graph (this doesn't generate C code, just the internal representation) const parserGraph = builder.build(); console.log('Parser graph built successfully. It can now be used with `llparse` to generate C code.'); // console.log(parserGraph.print()); // For debugging the graph structure

Debug

Known issues

gotchaThe `llparse-builder` package generates an intermediate parser graph. This graph must then be processed by the `llparse` library to emit actual C code, which then requires a C compiler toolchain (e.g., GCC or Clang) to be compiled into a runnable parser. This is not a pure JavaScript solution for runtime parsing.

fix

Understand that `llparse-builder` is part of a multi-stage process. You will need `llparse` and a C compiler for a complete solution.

affects: >=1.0.0

gotchaThe underlying `llparse` model and the concepts of state machines, spans, and actions are low-level and C-like. Developers new to parser generators or low-level parsing might face a steep learning curve. Debugging issues can be complex, as errors may originate in the generated C code rather than the TypeScript builder logic.

fix

Familiarize yourself with state machine concepts and the `llparse` documentation. Start with simple parsers and incrementally add complexity. Leverage `llparse`'s own debugging features if available for generated code.

affects: >=1.0.0

gotchaWhile `llparse-builder` abstracts much of the complexity, performance-critical applications require careful design of the parser graph to avoid backtracking or inefficient state transitions. Suboptimal graph design can negate the performance benefits of generated C parsers.

fix

Plan your parser's state machine meticulously. Analyze input patterns and optimize for common cases. Consider tools for visualizing state machines if available.

affects: >=1.0.0

Errors

Common errors & fixes

error TS2307: Cannot find module 'llparse-builder' or its corresponding type declarations.

TypeScript compiler cannot locate the package's type definitions, possibly due to incorrect installation or missing `tsconfig.json` settings.

fix

Ensure `llparse-builder` is installed (`npm install llparse-builder` or `yarn add llparse-builder`) and that your `tsconfig.json` includes `"moduleResolution": "node"` or similar settings to resolve modules correctly. If using an older TypeScript version, an explicit `types` entry might be needed.

TypeError: builder.build is not a function

Attempting to call `build()` on something that is not an instance of `Builder`, or `Builder` was imported incorrectly (e.g., as a default import when it's a named export).

fix

Verify that `Builder` is imported as a named export: `import { Builder } from 'llparse-builder';` and that `new Builder(...)` is used to create an instance before calling methods on it.

Parsing error: Expected 'X' but got 'Y' (or similar runtime error from the generated parser)

The input data does not conform to the grammar defined by the `llparse-builder` graph, or there's a logical error in the state machine definition itself, leading to an unexpected token or state.

fix

Review your `llparse-builder` state machine definition. Trace the expected path for the problematic input. Use `llparse`'s debugging features for the generated C code to pinpoint where the parser diverges from expectations. Ensure `builder.error()` calls correctly handle unexpected inputs.

Upgrade

Version history

1.5.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/indutny/llparse-builder ↗

packagehttps://www.npmjs.com/package/llparse-builder ↗