Registry / web-framework / bnf-parser

bnf-parser

JSON →
library4.1.3jsnpmunverified

bnf-parser is a deterministic compiler/parser library for Backus-Naur Form (BNF) grammars, currently at version 4.1.3. It differentiates itself by compiling BNF definitions directly into WebAssembly modules, enabling high-performance parsing. This compilation process also generates TypeScript type definitions for the resulting Abstract Syntax Tree (AST), making it easier to work with parsed outputs in type-safe environments. The compiled WebAssembly artifacts are platform-agnostic, capable of running wherever `WebAssembly.Instance()` is supported, and are bundled into a single JavaScript file for easy integration with bundlers. The library primarily functions as a `devDependency`, with its `bnf-compile` CLI tool generating standalone parser artifacts that do not require `bnf-parser` as a runtime dependency. Releases appear to be frequent, with several patch versions addressing memory management, compatibility, and bug fixes since the major v4.0.0 release.

npm install bnf-parser
INSTALL
IMPORT
SIG · BNF-PARSER
B
bnf-parser
web-frameworkjavascriptv4.1.3
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Parser
import * as syntax from './bnf/your_syntax_name.js';
const syntax = require('./bnf/your_syntax_name.js');
For parsers generated by `bnf-compile`, import the specific generated module. `bnf-parser` is ESM-only since v4.0.0, so CommonJS `require` will fail.
ParseFunction
import { Parse_Program } from './bnf/your_syntax_name.js';
The generated parser exports a function named 'Parse_EntryPointName' where 'EntryPointName' is your BNF's root rule (e.g., 'Program').
Legacy API
import { Parse } from 'bnf-parser/legacy';
import { Parse } from 'bnf-parser';
Since v4.0.0, all previous APIs were moved under the `legacy` namespace. Direct import from `bnf-parser` will not expose the older API.

This quickstart demonstrates how to compile a BNF grammar into a WebAssembly parser using the `bnf-compile` CLI tool and then import and utilize the generated TypeScript parser to process an input string and inspect its Abstract Syntax Tree (AST).

import * as fs from 'node:fs'; import * as path from 'node:path'; import { execSync } from 'node:child_process'; // 1. Define your BNF grammar const bnfContent = `program ::= chunk+ ; chunk ::= "a"+ "b"+ ;`; const bnfFilePath = path.join(process.cwd(), 'syntax.bnf'); fs.writeFileSync(bnfFilePath, bnfContent); // 2. Compile the BNF to a WebAssembly parser using the CLI // This is typically run as a build step or dev script try { console.log('Compiling BNF...'); execSync(`npx bnf-compile ${bnfFilePath} --outDir ./bnf-output`, { stdio: 'inherit' }); console.log('Compilation successful!'); } catch (error) { console.error('BNF compilation failed:', error.message); process.exit(1); } // 3. Import and use the generated parser // The path should match your --outDir and BNF file name import('./bnf-output/syntax.js').then(syntax => { const inputString = "abbaabab"; console.log(`Parsing input: "${inputString}"`); const tree = syntax.Parse_Program(inputString).root; console.log('Parsed AST:', JSON.stringify(tree, null, 2)); const firstChunk = tree.value[0]; if (firstChunk && firstChunk.type === 'Term_chunk') { console.log(`Type of first chunk: ${firstChunk.type}`); const firstBs = firstChunk.value[1]; // Assuming chunk is ['a+', 'b+'] if (firstBs && Array.isArray(firstBs.value)) { const bCount = firstBs.value.length; console.log(`Count of 'b's in the first 'b+' sequence: ${bCount}`); } } }).catch(error => { console.error('Failed to import or use generated parser:', error); });
bnf-compile --version
Debug
Known issues
breakingVersion 4.0.0 introduced significant breaking changes, including moving all previous APIs to a new `legacy` namespace and changing the package type to 'module', making it ESM-only. Existing `require()` statements or direct imports of older APIs will no longer work without modification.
fix
Update imports to use `import { Symbol } from 'bnf-parser/legacy';` for older APIs. For new compilation-based workflows, use `npx bnf-compile` and import the generated ES module. Ensure your project is configured for ESM or use a bundler.
affects: >=4.0.0
gotchaPrior to version 4.1.1, the WebAssembly module could experience memory overgrowth, potentially leading to crashes or unexpected behavior, especially with long or complex input strings or grammars that involve extensive backtracking.
fix
Upgrade to `bnf-parser@4.1.1` or newer. If issues persist with extremely large inputs, consider optimizing your BNF grammar to reduce complexity or segmenting inputs if feasible.
affects: <4.1.1
gotchaThe `bnf-parser` package is designed to be a `devDependency`. The primary workflow involves using its CLI (`bnf-compile`) to generate standalone parser artifacts. These generated artifacts do not require `bnf-parser` as a runtime dependency in your production bundles.
fix
Install `bnf-parser` with `--save-dev`. Ensure your build process properly includes the `bnf-compile` step and that your runtime code only imports the generated parser files, not the `bnf-parser` library directly.
affects: >=4.0.0
gotchaEarly v4.x versions (pre-4.0.5) had issues with hexadecimal character encoding in literals (e.g., `\x6b`) within BNF definitions and the `bnf-compile` CLI could crash when provided with invalid starting paths.
fix
Upgrade to `bnf-parser@4.0.5` or newer to ensure correct handling of hexadecimal literals and robust CLI behavior.
affects: <4.0.5
Errors
Common errors & fixes
TypeError: require is not a function
Attempting to import `bnf-parser` or its generated artifacts using CommonJS `require()` syntax in a module context after the package transitioned to ESM in v4.0.0.
fix
Update your import statements to use ES module syntax (e.g., `import * as syntax from './path/to/parser.js';`) and ensure your project's `package.json` is configured for ES modules (`"type": "module"`) or your bundler is correctly configured for ESM.
WebAssembly.RuntimeError: out of memory
The WebAssembly parser attempted to allocate more memory than available, often due to extremely large input strings, highly recursive grammars, or a bug in older versions of the parser module.
fix
Upgrade `bnf-parser` to `4.1.1` or newer to benefit from memory usage fixes. Review your BNF grammar for potential infinite recursion or excessively complex rules. For very large inputs, consider processing them in smaller chunks if your grammar allows.
Count not working when applied directly to a range (i.e. "a"->"z"+)
A specific bug in `bnf-parser` v4.0.0 caused incorrect parsing or counting behavior when applying repetition operators directly to character ranges.
fix
Upgrade to `bnf-parser@4.0.1` or newer, as this bug was addressed shortly after the v4.0.0 release.
Upgrade
Version history
4.1.3latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
11 hits · last 30 days
node
8
OpenAI (training)
1
Resources
bnf-parser — npm install bnf-parser · libregistry