parseman 0.1.0

package/README.md

@@ -0,0 +1,510 @@
+<p align="center">
+  <img src="assets/parseman.png" alt="Parmésan — 100% Pure Parsing" width="220" />
+</p>
+
+# Parmésan (PAR-zə-mahn)
+
+Write parsers with combinators, then let the bundler plugin compile them to optimized inline functions at build time — `charCodeAt` dispatch, `while` loops, zero allocation on failure paths. No generated boilerplate, no codegen step, no separate schema files.
+
+The same code runs without the plugin: the interpreter produces identical results. Use the macro build for production; skip it in tests and anywhere a bundler isn't in the picture.
+
+## Install
+
+```bash
+npm install parseman
+# pnpm add parseman
+```
+
+---
+
+## Quick start
+
+```ts
+import { literal, sequence, choice, regex, transform, parse } from 'parseman'
+
+const method  = choice(literal('GET'), literal('POST'), literal('PUT'), literal('DELETE'))
+const target  = regex(/[^\s]+/)
+const version = regex(/1\.[01]/)
+
+const requestLine = transform(
+  sequence(method, literal(' '), target, literal(' HTTP/'), version),
+  ([verb, , path, , ver]) => ({ verb, path, version: `HTTP/${ver}` })
+)
+
+parse(requestLine, 'GET /api/v1 HTTP/1.1')
+// { ok: true, value: { verb: 'GET', path: '/api/v1', version: 'HTTP/1.1' }, span: ... }
+```
+
+---
+
+## Macro mode
+
+Add the plugin once — your parser imports are evaluated and compiled at build time. The `parseman` import disappears from the bundle entirely.
+
+### 1. Register the plugin
+
+```ts
+// vite.config.ts
+import parseman from 'parseman/plugin'
+export default { plugins: [parseman()] }
+```
+
+```js
+// rollup.config.js
+import parseman from 'parseman/plugin'
+export default { plugins: [parseman.rollup()] }
+```
+
+```js
+// webpack.config.js
+const parseman = require('parseman/plugin')
+module.exports = { plugins: [parseman.webpack()] }
+```
+
+### 2. Import with `with { type: 'macro' }`
+
+```ts
+import { literal, sequence, choice, regex, transform } from 'parseman' with { type: 'macro' }
+```
+
+Same combinators, no other changes. The plugin walks the initializer, evaluates it at build time, and replaces it with an inline function.
+
+### What gets emitted
+
+```js
+// Before (source):
+const method = choice(literal('GET'), literal('POST'), literal('PUT'), literal('DELETE'))
+
+// After (bundle output):
+const method = function(input, _pos, _ctx) {
+  const _code = _pos < input.length ? input.codePointAt(_pos) : -1
+  if      (_code === 71) { /* G-E-T  */ }
+  else if (_code === 80) { /* P-O-S-T */ }
+  else if (_code === 68) { /* D-E-L-E-T-E */ }
+  else return { ok: false, expected: ['"GET"', '"POST"', ...], span: { start: _pos, end: _pos } }
+  ...
+}
+```
+
+Disjoint first characters → single `codePointAt` dispatch. Regex parsers → sticky `/pattern/y` hoisted to closure scope. No objects allocated on failure paths.
+
+### Debugging still works
+
+The plugin emits a precise source map via [magic-string](https://github.com/Rich-Harris/magic-string). Breakpoints set on the original `choice(...)` lines are hit when the compiled function runs; step-through shows original combinator source, not emitted charCode checks.
+
+If `with { type: 'macro' }` is stripped (older bundlers, test runners), the attribute is silently ignored and the interpreter runs instead — identical results, no errors.
+
+### What gets compiled
+
+Pure combinator trees — `literal`, `regex`, `sequence`, `choice`, `many`, `oneOrMore`, `optional`, `sepBy`, `transform`, `skip`. Parsers using `ref()` for recursion or that close over external variables stay as-is. The plugin compiles what it can and quietly leaves the rest alone.
+
+---
+
+## Combinators
+
+| Combinator | Description |
+|---|---|
+| `literal(s, opts?)` | Exact string match. `opts.caseInsensitive` for locale-aware comparison. |
+| `regex(pattern)` | Match a regex at the current position. Patterns are optimized via `regexp-tree`. |
+| `sequence(...parsers)` | Match all in order; returns a tuple `[v1, v2, ...]`. Skips trivia between terms when trivia is set. |
+| `choice(...parsers)` | Ordered alternatives (PEG — first match wins). Disjoint first chars → O(1) dispatch. |
+| `many(parser)` | Zero or more; compiles to a `while` loop. |
+| `oneOrMore(parser)` | One or more; fails if nothing matches. |
+| `optional(parser)` | Zero or one; returns `null` on no match. |
+| `sepBy(parser, sep)` | Zero or more `parser` separated by `sep`. |
+| `transform(parser, fn)` | Map the result: `fn(value, span) → newValue`. |
+| `skip(main, skipped)` | Match `main` then `skipped`; return `main`'s value. |
+| `parser(factory)` | Mutually recursive grammar rules — no forward declarations needed. |
+| `ref<T>()` | Low-level forward declaration slot (use `parser()` in most cases). |
+| `not(parser)` | Negative lookahead — succeeds (consuming nothing) when `parser` fails. |
+| `guard(predicate)` | Succeeds only when `predicate(ctx)` returns true; used for context-sensitive rules. |
+| `withCtx(extra, parser)` | Merge `extra` into the user context for the duration of `parser`. |
+| `recover(parser, sentinel)` | On failure, skip input until `sentinel` matches; returns a `CSTError` node. |
+| `scanTo(sentinel, skips?, opts?)` | Consume input up to (and including) `sentinel`, optionally skipping balanced pairs. |
+| `balanced(open, close)` | Match a balanced pair (e.g. `(…)`, `[…]`). Used as a `skip` argument to `scanTo`. |
+
+---
+
+## Whitespace and comment skipping
+
+Pass `trivia` to `parse()` and `sequence()` will automatically skip it between terms:
+
+```ts
+import { regex, sepBy, literal, parse } from 'parseman'
+
+const ws   = regex(/\s*/)
+const word = regex(/[a-z]+/)
+const list = sepBy(word, literal(','))
+
+parse(list, 'foo ,  bar , baz', { trivia: ws })
+// { ok: true, value: ['foo', 'bar', 'baz'], ... }
+```
+
+Multiple trivia types — whitespace and comments — combine with `choice()` and `many()`:
+
+```ts
+const lineComment  = sequence(literal('//'), regex(/[^\n]*/))
+const blockComment = sequence(literal('/*'), scanTo(literal('*/'), []))
+const trivia       = many(choice(regex(/\s+/), lineComment, blockComment))
+```
+
+Use `grammar(opts, root)` instead of the `parse()` trivia option when you want trivia only for a subtree within a larger parse:
+
+```ts
+import { grammar } from 'parseman'
+
+const jsonValue = grammar({ trivia: ws }, choice(object, array, str, num, bool, nil))
+```
+
+---
+
+## Ordered choice and keyword disambiguation
+
+`choice()` uses PEG ordered-choice semantics: first match wins. **Order matters.**
+
+For keywords — where `if` should not match the prefix of `ifdef` — use `not()`:
+
+```ts
+const wordChar = regex(/\w/)
+const keyword  = (s: string) => transform(sequence(literal(s), not(wordChar)), ([kw]) => kw)
+const ident    = regex(/[a-zA-Z_]\w*/)
+
+const token = choice(
+  keyword('if'),
+  keyword('else'),
+  keyword('return'),
+  ident,
+)
+```
+
+When alternatives share a prefix, put the longer one first:
+
+```ts
+// Wrong: choice(literal('in'), literal('instanceof')) — 'instanceof' never reached
+const op = choice(literal('instanceof'), literal('in'), literal('if'))
+```
+
+---
+
+## Recursive grammars
+
+Use `parser()` for mutually recursive rules. Pass a factory that receives all rule names as ready-to-use references and returns the definitions:
+
+```ts
+import { parser, choice, sequence, literal, sepBy, transform, regex } from 'parseman'
+import type { Combinator } from 'parseman'
+
+type JSON = null | boolean | number | string | JSON[] | Record<string, JSON>
+
+const ws = regex(/[ \t\n\r]*/)
+
+const { value } = parser<{ value: Combinator<JSON> }>(g => {
+  const comma = sequence(ws, literal(','), ws)
+
+  const array = transform(
+    sequence(literal('['), sepBy(g.value, comma), literal(']')),
+    ([, items]) => items as JSON[]
+  )
+  const pair = transform(
+    sequence(jsonString, literal(':'), g.value),
+    ([key,, val]) => [key, val] as [string, JSON]
+  )
+  const object = transform(
+    sequence(literal('{'), sepBy(pair, comma), literal('}')),
+    ([, pairs]) => Object.fromEntries(pairs) as Record<string, JSON>
+  )
+
+  return {
+    value: grammar(
+      { trivia: ws },
+      choice(object, array, jsonString, jsonNumber, jsonBool, jsonNull)
+    ) as Combinator<JSON>,
+  }
+})
+```
+
+`g.value` is a parser reference that works anywhere inside the factory regardless of order. Local helpers (`comma`, `pair`, `object`) that don't need to be cross-referenced can be plain `const`. Only put a rule in the returned object if other rules need to reach it as `g.xxx`.
+
+> **Macro note:** Recursive parsers can't be inlined as a single expression, so the plugin leaves them as-is — but you can still call `compile()` at runtime for the same speedups. The codegen emits mutually recursive named functions and handles cycles just fine. Non-recursive leaf parsers in the same file still get inlined.
+
+### `ref<T>()` — low-level forward declaration
+
+`parser()` is the right tool for most recursive grammars. `ref<T>()` is the lower-level primitive it uses internally, exposed for cases where you need a single forward slot outside of a `parser()` call:
+
+```ts
+const value = ref<JSON>()
+// ... build parsers that use value ...
+value.define(grammar({ trivia: ws }, choice(object, array, str, num, bool, nil)))
+```
+
+---
+
+## Class-based grammars
+
+For grammars that need automatic CST construction, incremental re-parsing, or custom AST nodes, extend `Parser`. Capital-letter rules produce named CST nodes; lowercase rules are transparent helpers whose terminals surface as leaves of the nearest enclosing rule.
+
+```ts
+import { Parser, parse, regex, literal, choice, sequence, many, sepBy } from 'parseman'
+import type { Refs } from 'parseman'
+
+class ExprParser extends Parser {
+  ws     = regex(/\s*/)
+  digits = regex(/[0-9]+/)
+  ident  = regex(/[a-zA-Z_]\w*/)
+
+  // Plain initializer when no cross-reference needed
+  Str    = sequence(literal('"'), regex(/[^"]*/), literal('"'))
+
+  // Thunk form for forward / mutual references
+  Num    = (g: Refs<ExprParser>) => g.digits
+  Id     = (g: Refs<ExprParser>) => g.ident
+  Add    = (g: Refs<ExprParser>) => sequence(g.Num, many(sequence(literal('+'), g.Num)))
+  Expr   = (g: Refs<ExprParser>) => choice(g.Add, g.Num, g.Id)
+}
+
+const expr = new ExprParser()
+const r = parse(expr.rule('Expr'), '1+2+3')
+// r.value is a CSTNode { _tag: 'node', type: 'Expr', span, children, savedContext }
+```
+
+### Inheritance
+
+Override any rule by redeclaring it in a subclass — subclass initializers run after the parent's, so the override wins automatically:
+
+```ts
+class JSXParser extends ExprParser {
+  // replace just the ident rule; everything else stays
+  ident = regex(/[a-zA-Z_$][\w$]*/)
+}
+```
+
+### Custom AST nodes (`buildNode`)
+
+Override `buildNode` to return your own node type instead of the default `CSTNode`:
+
+```ts
+import type { CSTLeaf, CSTError, CSTRawChild, Span } from 'parseman'
+
+type MyNode = { _tag: 'node'; type: string; span: Span; savedContext: unknown; children: MyNode[]; text: string }
+
+class MyParser extends Parser<MyNode> {
+  // ... rules ...
+
+  protected buildNode(
+    type: string,
+    span: Span,
+    children: ReadonlyArray<MyNode | CSTLeaf | CSTError>,
+    savedContext: unknown,
+    rawChildren: ReadonlyArray<CSTRawChild>,
+  ): MyNode {
+    return { _tag: 'node', type, span, savedContext, children: children as MyNode[], text: '...' }
+  }
+}
+```
+
+`children` contains the structural children (sub-nodes and leaf tokens, no trivia). `rawChildren` contains everything in parse order including trivia tokens — useful for whitespace-sensitive grammars.
+
+### Whitespace-sensitive rules with `rawChildren`
+
+When whitespace is semantically meaningful (e.g. CSS where `div p` is a descendant combinator but `div+p` is adjacent), inspect `rawChildren` inside `buildNode`:
+
+```ts
+import type { CSTTrivia } from 'parseman'
+
+class CssParser extends Parser<SelectorNode> {
+  ident     = regex(/[a-zA-Z-]+/)
+  Selector  = (g: Refs<CssParser>) => sequence(g.ident, g.ident)
+
+  protected buildNode(type, span, children, savedContext, rawChildren) {
+    if (type === 'Selector') {
+      // rawChildren: [Ident("div"), CSTTrivia(" "), Ident("p")]
+      const hasDescendant = rawChildren.some(c => c._tag === 'trivia')
+    }
+    return ...
+  }
+}
+
+// Trivia is set on parse() — the whitespace skip happens globally
+parse(css.rule('Stylesheet'), src, { trivia: many(choice(regex(/\s+/), comment)) })
+```
+
+`CSTTrivia` nodes only appear in `rawChildren`, never in `children`. Zero-length trivia matches (e.g. `\s*` at a non-whitespace position) are not emitted.
+
+### Incremental re-parsing
+
+`Parser.parse(ruleName, input)` returns a `ParseDoc` — an object holding the tree, any parse errors, and an `edit()` method for incremental re-parsing. The parser itself stays stateless; all the incremental state lives in the doc.
+
+```ts
+const css = new CSSParser()
+
+const doc = css.parse('Stylesheet', src)
+doc.tree    // CSTNode root, or null on failure
+doc.errors  // ParseFail[], empty on success
+doc.input   // the source string
+
+// subsequent edits return a new doc — old one is untouched
+// edit(from, to, replacement): select from→to in the old text, replace with replacement
+const doc2 = doc.edit(changeStart, changeStart + changeLength, newText)
+```
+
+`edit(from, to, replacement)` takes two byte offsets into the **old** text (`from` and `to`), plus the replacement string. Think of it as "highlight characters from→to, type replacement" — the same three things any editor already knows on every keystroke. Internally it runs `old.slice(0, from) + replacement + old.slice(to)`. It finds the smallest node containing the change, re-parses just that subtree using its saved context, and stops early when the new span end matches the expected position. O(changed region) amortized for typical edits. Nodes unaffected by the edit are structurally shared between old and new docs.
+
+Context-sensitive grammars work correctly: each CST node records a `ctx.user` snapshot at parse time (`savedContext`), so re-parsing resumes from the exact same state. Solid enough for a language server.
+
+**In an IDE extension**, hold one parser instance per language, one `ParseDoc` per open document. On each keystroke your editor gives you the changed range as byte offsets — pass those straight to `edit()`:
+
+```ts
+// VS Code example
+const parser = new CSSParser()
+const docs = new Map<string, ParseDoc<CSTNode>>()
+
+vscode.workspace.onDidOpenTextDocument(document => {
+  docs.set(document.uri.toString(), parser.parse('Stylesheet', document.getText()))
+})
+
+vscode.workspace.onDidChangeTextDocument(event => {
+  const uri = event.document.uri.toString()
+  let doc = docs.get(uri)!
+  for (const change of event.contentChanges) {
+    doc = doc.edit(change.rangeOffset, change.rangeOffset + change.rangeLength, change.text)
+  }
+  docs.set(uri, doc)
+  // walk doc.tree to emit diagnostics, folding ranges, semantic tokens, etc.
+})
+```
+
+---
+
+## Context-sensitive parsing
+
+`withCtx` and `guard` implement context-sensitive rules without mutating shared state.
+
+`withCtx(extra, parser)` merges `extra` into the user context for the duration of `parser`. `guard(predicate)` succeeds only when `predicate(ctx)` returns true, effectively gating a rule behind runtime context.
+
+```ts
+import { withCtx, guard, many, sequence, choice, literal, regex } from 'parseman'
+
+class LangParser extends Parser {
+  ws = regex(/\s*/)
+
+  Expr    = regex(/[a-z]+/)
+  Return  = (g: Refs<LangParser>) => sequence(
+    guard((ctx: { inFn?: boolean }) => ctx.inFn === true),
+    literal('return'),
+  )
+  Stmt    = (g: Refs<LangParser>) => choice(g.Return, g.Expr)
+  Body    = (g: Refs<LangParser>) => withCtx({ inFn: true }, many(sequence(g.Stmt, g.ws)))
+  Program = (g: Refs<LangParser>) => many(g.Body)
+}
+```
+
+`Return` is only reachable inside a `Body` because `guard` rejects it when `inFn` is not set. `ParseDoc.edit()` replays the correct context on incremental edits because `savedContext` captures the `inFn: true` snapshot at the node that originally set it.
+
+---
+
+## Error recovery
+
+`recover(parser, sentinel)` wraps a parser so that on failure it skips forward until `sentinel` matches, then returns a `CSTError` node instead of bailing on the whole parse. Error recovery is never pretty, but at least you can keep going.
+
+```ts
+import { recover, scanTo, balanced, literal } from 'parseman'
+
+// Skip to ';' if a statement fails to parse
+const stmt = recover(g.Stmt, literal(';'))
+
+// Consume everything up to '}', skipping balanced () and [] pairs
+const block = scanTo(literal('}'), [balanced(literal('('), literal(')')), balanced(literal('['), literal(']'))])
+```
+
+`scanTo(sentinel, skips?, opts?)` consumes input character-by-character until `sentinel` matches. Pass `skips` to skip over balanced pairs that might contain the sentinel character. Pass `opts.orEOF: true` to succeed at end-of-input if the sentinel is never found.
+
+---
+
+## Line / column tracking
+
+```ts
+const r = parse(myParser, 'hello\nworld', { trackLines: true })
+
+if (r.ok) {
+  r.span.startLine   // 1
+  r.span.startColumn // 1
+  r.span.endLine     // 2
+  r.span.endColumn   // 6
+}
+```
+
+Line lookup is O(log n) via binary search on a precomputed newline index built once per input string. When `trackLines` is false (the default), no index is built and spans carry only byte offsets.
+
+---
+
+## `compile()` — runtime compilation
+
+`compile()` runs the same optimizer as the plugin, but at runtime — handy when you're assembling a grammar dynamically, or just want the speed without a build step:
+
+```ts
+import { choice, literal, compile } from 'parseman'
+
+const compiled = compile(choice(literal('yes'), literal('no')))
+compiled.parse('yes', 0, { trackLines: false })  // { ok: true, value: 'yes', ... }
+compiled.source                                   // generated JS source string
+compiled.inlineExpression                         // self-contained expression (what the plugin inlines)
+```
+
+---
+
+## ParseResult types
+
+```ts
+type ParseOk<T>  = { ok: true;  value: T;   span: Span }
+type ParseFail   = { ok: false; expected: string[]; span: Span }
+type ParseResult<T> = ParseOk<T> | ParseFail
+
+type Span = {
+  start: number         // byte offset, inclusive
+  end: number           // byte offset, exclusive
+  startLine?: number    // 1-based; only when trackLines: true
+  startColumn?: number
+  endLine?: number
+  endColumn?: number
+}
+```
+
+### CST types
+
+```ts
+type CSTNode  = { _tag: 'node';  type: string; span: Span; children: CSTChild[]; savedContext: unknown }
+type CSTLeaf  = { _tag: 'leaf';  value: string; span: Span }
+type CSTError = { _tag: 'error'; type: string; span: Span; expected: string[]; children: CSTChild[]; savedContext: unknown }
+type CSTTrivia = { _tag: 'trivia'; value: string; span: Span }  // only in rawChildren
+
+type CSTChild    = CSTNode | CSTLeaf | CSTError
+type CSTRawChild = CSTNode | CSTLeaf | CSTTrivia | CSTError
+```
+
+---
+
+## Benchmarks
+
+Measured on Apple M2 Pro. Bars show µs per parse — shorter is faster.
+
+![JSON parsing benchmarks](assets/bench-json.svg)
+
+![CSV parsing benchmarks](assets/bench-csv.svg)
+
+Parmésan compiled edges out Peggy on small and medium JSON. At 12 kB Peggy pulls ahead by ~10% — it's been doing this a while. On CSV, where the grammar is non-recursive and fully inlines, Parmésan compiled wins going away.
+
+---
+
+## Developing
+
+```bash
+pnpm install
+pnpm test       # Vitest — interpreter + compiler parity + ordered-choice semantics
+pnpm typecheck  # TypeScript 7
+pnpm build      # ESM + CJS + .d.ts → dist/
+pnpm bench      # Parmésan vs Peggy vs Parsimmon vs Chevrotain
+```
+
+## License
+
+MIT © [Matthew Dean](https://github.com/matthew-dean)

package/dist/combinators/choice.d.ts

@@ -0,0 +1,15 @@
+import type { Combinator, GatedArm } from '../types.ts';
+type ArmParser<T> = T extends GatedArm<infer U> ? Combinator<U> : T extends Combinator<infer U> ? Combinator<U> : never;
+type UnionArms<T extends (Combinator<unknown> | GatedArm<unknown>)[]> = {
+    [K in keyof T]: ArmParser<T[K]>;
+}[number] extends Combinator<infer U> ? U : never;
+export declare function choice<T extends [Combinator<unknown> | GatedArm<unknown>, ...(Combinator<unknown> | GatedArm<unknown>)[]]>(...args: T): Combinator<UnionArms<T>>;
+/** Walk transform wrappers to find an inner literal's string value. */
+export declare function getCoreLiteralValue(p: Combinator<unknown>): string | null;
+/** Walk transform wrappers to find an inner regex's source/flags. */
+export declare function getCoreRegexDef(p: Combinator<unknown>): {
+    source: string;
+    flags: string;
+} | null;
+export {};
+//# sourceMappingURL=choice.d.ts.map

package/dist/combinators/choice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"choice.d.ts","sourceRoot":"","sources":["../../src/combinators/choice.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EAC+B,QAAQ,EAClD,MAAM,aAAa,CAAA;AAGpB,KAAK,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,KAAK,CAAA;AACvH,KAAK,SAAS,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI;KACrE,CAAC,IAAI,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAChC,CAAC,MAAM,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;AAEjD,wBAAgB,MAAM,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,EACxH,GAAG,IAAI,EAAE,CAAC,GACT,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAqH1B;AAwFD,uEAAuE;AACvE,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CAKzE;AAED,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAKhG"}

package/dist/combinators/first-set.d.ts

@@ -0,0 +1,8 @@
+import type { FirstSet } from '../types.ts';
+export declare function union(a: FirstSet, b: FirstSet): FirstSet;
+export declare function intersects(a: FirstSet, b: FirstSet): boolean;
+export declare function fromChar(code: number): FirstSet;
+export declare function fromRange(lo: number, hi: number): FirstSet;
+export declare function any(): FirstSet;
+export declare function empty(): FirstSet;
+//# sourceMappingURL=first-set.d.ts.map

package/dist/combinators/first-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"first-set.d.ts","sourceRoot":"","sources":["../../src/combinators/first-set.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEtD,wBAAgB,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAKxD;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,OAAO,CAS5D;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAE/C;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,QAAQ,CAE1D;AAED,wBAAgB,GAAG,IAAI,QAAQ,CAE9B;AAED,wBAAgB,KAAK,IAAI,QAAQ,CAEhC"}

package/dist/combinators/grammar.d.ts

@@ -0,0 +1,8 @@
+import type { Combinator, ParseResult } from '../types.ts';
+export type ParseOptions = {
+    trivia?: Combinator<unknown>;
+    trackLines?: boolean;
+};
+export declare function grammar<T>(opts: ParseOptions, root: Combinator<T>): Combinator<T>;
+export declare function parse<T>(parser: Combinator<T>, input: string, opts?: ParseOptions): ParseResult<T>;
+//# sourceMappingURL=grammar.d.ts.map

package/dist/combinators/grammar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammar.d.ts","sourceRoot":"","sources":["../../src/combinators/grammar.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAgB,WAAW,EAAE,MAAM,aAAa,CAAA;AAGxE,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,CAAA;IAC5B,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB,CAAA;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAuBjF;AAED,wBAAgB,KAAK,CAAC,CAAC,EACrB,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,EACrB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,YAAiB,GACtB,WAAW,CAAC,CAAC,CAAC,CAWhB"}

package/dist/combinators/guard.d.ts

@@ -0,0 +1,15 @@
+import type { Combinator } from '../types.ts';
+/**
+ * Zero-width assertion: succeeds (consuming nothing) only when `predicate`
+ * returns true for `ctx.user`. Fails otherwise.
+ *
+ * Intended for use inside sequence() to gate subsequent parsing on runtime
+ * context set with withCtx().
+ *
+ *   const returnStmt = sequence(
+ *     guard(ctx => (ctx as { inFn: boolean }).inFn),
+ *     literal('return'), optional(expr)
+ *   )
+ */
+export declare function guard(predicate: (user: unknown) => boolean): Combinator<null>;
+//# sourceMappingURL=guard.d.ts.map

package/dist/combinators/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/combinators/guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,MAAM,aAAa,CAAA;AAEpF;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,CAgB7E"}

package/dist/combinators/lazy.d.ts

@@ -0,0 +1,14 @@
+import type { Combinator } from '../types.ts';
+/**
+ * Defers parser construction until first use — necessary for recursive grammars
+ * where a parser references itself (e.g. JSON value contains JSON arrays/objects).
+ *
+ * The thunk is called once and the result cached. First-set metadata is
+ * approximated as 'any' since it's unknown at construction time; this means
+ * lazy parsers inside choice() won't get O(1) disjoint dispatch, but they
+ * will work correctly.
+ *
+ * The compiler treats lazy as a runtime fallback (can't inline recursive parsers).
+ */
+export declare function lazy<T>(thunk: () => Combinator<T>): Combinator<T>;
+//# sourceMappingURL=lazy.d.ts.map

package/dist/combinators/lazy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy.d.ts","sourceRoot":"","sources":["../../src/combinators/lazy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,MAAM,aAAa,CAAA;AAGpF;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAkBjE"}

package/dist/combinators/literal.d.ts

@@ -0,0 +1,6 @@
+import type { Combinator } from '../types.ts';
+export type LiteralOptions = {
+    caseInsensitive?: boolean;
+};
+export declare function literal(value: string, opts?: LiteralOptions): Combinator<string>;
+//# sourceMappingURL=literal.d.ts.map

package/dist/combinators/literal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"literal.d.ts","sourceRoot":"","sources":["../../src/combinators/literal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,MAAM,aAAa,CAAA;AAWpF,MAAM,MAAM,cAAc,GAAG;IAC3B,eAAe,CAAC,EAAE,OAAO,CAAA;CAC1B,CAAA;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,UAAU,CAAC,MAAM,CAAC,CAgDpF"}

package/dist/combinators/map.d.ts

@@ -0,0 +1,8 @@
+import type { Combinator } from '../types.ts';
+export declare function transform<T, U>(parser: Combinator<T>, fn: (value: T, span: {
+    start: number;
+    end: number;
+}) => U): Combinator<U>;
+export declare function skip<T, S>(main: Combinator<T>, skipped: Combinator<S>): Combinator<T>;
+export declare function trivia<T>(parser: Combinator<T>): Combinator<T>;
+//# sourceMappingURL=map.d.ts.map

package/dist/combinators/map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map.d.ts","sourceRoot":"","sources":["../../src/combinators/map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAA6B,MAAM,aAAa,CAAA;AAExE,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,EAC5B,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,EACrB,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,KAAK,CAAC,GACxD,UAAU,CAAC,CAAC,CAAC,CAWf;AAED,wBAAgB,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAarF;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAO9D"}

package/dist/combinators/not.d.ts

@@ -0,0 +1,13 @@
+import type { Combinator } from '../types.ts';
+/**
+ * Negative lookahead. Succeeds (consuming nothing) when `parser` fails;
+ * fails when `parser` succeeds.
+ *
+ * The standard way to match a keyword without also matching the prefix
+ * of a longer identifier:
+ *
+ *   const kwTrue = sequence(literal('true'), not(regex(/\w/)))
+ *   // matches "true" in "true && x" but NOT in "trueish" or "trueness"
+ */
+export declare function not(parser: Combinator<unknown>): Combinator<null>;
+//# sourceMappingURL=not.d.ts.map

package/dist/combinators/not.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"not.d.ts","sourceRoot":"","sources":["../../src/combinators/not.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAyC,MAAM,aAAa,CAAA;AAGpF;;;;;;;;;GASG;AACH,wBAAgB,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,CAmBjE"}

package/dist/combinators/parser.d.ts

@@ -0,0 +1,25 @@
+import type { Combinator } from '../types.ts';
+/**
+ * Define mutually recursive grammar parser without forward declarations.
+ *
+ * Pass a factory that receives all rule names as parser references (via a Proxy)
+ * and returns a record of parser definitions. parser() handles creating ref()
+ * placeholders and wiring them up — the user never sees ref() at all.
+ *
+ *   const { value } = parser(g => ({
+ *     value:  choice(g.object, g.array, str, num, bool, nil),
+ *     object: transform(sequence('{', sepBy(g.pair, ','), '}'), Object.fromEntries),
+ *     array:  transform(sequence('[', sepBy(g.value, ','), ']'), ([, items]) => items),
+ *     pair:   transform(sequence(g.key, literal(':'), g.value), ([k,, v]) => [k, v]),
+ *   }))
+ *
+ * Not every name in the factory must appear in the returned object — local helpers
+ * (like `comma`, `key`) can be plain const inside the factory and composed normally.
+ * Only names that OTHER parser reference via `g.xxx` need to be in the returned record.
+ *
+ * TypeScript: use an explicit type parameter for full type safety on `g`:
+ *   parser<{ value: Combinator<JSONValue>; array: Combinator<JSONValue[]> }>(g => ({ ... }))
+ * Without it, `g.*` accesses are typed as `any` but the return is still inferred.
+ */
+export declare function parser<T extends Record<string, Combinator<unknown>>>(factory: (self: any) => T): T;
+//# sourceMappingURL=parser.d.ts.map

package/dist/combinators/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/combinators/parser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAG7C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,EAClE,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,GACxB,CAAC,CAmCH"}