prefix-safe-json 0.0.1-alpha.0

package/dist/diagnostics/factory.d.ts

@@ -0,0 +1,8 @@
+import type { Diagnostic } from "../types.js";
+type Severity = Diagnostic["severity"];
+/**
+ * Creates a Diagnostic object.
+ */
+export declare function createDiagnostic(code: string, severity: Severity, byteOffset: number, message: string, recoverable: boolean, path?: string): Diagnostic;
+export {};
+//# sourceMappingURL=factory.d.ts.map

package/dist/diagnostics/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/diagnostics/factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,KAAK,QAAQ,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;AAEvC;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,OAAO,EACpB,IAAI,CAAC,EAAE,MAAM,GACZ,UAAU,CAYZ"}

package/dist/diagnostics/factory.js

@@ -0,0 +1,17 @@
+/**
+ * Creates a Diagnostic object.
+ */
+export function createDiagnostic(code, severity, byteOffset, message, recoverable, path) {
+    const diag = {
+        code,
+        severity,
+        byteOffset,
+        message,
+        recoverable,
+    };
+    if (path !== undefined) {
+        diag.path = path;
+    }
+    return diag;
+}
+//# sourceMappingURL=factory.js.map

package/dist/diagnostics/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/diagnostics/factory.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,QAAkB,EAClB,UAAkB,EAClB,OAAe,EACf,WAAoB,EACpB,IAAa;IAEb,MAAM,IAAI,GAAe;QACvB,IAAI;QACJ,QAAQ;QACR,UAAU;QACV,OAAO;QACP,WAAW;KACZ,CAAC;IACF,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/grammar/frame.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Expectation states for object parsing.
+ */
+export type ObjectExpectation = "first_key_or_end" | "key_after_comma" | "colon" | "value" | "comma_or_end";
+/**
+ * Expectation states for array parsing.
+ */
+export type ArrayExpectation = "first_value_or_end" | "value_after_comma" | "comma_or_end";
+/**
+ * A frame on the grammar stack representing a JSON container.
+ */
+export interface GrammarFrame {
+    /** The type of container. */
+    containerType: "object" | "array";
+    /**
+     * The JSON Pointer path up to this container.
+     * Backed by a lazily-computed, memoized getter (see attachLazyPath) —
+     * reads exactly like a plain string field everywhere else in the codebase.
+     */
+    path: string;
+    /** Current expectation for object parsing. */
+    objectExpectation?: ObjectExpectation;
+    /** Current key being processed. */
+    currentKey?: string;
+    /** Set of keys already seen (for duplicate detection). */
+    seenKeys?: Set<string>;
+    /** Current expectation for array parsing. */
+    arrayExpectation?: ArrayExpectation;
+    /** Index of the next element. */
+    nextArrayIndex: number;
+    /** Byte offset where this container started. */
+    byteStart: number;
+    /**
+     * @internal Lazy-path bookkeeping. Do not read directly — use `.path`.
+     * A frame's own path never changes after creation (only descendants'
+     * currentKey/nextArrayIndex mutate), so it's safe to resolve on demand.
+     */
+    _parent?: GrammarFrame | null;
+    /** @internal The key/index linking `_parent` to this frame, captured at creation time. */
+    _segment?: string | number | null;
+    /** @internal Memoized resolved path, set the first time `.path` is read. */
+    _cachedPath?: string;
+}
+/**
+ * Create a new object frame.
+ * `parent` is the frame this one is nested inside (or null at the root);
+ * `segment` is the key/index leading from parent to this frame (or null at
+ * the root) — the same value `GrammarStack.currentValuePath()` would have
+ * used, captured eagerly since it reflects the parent's mutable state at
+ * this exact moment. Only the (expensive, O(depth)) string flattening is
+ * deferred.
+ */
+export declare function createObjectFrame(parent: GrammarFrame | null, segment: string | number | null, byteStart: number): GrammarFrame;
+/**
+ * Create a new array frame. See createObjectFrame for `parent`/`segment`.
+ */
+export declare function createArrayFrame(parent: GrammarFrame | null, segment: string | number | null, byteStart: number): GrammarFrame;
+//# sourceMappingURL=frame.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../../src/grammar/frame.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,MAAM,iBAAiB,GACzB,kBAAkB,GAClB,iBAAiB,GACjB,OAAO,GACP,OAAO,GACP,cAAc,CAAC;AAEnB;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,oBAAoB,GACpB,mBAAmB,GACnB,cAAc,CAAC;AAEnB;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,6BAA6B;IAC7B,aAAa,EAAE,QAAQ,GAAG,OAAO,CAAC;IAElC;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IAGb,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAEtC,mCAAmC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAGvB,6CAA6C;IAC7C,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAEpC,iCAAiC;IACjC,cAAc,EAAE,MAAM,CAAC;IAEvB,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9B,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAClC,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA0DD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,GAAG,IAAI,EAC3B,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,EAC/B,SAAS,EAAE,MAAM,GAChB,YAAY,CAWd;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,YAAY,GAAG,IAAI,EAC3B,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,EAC/B,SAAS,EAAE,MAAM,GAChB,YAAY,CAUd"}

