{"id":13472,"library":"llparse-builder","title":"LLParse Builder","description":"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.","status":"active","version":"1.5.2","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/indutny/llparse-builder","tags":["javascript","llparse","builder","llvm","bitcode","typescript"],"install":[{"cmd":"npm install llparse-builder","lang":"bash","label":"npm"},{"cmd":"yarn add llparse-builder","lang":"bash","label":"yarn"},{"cmd":"pnpm add llparse-builder","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary class for constructing parser graphs. Uses named exports, not default.","wrong":"const Builder = require('llparse-builder');","symbol":"Builder","correct":"import { Builder } from 'llparse-builder';"},{"note":"Used for defining actions and operations within the parser's state machine, typically accessed via a `builder` instance.","wrong":"import { LLParseCode } from 'llparse-builder';","symbol":"Code","correct":"import { Code } from 'llparse-builder';"},{"note":"Represents a state node in the parser graph. Often returned by builder methods like `builder.node()`.","symbol":"Node","correct":"import { Node } from 'llparse-builder';"}],"quickstart":{"code":"import { Builder, Code } from 'llparse-builder';\n\ninterface ParserContext {\n  onComplete: () => void;\n  onData: (char: number) => void;\n}\n\nconst builder = new Builder<ParserContext>('simple_parser');\n\nconst start = builder.node('start');\nconst gotA = builder.node('got_a');\nconst gotB = builder.node('got_b');\nconst end = builder.node('end');\n\n// Define custom functions that will be invoked in the C parser\nbuilder.addFunction('on_complete', 'void');\nbuilder.addFunction('on_data', 'void', ['uint8_t ch']);\n\n// Error codes for the parser\nbuilder.addError('ERR_INVALID_CHAR', 1);\n\nstart\n  .match('A', gotA)\n  .otherwise(builder.error(builder.errors.ERR_INVALID_CHAR));\n\ngotA\n  .match('B', gotB)\n  .otherwise(builder.error(builder.errors.ERR_INVALID_CHAR));\n\ngotB\n  .match('C', end)\n  .otherwise(builder.error(builder.errors.ERR_INVALID_CHAR));\n\nend\n  .invoke(builder.code.invoke('on_complete'))\n  .span(builder.code.span('on_data')) // Example of spanning some data\n  .skip(start); // Loop back to start for continuous parsing\n\n// Build the parser graph (this doesn't generate C code, just the internal representation)\nconst parserGraph = builder.build();\n\nconsole.log('Parser graph built successfully. It can now be used with `llparse` to generate C code.');\n// console.log(parserGraph.print()); // For debugging the graph structure\n","lang":"typescript","description":"Demonstrates how to define a simple state machine parser for the sequence 'ABC' using the Builder API, including custom functions and error handling."},"warnings":[{"fix":"Understand that `llparse-builder` is part of a multi-stage process. You will need `llparse` and a C compiler for a complete solution.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Plan your parser's state machine meticulously. Analyze input patterns and optimize for common cases. Consider tools for visualizing state machines if available.","message":"While `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"TypeScript compiler cannot locate the package's type definitions, possibly due to incorrect installation or missing `tsconfig.json` settings.","error":"error TS2307: Cannot find module 'llparse-builder' or its corresponding type declarations."},{"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.","cause":"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).","error":"TypeError: builder.build is not a function"},{"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.","cause":"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.","error":"Parsing error: Expected 'X' but got 'Y' (or similar runtime error from the generated parser)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"_links":{"self":"https://checklist.day/api/registry/llparse-builder","v1":"https://checklist.day/v1/registry/llparse-builder","v1_install":"https://checklist.day/v1/registry/llparse-builder/install","v1_imports":"https://checklist.day/v1/registry/llparse-builder/imports","v1_compatibility":"https://checklist.day/v1/registry/llparse-builder/compatibility","v1_quickstart":"https://checklist.day/v1/registry/llparse-builder/quickstart","docs":"https://checklist.day/docs"}}