{"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,"search_vec":"'1.5.2':11 'abil':119 'abstract':121 'activ':99 'addit':160 'api':32 'appear':151 'applic':83 'base':141 'binary/text':90 'bitcod':69,170 'builder':2,6,77,168 'built':73 'c':63,140,145 'c-base':139 'cadenc':150 'care':112 'code':64,146 'compil':43 'complex':123 'consum':48 'creation':22 'critic':82 'current':8 'defin':34 'depend':108 'design':18 'develop':132 'differenti':114 'direct':147 'driven':154 'emit':60 'enabl':130 'extrem':136 'facilit':20 'factor':115 'featur':159 'first':16 'fluent':31 'generat':58,129 'github':104 'graph':46 'high':25,61 'high-perform':24 'http':85 'javascript':166 'javascript/typescript':131 'level':127 'leverag':134 'librari':7 'lie':116 'like':84 'llpars':1,5,51,53,76,167 'llparse-build':4,75 'llvm':68,169 'logic':39 'low':126 'low-level':125 'machin':36 'maintain':100 'make':70 'necessari':156 'nodej':103 'ongo':111 'optim':62 'organ':105 'packag':17 'paramount':95 'pars':38,87 'parser':27,57,72,128,142 'perform':26,81,137 'performance-crit':80 'project':97 'protocol':86,91 'provid':29 'rather':161 'recent':107 'reflect':110 'releas':149 'runtim':52 'schedul':165 'speed':93 'state':35 'strict':164 'structur':47 'suitabl':78 'typescript':15,171 'typescript-first':14 'updat':109,157 'version':10 'via':67 'webassembl':66 'within':101 'without':143 'write':144","created_at":"2026-04-20T01:54:41.006044+00:00","updated_at":"2026-04-20T01:54:41.006044+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/indutny/llparse-builder","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/llparse-builder","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}