package/dist/grammar/frame.js

@@ -0,0 +1,87 @@
+// ---------------------------------------------------------------------------
+// Grammar stack frame — tracks state of a JSON container
+// ---------------------------------------------------------------------------
+import { appendPointer } from "./pointer.js";
+/**
+ * Resolve (and memoize) a frame's full JSON Pointer path.
+ *
+ * Iterative, not recursive: walks up `_parent` references collecting frames
+ * until it finds one whose path is already cached (or the root), then walks
+ * back down building and caching each frame's path exactly once. This keeps
+ * per-frame cost amortized O(1) regardless of nesting depth, and avoids
+ * both the call-stack growth a recursive walk would have and the O(depth)
+ * eager string concatenation this replaces (which made opening N nested
+ * containers cost O(N^2) total, regardless of whether any value inside them
+ * was ever committed).
+ */
+function resolveFramePath(frame) {
+    if (frame._cachedPath !== undefined)
+        return frame._cachedPath;
+    const chain = [];
+    let cur = frame;
+    while (cur !== null && cur._cachedPath === undefined) {
+        chain.push(cur);
+        cur = cur._parent === undefined ? null : cur._parent;
+    }
+    let basePath = cur !== null ? cur._cachedPath : "";
+    // chain[0] is always `frame` itself (pushed in the first loop iteration),
+    // and this loop runs in reverse, so the last iteration (i === 0) sets
+    // basePath to frame's own resolved path — returning it directly avoids
+    // re-reading frame._cachedPath, which TS can't prove was set here since
+    // the mutation happens through the aliased `f` reference.
+    for (let i = chain.length - 1; i >= 0; i--) {
+        const f = chain[i];
+        const seg = f._segment;
+        basePath =
+            seg === null || seg === undefined ? basePath : appendPointer(basePath, seg);
+        f._cachedPath = basePath;
+    }
+    return basePath;
+}
+function attachLazyPath(frame, parent, segment) {
+    frame._parent = parent;
+    frame._segment = segment;
+    Object.defineProperty(frame, "path", {
+        enumerable: true,
+        configurable: true,
+        get() {
+            return resolveFramePath(frame);
+        },
+    });
+}
+/**
+ * Create a new object frame.
+ * `parent` is the frame this one is nested inside (or null at the root);
+ * `segment` is the key/index leading from parent to this frame (or null at
+ * the root) — the same value `GrammarStack.currentValuePath()` would have
+ * used, captured eagerly since it reflects the parent's mutable state at
+ * this exact moment. Only the (expensive, O(depth)) string flattening is
+ * deferred.
+ */
+export function createObjectFrame(parent, segment, byteStart) {
+    const frame = {
+        containerType: "object",
+        path: "",
+        objectExpectation: "first_key_or_end",
+        seenKeys: new Set(),
+        nextArrayIndex: 0,
+        byteStart,
+    };
+    attachLazyPath(frame, parent, segment);
+    return frame;
+}
+/**
+ * Create a new array frame. See createObjectFrame for `parent`/`segment`.
+ */
+export function createArrayFrame(parent, segment, byteStart) {
+    const frame = {
+        containerType: "array",
+        path: "",
+        arrayExpectation: "first_value_or_end",
+        nextArrayIndex: 0,
+        byteStart,
+    };
+    attachLazyPath(frame, parent, segment);
+    return frame;
+}
+//# sourceMappingURL=frame.js.map

