parseman 0.24.0 → 0.25.0

package/README.md

@@ -110,7 +110,7 @@ Parséman includes benchmarks against several JavaScript/TypeScript parser libra
 
 **When parsing to JS values** — objects, row arrays, AST nodes — **Parséman's macro build is the fastest general-purpose JS parser we benchmark**, beating [Peggy](https://peggyjs.org/), [Parsimmon](https://github.com/jneen/parsimmon), [Chevrotain](https://chevrotain.io/), [Nearley](https://nearley.js.org/), and [Jison](https://github.com/zaach/jison) at every grammar and size. The only thing that edges it out is a purpose-built native like `JSON.parse`; for anything that *doesn't* have a built-in, Parséman is the one to beat.
 
-For **syntax tree building**, the compiled CST path (macro build) beats [Lezer](https://lezer.codemirror.net/) on the JSON CST fixture too — while producing a richer object tree with spans and trivia. For **incremental re-parse**, the two trade places by edit type: Parséman's `parseDoc` is ~300× faster than a full reparse on in-place value edits (and ahead of Lezer), while Lezer's buffer reuse wins on structural edits. Full breakdown in the [benchmarks guide](https://matthew-dean.github.io/parseman/guide/benchmarks).
+For **syntax tree building**, the compiled CST path (macro build) beats [Lezer](https://lezer.codemirror.net/) on the JSON CST fixture too — while producing a richer object tree with spans and trivia. For **incremental re-parse**, Parséman's `parseDoc` stores parent-relative spans so in-place value edits are ~110× faster than a full reparse and ~20× ahead of Lezer; structural edits (inserting/removing a whole list element) reuse the collection's untouched tail and land within a few × of Lezer's buffer reuse rather than at full-reparse cost. Full breakdown in the [benchmarks guide](https://matthew-dean.github.io/parseman/guide/benchmarks).
 
 Measured on Apple M4 Pro. Bars show µs per parse — shorter is faster. Refresh: `pnpm bench:svg` (benchmarks chart parsers and updates `assets/bench-*.svg`).
 

package/dist/cst/relative-spans.d.ts

@@ -40,6 +40,37 @@ export declare function absoluteSpanAt(root: RelNode, path: readonly number[]):
     start: number;
     end: number;
 };
+/**
+ * A CST child as far as span projection cares: a nested span + optional children.
+ * `children` is typed loosely (`unknown[]`) so the real heterogeneous CST unions
+ * (nodes, leaves, error nodes — a leaf has no `children`) satisfy it directly.
+ */
+type Spanned = {
+    readonly span: {
+        readonly start: number;
+        readonly end: number;
+    };
+    readonly children?: readonly unknown[];
+};
+/**
+ * Rewrite a CST subtree's spans to be RELATIVE to `parentBase` (the absolute
+ * start of the node's parent; root base = 0). Each child's own children are
+ * relativized against *this* node's absolute start. Preserves every other field
+ * (`_tag`, `type`, `state`, leaf `value`, …) by shallow spread.
+ */
+export declare function relativizeCST<T extends Spanned>(node: T, parentBase?: number): T;
+/** Reconstruct absolute CST spans from a relative subtree. Inverse of `relativizeCST`. */
+export declare function absolutizeCST<T extends Spanned>(node: T, parentBase?: number): T;
+/**
+ * Absolute span of the CST node at `path` (child indices from the root),
+ * accumulating the base as it descends — O(path length), no full absolutize.
+ * The relative-form cursor for a positioned CST: query one node's absolute
+ * position without materializing the whole tree.
+ */
+export declare function absoluteSpanCST(root: Spanned, path: readonly number[]): {
+    start: number;
+    end: number;
+};
 /** Naive absolute reshift (baseline): shift every offset >= `at` by `delta`. */
 export declare function shiftAbsolute(node: AbsNode, at: number, delta: number): AbsNode;
 /**
@@ -53,4 +84,5 @@ export declare function shiftAbsolute(node: AbsNode, at: number, delta: number):
 export declare function applyEdit(root: RelNode, at: number, delta: number, stats?: {
     allocated: number;
 }): RelNode;
+export {};
 //# sourceMappingURL=relative-spans.d.ts.map

package/dist/cst/relative-spans.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relative-spans.d.ts","sourceRoot":"","sources":["../../src/cst/relative-spans.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,gEAAgE;AAChE,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAA;CACtC,CAAA;AAED,qFAAqF;AACrF,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAA;CACtC,CAAA;AAED,yDAAyD;AACzD,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,SAAI,GAAG,OAAO,CAMjE;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,SAAI,GAAG,OAAO,CAOjE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAUrG;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAQ/E;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,OAAO,EACb,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAC5B,OAAO,CAGT"}
+{"version":3,"file":"relative-spans.d.ts","sourceRoot":"","sources":["../../src/cst/relative-spans.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,gEAAgE;AAChE,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAA;CACtC,CAAA;AAED,qFAAqF;AACrF,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAA;CACtC,CAAA;AAED,yDAAyD;AACzD,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,SAAI,GAAG,OAAO,CAMjE;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,SAAI,GAAG,OAAO,CAOjE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAUrG;AAYD;;;;GAIG;AACH,KAAK,OAAO,GAAG;IACb,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;CACvC,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,UAAU,SAAI,GAAG,CAAC,CAO3E;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,CAAC,SAAS,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,UAAU,SAAI,GAAG,CAAC,CAO3E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAUtG;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAQ/E;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,OAAO,EACb,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAC5B,OAAO,CAGT"}

package/dist/functional/doc.d.ts

@@ -1,12 +1,19 @@
 /**
  * Incremental parse document — incremental re-parse over a rules() registry.
  */
-import type { ParseContext, ParseFail, ParseResult } from '../types.ts';
+import type { Combinator, ParseContext, ParseFail, ParseResult } from '../types.ts';
 import type { NodeLike, CSTLeaf, CSTError } from '../cst/types.ts';
 /** A single compiled (or interpreted) rule: parse from `pos`, producing node `N`. */
 export type RuleFn<N> = (input: string, pos: number, ctx: ParseContext) => ParseResult<N>;
-/** Rule name → parser function. This is exactly the shape `rules()` returns. */
-export type Registry<N> = Record<string, RuleFn<N>>;
+/**
+ * Rule name → parser. Each entry is either a bare parse function or a
+ * `Combinator` (what `rules()` returns). Passing the `rules()` combinators
+ * directly lets `.edit()` inspect the grammar — required for **sound** structural
+ * list-reuse (see `structuralReuse`): only a rule the grammar proves is a genuine
+ * repetition is ever spliced. A bare-function registry still parses correctly; it
+ * just can't be structurally reused (the splice is skipped, never guessed).
+ */
+export type Registry<N> = Record<string, RuleFn<N> | Combinator<N>>;
 export type ParseDocOptions<N extends NodeLike> = {
     /** Initial grammar state threaded into ctx.state for the root parse. */
     state?: unknown;
@@ -23,11 +30,48 @@ export type ParseDocOptions<N extends NodeLike> = {
      * own builders (eval mode).
      */
     build?: ParseContext['build'];
+    /**
+     * Enable structural list-reuse: on a length-changing *structural* edit (adding
+     * or removing a whole element in a collection) that would otherwise force a full
+     * reparse, reparse only the disturbed span and reuse the collection's untouched
+     * tail elements by identity — turning an insert near the top of a large list from
+     * O(list) into O(edit + trailing siblings).
+     *
+     * OFF by default because it is sound only when a rule whose CST children form a
+     * homogeneous, separator-delimited element list is a genuine REPETITION
+     * (`many` / `sepBy` / `oneOrMore`), not a fixed-arity sequence of same-typed
+     * tokens (e.g. `Triple = Num ',' Num ',' Num`) — the two are structurally
+     * indistinguishable without the grammar, and splicing the latter would accept an
+     * element count it shouldn't. Turn it on when your list rules are true
+     * repetitions (the common case: JSON arrays/objects, CSS value lists, argument
+     * lists). Every splice is still guarded (exact tiling + lookahead probe +
+     * stateless-tail check) and falls back to a full, correct reparse when unproven;
+     * the flag only authorises *attempting* the reuse.
+     */
+    structuralReuse?: boolean;
 };
 export interface ParseDoc<N extends NodeLike> {
+    /**
+     * The parse tree with PARENT-RELATIVE spans — each node's `span` is relative to
+     * its parent's start (root base 0). This is the shareable representation: a
+     * length-changing `.edit()` keeps every untouched subtree shared by identity,
+     * and reading the tree is O(1) (no offset rewrite). For absolute positions use
+     * the O(depth) cursor `spanAt(path)`, or `absolutizeCST(doc.tree)` to
+     * materialize the whole absolute tree. A fresh non-incremental `node().parse()`
+     * result is unchanged — still absolute.
+     */
     readonly tree: N | null;
     readonly errors: ParseFail[];
     readonly input: string;
+    /**
+     * Absolute span of the node at `path` (child indices from the root) — O(depth),
+     * without materializing the absolute tree. The projection cursor for the
+     * relative representation; use it for spot queries on a large incremental doc.
+     */
+    spanAt(path: readonly number[]): {
+        start: number;
+        end: number;
+    };
     /**
      * Incrementally re-parse after a text change. `from`/`to` are byte offsets in
      * the OLD input; `replacement` fills that range (editor change-event shape).
@@ -47,6 +91,12 @@ export interface ParseDoc<N extends NodeLike> {
  * probe results with.
  */
 export declare function structurallyEqual(a: unknown, b: unknown): boolean;
+/**
+ * The relative (parent-offset) tree backing a doc. Currently identical to the
+ * public `doc.tree` (which is relative); kept as a named internal handle for the
+ * reuse-metric tests, which assert on the shareable representation explicitly.
+ */
+export declare function relTreeOf<N extends NodeLike>(doc: ParseDoc<N>): N | null;
 /**
  * Parse `input` from `rootRule` and wrap the result in a ParseDoc that can
  * be incrementally re-parsed via `.edit()`.

package/dist/functional/doc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../../src/functional/doc.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACvE,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAElE,qFAAqF;AACrF,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,KAAK,WAAW,CAAC,CAAC,CAAC,CAAA;AAEzF,gFAAgF;AAChF,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAA;AAEnD,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,QAAQ,IAAI;IAChD,wEAAwE;IACxE,KAAK,CAAC,EAAE,OAAO,CAAA;IACf;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,GAAG,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;IACzE;;;;;OAKG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC,OAAO,CAAC,CAAA;CAC9B,CAAA;AAED,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,QAAQ;IAC1C,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,CAAA;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB;;;;;;;;;OASG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAA;CACjE;AA6GD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAsBjE;AAyID;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,QAAQ,EACzC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EACrB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,eAAe,CAAC,CAAC,CAAM,GAC5B,QAAQ,CAAC,CAAC,CAAC,CASb"}
+{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../../src/functional/doc.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAmB,MAAM,aAAa,CAAA;AACpG,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAGlE,qFAAqF;AACrF,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,KAAK,WAAW,CAAC,CAAC,CAAC,CAAA;AAEzF;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;AAiEnE,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,QAAQ,IAAI;IAChD,wEAAwE;IACxE,KAAK,CAAC,EAAE,OAAO,CAAA;IACf;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,GAAG,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;IACzE;;;;;OAKG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC,OAAO,CAAC,CAAA;IAC7B;;;;;;;;;;;;;;;;;OAiBG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;CAC1B,CAAA;AAED,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,QAAQ;IAC1C;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,CAAA;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;IAC/D;;;;;;;;;OASG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAA;CACjE;AA6TD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAsBjE;AAwND;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,QAAQ,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAExE;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,QAAQ,EACzC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EACrB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,eAAe,CAAC,CAAC,CAAM,GAC5B,QAAQ,CAAC,CAAC,CAAC,CAWb"}