Grammar Well

Grammar Well is a cross-platform compiler, parser, and/or interpreter. It originated as a port of the popular library Nearley to TypeScript but has since evolved to include additional functionality, such as a built-in lexer and support for various parsing algorithms including LR0 and CKY. It also offers a range of quality of life features.

Check out the documentation at https://grammar-well.xyz/

Quick Start

Install

npm i grammar-well

Example

import { Compile, Parse } from 'grammar-well';

const source = `
import * from whitespace;

lexer {
	start: "json"

	[json]
		- import whitespace
		- when r:{-?(?:[0-9]|[1-9][0-9]+)(?:\.[0-9]+)?(?:[eE][-+]?[0-9]+)?\b} tag "number"
		- when r:{"(?:\\["bfnrt/\\]|\\u[a-fA-F0-9]{4}|[^"\\])*"} tag "string"
		- when "{" tag "{"
		- when "}" tag "}"
		- when "[" tag "["
		- when "]" tag "]"
		- when "," tag ","
		- when ":" tag ":"
		- when "true" tag "true"
		- when "false" tag "false"
		- when "null" tag "null"

}

grammar {
	start: "json"

	[json]
		| _ (object | array) _ => ( $1[0] )

	[object]
		| "{" _ "}" => ( {} )
		| "{" _ pair (_ "," _ pair)* _ "}" => \${ extractObject }

	[array]
		| "[" _ "]" => ( [] )
		| "[" _ value (_ "," _ value)* _ "]" => \${ extractArray }

	[value]
		| object => ( $0 )
		| array => ( $0 )
		| number => ( $0 )
		| string => ( $0 )
		| "true" => ( true )
		| "false" => ( false )
		| "null" => ( null )

	[number]
		| <number> => ( parseFloat($0.value) )

	[string]
		| <string> => ( JSON.parse($0.value) )

	[pair]
		| key@k _ ":" _ value@v => ( [$k, $v] )

	[key]
		| string => ( $0 )

}

on:import {
    function extractPair(kv, output) {
        if(kv[0]) { output[kv[0]] = kv[1]; }
    }

    function extractObject({data}) {
        let output = {};

        extractPair(data[2], output);

        for (let i in data[3]) {
            extractPair(data[3][i][3], output);
        }

        return output;
    }

    function extractArray({data}) {
        let output = [data[2]];

        for (let i in data[3]) {
            output.push(data[3][i][3]);
        }

        return output;
    }
}`

const javascriptsource = await Generate(source, {
    output: {
        name: 'grammar',
        format: 'typescript',
        artifacts: {
            lexer: true,
            grammar: true
        }
    }
});

Performance & Scalability Report: The 100k "Grammar Well"

This sections documents the engine's performance limits when processing extreme-depth telemetry (100,000 nested nodes).

Infrastructure Profile

To ensure absolute resource isolation, tests were conducted on a dedicated high-memory cloud instance.

| Category | Specification | | :----------- | :--------------------------------------------------- | | Provider | DigitalOcean (Memory-Optimized Droplet) | | Compute | 4 Dedicated vCPUs (Intel® Xeon® Gold 6248 @ 2.50GHz) | | Memory | 32 GB Dedicated RAM | | Storage | 100 GB NVMe SSD | | Runtime | Node.js v25.2.1 on Linux 6.8.0 |

V8 Runtime Configuration

Processing 100,000 nodes at depth generates a recursive call-stack that exceeds default Node.js and OS boundaries.

# 1. Unlock the OS-level stack limit
ulimit -s unlimited

# 2. Open a persistent session to prevent SSH timeout crashes
screen -L -Logfile benchmark.log -S benchmark

# 3. Launch the suite with tuned V8 stack/heap flags to stabilize the environment and prevent Segmentation Faults:
npm run benchmark -- --stack-size=65536 --max-old-space-size=28000

Workflow Tip: Use CTRL + A + D to detach the screen. You can safely close your terminal or monitor the output via:

tail -f benchmark.log

JSON (1K Nodes)

| | Parsing Cold | Parsing Hot | Stability (CV) | Memory Used | Parsing Iterations | | --------------------------- | ------------ | ------------- | -------------- | ----------- | ------------------ | | Lexer Only | 6.17 | 5.22 (±1.92) | 36.8% | 24.12 MB | 100 | | Earley Eager | 40.36 | 37.15 (±5.37) | 14.5% | 45.25 MB | 100 | | Earley Lazy | 46.27 | 42.59 (±4.75) | 11.1% | 48.30 MB | 100 | | Earley Eager (Zero Epsilon) | 39.44 | 36.27 (±4.93) | 13.6% | 40.29 MB | 100 | | Earley Lazy (Zero Epsilon) | 39.19 | 35.67 (±6.31) | 17.7% | 41.65 MB | 100 | | LR0 (Zero Epsilon) | 19.72 | 12.96 (±3.28) | 25.3% | 25.60 MB | 100 |

JSON (10K Nodes)

| | Parsing Cold | Parsing Hot | Stability (CV) | Memory Used | Parsing Iterations | | --------------------------- | ------------ | --------------- | -------------- | ----------- | ------------------ | | Lexer Only | 32.27 | 31.49 (±2.17) | 6.9% | 56.12 MB | 100 | | Earley Eager | 855.60 | 825.14 (±17.17) | 2.1% | 270.32 MB | 100 | | Earley Lazy | 759.63 | 750.13 (±11.63) | 1.5% | 186.92 MB | 100 | | Earley Eager (Zero Epsilon) | 246.72 | 236.36 (±7.41) | 3.1% | 85.53 MB | 100 | | Earley Lazy (Zero Epsilon) | 267.39 | 262.59 (±6.62) | 2.5% | 94.25 MB | 100 | | LR0 (Zero Epsilon) | 86.06 | 85.09 (±4.86) | 5.7% | 53.52 MB | 100 |

JSON (50K Nodes)

| | Parsing Cold | Parsing Hot | Stability (CV) | Memory Used | Parsing Iterations | | --------------------------- | ------------ | ------------------ | -------------- | ----------- | ------------------ | | Lexer Only | 128.11 | 128.23 (±4.82) | 3.8% | 206.47 MB | 10 | | Earley Eager | 15647.68 | 15585.77 (±299.41) | 1.9% | 5365.89 MB | 10 | | Earley Lazy | 14665.24 | 14710.48 (±139.89) | 1.0% | 1239.93 MB | 10 | | Earley Eager (Zero Epsilon) | 1256.36 | 1216.06 (±21.39) | 1.8% | 161.81 MB | 10 | | Earley Lazy (Zero Epsilon) | 1388.78 | 1342.75 (±13.41) | 1.0% | 229.55 MB | 10 | | LR0 (Zero Epsilon) | 431.23 | 422.55 (±11.36) | 2.7% | 143.34 MB | 10 |

JSON (100k Nodes)

| | Parsing Cold | Parsing Hot | Stability (CV) | Memory Used | Parsing Iterations | | --------------------------- | ------------ | ---------------- | -------------- | ----------- | ------------------ | | Lexer Only | 226.86 | 224.91 (±6.51) | 2.9% | 281.19 MB | 10 | | Earley Eager (Zero Epsilon) | 2259.98 | 2258.16 (±22.03) | 1.0% | 227.75 MB | 10 | | Earley Lazy (Zero Epsilon) | 2569.49 | 2603.80 (±26.03) | 1.0% | 353.09 MB | 10 | | LR0 (Zero Epsilon) | 717.48 | 753.08 (±17.29) | 2.3% | 176.64 MB | 10 |