package/dist/grammar/frame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.js","sourceRoot":"","sources":["../../src/grammar/frame.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,yDAAyD;AACzD,8EAA8E;AAE9E,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAkE7C;;;;;;;;;;;GAWG;AACH,SAAS,gBAAgB,CAAC,KAAmB;IAC3C,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,WAAW,CAAC;IAE9D,MAAM,KAAK,GAAmB,EAAE,CAAC;IACjC,IAAI,GAAG,GAAwB,KAAK,CAAC;IACrC,OAAO,GAAG,KAAK,IAAI,IAAI,GAAG,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACrD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChB,GAAG,GAAG,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC;IACvD,CAAC;IAED,IAAI,QAAQ,GAAG,GAAG,KAAK,IAAI,CAAC,CAAC,CAAE,GAAG,CAAC,WAAsB,CAAC,CAAC,CAAC,EAAE,CAAC;IAE/D,0EAA0E;IAC1E,sEAAsE;IACtE,uEAAuE;IACvE,wEAAwE;IACxE,0DAA0D;IAC1D,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAiB,CAAC;QACnC,MAAM,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC;QACvB,QAAQ;YACN,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QAC9E,CAAC,CAAC,WAAW,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,cAAc,CACrB,KAAmB,EACnB,MAA2B,EAC3B,OAA+B;IAE/B,KAAK,CAAC,OAAO,GAAG,MAAM,CAAC;IACvB,KAAK,CAAC,QAAQ,GAAG,OAAO,CAAC;IACzB,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE;QACnC,UAAU,EAAE,IAAI;QAChB,YAAY,EAAE,IAAI;QAClB,GAAG;YACD,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC;QACjC,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAA2B,EAC3B,OAA+B,EAC/B,SAAiB;IAEjB,MAAM,KAAK,GAAiB;QAC1B,aAAa,EAAE,QAAQ;QACvB,IAAI,EAAE,EAAE;QACR,iBAAiB,EAAE,kBAAkB;QACrC,QAAQ,EAAE,IAAI,GAAG,EAAE;QACnB,cAAc,EAAE,CAAC;QACjB,SAAS;KACV,CAAC;IACF,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAA2B,EAC3B,OAA+B,EAC/B,SAAiB;IAEjB,MAAM,KAAK,GAAiB;QAC1B,aAAa,EAAE,OAAO;QACtB,IAAI,EAAE,EAAE;QACR,gBAAgB,EAAE,oBAAoB;QACtC,cAAc,EAAE,CAAC;QACjB,SAAS;KACV,CAAC;IACF,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/grammar/pointer.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Escape a JSON Pointer reference token per RFC 6901.
+ * ~ → ~0, / → ~1
+ */
+export declare function escapePointerToken(token: string): string;
+/**
+ * Build a JSON Pointer path from parent path and a key or index.
+ */
+export declare function appendPointer(parent: string, token: string | number): string;
+//# sourceMappingURL=pointer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pointer.d.ts","sourceRoot":"","sources":["../../src/grammar/pointer.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAK5E"}

package/dist/grammar/pointer.js

@@ -0,0 +1,20 @@
+// ---------------------------------------------------------------------------
+// JSON Pointer utilities (RFC 6901)
+// ---------------------------------------------------------------------------
+/**
+ * Escape a JSON Pointer reference token per RFC 6901.
+ * ~ → ~0, / → ~1
+ */
+export function escapePointerToken(token) {
+    return token.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+/**
+ * Build a JSON Pointer path from parent path and a key or index.
+ */
+export function appendPointer(parent, token) {
+    if (typeof token === "number") {
+        return `${parent}/${token}`;
+    }
+    return `${parent}/${escapePointerToken(token)}`;
+}
+//# sourceMappingURL=pointer.js.map

package/dist/grammar/pointer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pointer.js","sourceRoot":"","sources":["../../src/grammar/pointer.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,oCAAoC;AACpC,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACxD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,KAAsB;IAClE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,GAAG,MAAM,IAAI,KAAK,EAAE,CAAC;IAC9B,CAAC;IACD,OAAO,GAAG,MAAM,IAAI,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;AAClD,CAAC"}

package/dist/grammar/stack.d.ts

@@ -0,0 +1,73 @@
+import type { GrammarFrame } from "./frame.js";
+import type { Diagnostic } from "../types.js";
+/**
+ * Manages the stack of open JSON containers.
+ * Handles object/array nesting, expectations, and duplicate key detection.
+ */
+export declare class GrammarStack {
+    private stack;
+    private diagnostics;
+    private hasDuplicateKey;
+    private maxDepth;
+    constructor(maxDepth: number);
+    /** Current depth (number of open containers). */
+    get depth(): number;
+    /** Whether any duplicate key has been seen. */
+    get hasDuplicate(): boolean;
+    /** Get the current (top) frame, or undefined if empty. */
+    get current(): GrammarFrame | undefined;
+    /**
+     * Push a new object container.
+     * Returns the frame, or null if depth limit exceeded.
+     */
+    pushObject(byteStart: number): GrammarFrame | null;
+    /**
+     * Push a new array container.
+     * Returns the frame, or null if depth limit exceeded.
+     */
+    pushArray(byteStart: number): GrammarFrame | null;
+    /**
+     * Pop the current container.
+     * Returns the popped frame.
+     */
+    pop(): GrammarFrame | undefined;
+    /**
+     * Register an object key. Returns true if the key is new.
+     * If duplicate, emits diagnostic and returns false.
+     */
+    registerObjectKey(key: string, byteOffset: number): boolean;
+    /**
+     * Get the JSON Pointer path for where the next value will go.
+     */
+    currentValuePath(): string;
+    /**
+     * The key/index that would lead from the current frame to its next child,
+     * without flattening it into a full path string. Same underlying value
+     * currentValuePath() uses; kept as a raw segment so a newly-pushed child
+     * frame can capture it in O(1) and defer the expensive path-string join
+     * (see grammar/frame.ts) until something actually reads `.path`.
+     */
+    private currentSegment;
+    /**
+     * Advance the array index after an element value is committed.
+     */
+    advanceArrayIndex(): void;
+    /**
+     * Take accumulated diagnostics and clear.
+     */
+    takeDiagnostics(): Diagnostic[];
+    /**
+     * Check if the stack is empty (no open containers).
+     */
+    isEmpty(): boolean;
+    /**
+     * Get all frames (for snapshot/pending info).
+     */
+    getFrames(): readonly GrammarFrame[];
+    /**
+     * Determine if all open containers can be safely closed by just appending '}' or ']'.
+     * This is true if no container is waiting for a colon or a value.
+     */
+    canSafelyCloseAll(): boolean;
+}
+//# sourceMappingURL=stack.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stack.d.ts","sourceRoot":"","sources":["../../src/grammar/stack.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAI9C;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAS;gBAEb,QAAQ,EAAE,MAAM;IAI5B,iDAAiD;IACjD,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,+CAA+C;IAC/C,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,0DAA0D;IAC1D,IAAI,OAAO,IAAI,YAAY,GAAG,SAAS,CAEtC;IAED;;;OAGG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAmBlD;;;OAGG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAmBjD;;;OAGG;IACH,GAAG,IAAI,YAAY,GAAG,SAAS;IAI/B;;;OAGG;IACH,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO;IA0B3D;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAc1B;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAUtB;;OAEG;IACH,iBAAiB,IAAI,IAAI;IAOzB;;OAEG;IACH,eAAe,IAAI,UAAU,EAAE;IAM/B;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACH,SAAS,IAAI,SAAS,YAAY,EAAE;IAIpC;;;OAGG;IACH,iBAAiB,IAAI,OAAO;CAkB7B"}

package/dist/grammar/stack.js

@@ -0,0 +1,168 @@
+// ---------------------------------------------------------------------------
+// Grammar Stack — tracks nested JSON container state
+// ---------------------------------------------------------------------------
+import { createObjectFrame, createArrayFrame } from "./frame.js";
+import { appendPointer } from "./pointer.js";
+import { DiagnosticCode } from "../diagnostics/codes.js";
+import { createDiagnostic } from "../diagnostics/factory.js";
+/**
+ * Manages the stack of open JSON containers.
+ * Handles object/array nesting, expectations, and duplicate key detection.
+ */
+export class GrammarStack {
+    stack = [];
+    diagnostics = [];
+    hasDuplicateKey = false;
+    maxDepth;
+    constructor(maxDepth) {
+        this.maxDepth = maxDepth;
+    }
+    /** Current depth (number of open containers). */
+    get depth() {
+        return this.stack.length;
+    }
+    /** Whether any duplicate key has been seen. */
+    get hasDuplicate() {
+        return this.hasDuplicateKey;
+    }
+    /** Get the current (top) frame, or undefined if empty. */
+    get current() {
+        return this.stack[this.stack.length - 1];
+    }
+    /**
+     * Push a new object container.
+     * Returns the frame, or null if depth limit exceeded.
+     */
+    pushObject(byteStart) {
+        if (this.stack.length >= this.maxDepth) {
+            this.diagnostics.push(createDiagnostic(DiagnosticCode.E_LIMIT_DEPTH, "fatal", byteStart, `Maximum nesting depth ${this.maxDepth} exceeded`, false));
+            return null;
+        }
+        const parent = this.current ?? null;
+        const frame = createObjectFrame(parent, this.currentSegment(), byteStart);
+        this.stack.push(frame);
+        return frame;
+    }
+    /**
+     * Push a new array container.
+     * Returns the frame, or null if depth limit exceeded.
+     */
+    pushArray(byteStart) {
+        if (this.stack.length >= this.maxDepth) {
+            this.diagnostics.push(createDiagnostic(DiagnosticCode.E_LIMIT_DEPTH, "fatal", byteStart, `Maximum nesting depth ${this.maxDepth} exceeded`, false));
+            return null;
+        }
+        const parent = this.current ?? null;
+        const frame = createArrayFrame(parent, this.currentSegment(), byteStart);
+        this.stack.push(frame);
+        return frame;
+    }
+    /**
+     * Pop the current container.
+     * Returns the popped frame.
+     */
+    pop() {
+        return this.stack.pop();
+    }
+    /**
+     * Register an object key. Returns true if the key is new.
+     * If duplicate, emits diagnostic and returns false.
+     */
+    registerObjectKey(key, byteOffset) {
+        const frame = this.current;
+        if (!frame || frame.containerType !== "object" || !frame.seenKeys) {
+            return false;
+        }
+        if (frame.seenKeys.has(key)) {
+            this.hasDuplicateKey = true;
+            this.diagnostics.push(createDiagnostic(DiagnosticCode.E_DUPLICATE_KEY, "error", byteOffset, `Duplicate object key: ${JSON.stringify(key)}`, false, frame.path));
+            return false;
+        }
+        frame.seenKeys.add(key);
+        frame.currentKey = key;
+        return true;
+    }
+    /**
+     * Get the JSON Pointer path for where the next value will go.
+     */
+    currentValuePath() {
+        const frame = this.current;
+        if (!frame)
+            return "";
+        if (frame.containerType === "object") {
+            if (frame.currentKey !== undefined) {
+                return appendPointer(frame.path, frame.currentKey);
+            }
+            return frame.path;
+        }
+        // array
+        return appendPointer(frame.path, frame.nextArrayIndex);
+    }
+    /**
+     * The key/index that would lead from the current frame to its next child,
+     * without flattening it into a full path string. Same underlying value
+     * currentValuePath() uses; kept as a raw segment so a newly-pushed child
+     * frame can capture it in O(1) and defer the expensive path-string join
+     * (see grammar/frame.ts) until something actually reads `.path`.
+     */
+    currentSegment() {
+        const frame = this.current;
+        if (!frame)
+            return null;
+        if (frame.containerType === "object") {
+            return frame.currentKey !== undefined ? frame.currentKey : null;
+        }
+        return frame.nextArrayIndex;
+    }
+    /**
+     * Advance the array index after an element value is committed.
+     */
+    advanceArrayIndex() {
+        const frame = this.current;
+        if (frame && frame.containerType === "array") {
+            frame.nextArrayIndex++;
+        }
+    }
+    /**
+     * Take accumulated diagnostics and clear.
+     */
+    takeDiagnostics() {
+        const result = this.diagnostics;
+        this.diagnostics = [];
+        return result;
+    }
+    /**
+     * Check if the stack is empty (no open containers).
+     */
+    isEmpty() {
+        return this.stack.length === 0;
+    }
+    /**
+     * Get all frames (for snapshot/pending info).
+     */
+    getFrames() {
+        return this.stack;
+    }
+    /**
+     * Determine if all open containers can be safely closed by just appending '}' or ']'.
+     * This is true if no container is waiting for a colon or a value.
+     */
+    canSafelyCloseAll() {
+        for (const frame of this.stack) {
+            if (frame.containerType === "object") {
+                if (frame.objectExpectation === "colon" ||
+                    frame.objectExpectation === "value" ||
+                    frame.objectExpectation === "key_after_comma") {
+                    return false; // Missing colon or value or key
+                }
+            }
+            else {
+                if (frame.arrayExpectation === "value_after_comma") {
+                    return false; // Missing value after comma
+                }
+            }
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=stack.js.map

package/dist/grammar/stack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack.js","sourceRoot":"","sources":["../../src/grammar/stack.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @public (Stable)
+ * Creates a new Incremental JSON Parser instance.
+ */
+export { createParser } from "./parser.js";
+export type { IncrementalJsonParser, ParserOptions, PushResult, ParserSnapshot, FinalResult, ParserEvent, ValueCommittedEvent, ContainerClosedEvent, RepairAppliedEvent, DiagnosticEvent, DocumentCompleteEvent, StreamFinishedEvent, JsonValue, JsonObject, JsonArray, SyntaxStatus, StreamEndReason, PendingToken, RepairAction, Diagnostic, ParserLimits, } from "./types.js";
+export { DEFAULT_LIMITS } from "./limits.js";
+export { DiagnosticCode } from "./diagnostics/codes.js";
+/**
+ * @public (Stable)
+ * Creates a stream coordinator for mapping overlapping multi-tool streams.
+ */
+export { createToolCallStreamCoordinator } from "./coordinator/coordinator.js";
+export type { ToolCallStreamCoordinator } from "./coordinator/types.js";
+export type { NormalizedToolStreamEvent } from "./coordinator/protocol.js";
+export type { ProviderStreamAdapter } from "./providers/adapter.js";
+/**
+ * @public (Experimental)
+ * Provider adapters for various LLM network shapes.
+ * These are experimental and may change if upstream APIs change.
+ */
+export { OpenAIStreamAdapter } from "./providers/openai.js";
+export { OpenAICompatibleStreamAdapter } from "./providers/openai-compatible.js";
+export { AnthropicStreamAdapter } from "./providers/anthropic.js";
+export { GeminiStreamAdapter } from "./providers/gemini.js";
+export { OpenRouterStreamAdapter } from "./providers/openrouter.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,YAAY,EAEV,qBAAqB,EACrB,aAAa,EAGb,UAAU,EACV,cAAc,EACd,WAAW,EAGX,WAAW,EACX,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EAGnB,SAAS,EACT,UAAU,EACV,SAAS,EACT,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAGxD;;;GAGG;AACH,OAAO,EAAE,+BAA+B,EAAE,MAAM,8BAA8B,CAAC;AAC/E,YAAY,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AACxE,YAAY,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAG3E,YAAY,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE;;;;GAIG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,6BAA6B,EAAE,MAAM,kCAAkC,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,27 @@
+// ---------------------------------------------------------------------------
+// Public API — prefix-safe-json
+// ---------------------------------------------------------------------------
+/**
+ * @public (Stable)
+ * Creates a new Incremental JSON Parser instance.
+ */
+export { createParser } from "./parser.js";
+export { DEFAULT_LIMITS } from "./limits.js";
+export { DiagnosticCode } from "./diagnostics/codes.js";
+// Coordinator API
+/**
+ * @public (Stable)
+ * Creates a stream coordinator for mapping overlapping multi-tool streams.
+ */
+export { createToolCallStreamCoordinator } from "./coordinator/coordinator.js";
+/**
+ * @public (Experimental)
+ * Provider adapters for various LLM network shapes.
+ * These are experimental and may change if upstream APIs change.
+ */
+export { OpenAIStreamAdapter } from "./providers/openai.js";
+export { OpenAICompatibleStreamAdapter } from "./providers/openai-compatible.js";
+export { AnthropicStreamAdapter } from "./providers/anthropic.js";
+export { GeminiStreamAdapter } from "./providers/gemini.js";
+export { OpenRouterStreamAdapter } from "./providers/openrouter.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,gCAAgC;AAChC,8EAA8E;AAE9E;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAiC3C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,kBAAkB;AAClB;;;GAGG;AACH,OAAO,EAAE,+BAA+B,EAAE,MAAM,8BAA8B,CAAC;AAO/E;;;;GAIG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,6BAA6B,EAAE,MAAM,kCAAkC,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/lexer/scanner.d.ts

@@ -0,0 +1,108 @@
+import { ScannerState } from "./states.js";
+import type { Token } from "./tokens.js";
+import type { Diagnostic, RepairAction, ParserOptions } from "../types.js";
+/**
+ * Incremental JSON scanner.
+ * Feed characters one at a time via feedChar().
+ * Collect tokens via takeTokens().
+ */
+export declare class Scanner {
+    private options;
+    private maxStringBytes;
+    constructor(options?: ParserOptions);
+    private state;
+    private tokens;
+    private diagnostics;
+    private repairs;
+    private stringBuffer;
+    private stringIsKey;
+    private stringByteStart;
+    private unicodeHexBuffer;
+    private highSurrogate;
+    /** Tracks position in surrogate pair sequence: 0=initial, 1=saw backslash, 2=saw 'u' */
+    private surrogatePhase;
+    private numberBuffer;
+    private numberByteStart;
+    private numberHasDigit;
+    private literalTarget;
+    private literalIndex;
+    private literalByteStart;
+    /** Byte offset of the current character being fed. Set by the caller. */
+    private currentByteOffset;
+    /** Whether we're in a key position for string parsing. */
+    private nextStringIsKey;
+    get currentState(): ScannerState;
+    /**
+     * Feed a single character to the scanner.
+     * @param ch - The character to process.
+     * @param byteOffset - Absolute byte offset of this character in the input stream.
+     * @param charByteLength - Number of bytes this character occupies in UTF-8.
+     */
+    feedChar(ch: string, byteOffset: number, charByteLength: number): void;
+    /**
+     * Take all tokens accumulated since the last call.
+     * Clears the internal token buffer.
+     */
+    takeTokens(): Token[];
+    /**
+     * Take all diagnostics accumulated since the last call.
+     * Clears the internal diagnostic buffer.
+     */
+    takeDiagnostics(): Diagnostic[];
+    takeRepairs(): RepairAction[];
+    /**
+     * Set whether the next string to be scanned should be treated as an object key.
+     */
+    setNextStringIsKey(isKey: boolean): void;
+    /**
+     * Get info about any pending (incomplete) value.
+     */
+    getPendingInfo(): {
+        type: "string" | "number" | "literal" | "unicode_escape" | "surrogate" | "none";
+        buffer: string;
+        byteStart: number;
+        isKey: boolean;
+    };
+    /**
+     * Check numberBuffer against the parts of RFC 8259's number grammar that
+     * aren't already enforced by the state machine's character-by-character
+     * transitions: no leading zero in the integer part, and no trailing
+     * "." or exponent marker with no digit following it. Returns an error
+     * message if invalid, or null if the buffer is a well-formed number.
+     */
+    private numberGrammarError;
+    /**
+     * Attempt to finalize a pending number (at end of input or finish()).
+     *  - "finalized": a valid number token was emitted.
+     *  - "invalid": there was a complete-looking buffer, but it violates JSON
+     *    number grammar (leading zero, trailing "." or exponent marker with
+     *    no digit after it). Nothing is emitted; numberBuffer is left as-is.
+     *  - "not_ready": scanner isn't in a finalizable number state at all
+     *    (e.g. buffer is just "-", or ends right at a bare "e"/"E" with no
+     *    sign or digit yet) — unchanged pre-existing behavior, callers should
+     *    not newly diagnose this case.
+     */
+    finalizeNumber(): "finalized" | "invalid" | "not_ready";
+    /**
+     * Attempt to finalize a pending literal (at end of input or finish).
+     * Returns true if a literal token was emitted.
+     */
+    finalizeLiteral(): boolean;
+    private processStructural;
+    private processString;
+    private processEscape;
+    private processUnicodeEscape;
+    private processSurrogatePending;
+    private processNumber;
+    private processLiteral;
+    private processTrailingWhitespace;
+    private beginString;
+    private beginNumber;
+    private beginLiteral;
+    private commitNumber;
+    private isValueTerminator;
+    private reprocessChar;
+    private emitToken;
+    private emitDiagnostic;
+}
+//# sourceMappingURL=scanner.d.ts.map