@jarenjs/json 0.9.2 → 0.34.0

package/dist/types/jtlt/errors.d.ts

@@ -1,18 +1,15 @@
+import { CodedDocPathError } from '../errors.js';
 /**
  * Error thrown when a JTLT template is rejected at compile time
  * (`TL0xxx` codes).
  */
-export declare class JtltCompileError extends Error {
-    code: any;
-    docPath: any;
+export declare class JtltCompileError extends CodedDocPathError {
     constructor(code: any, message: any, docPath: any, cause?: undefined);
 }
 /**
  * Error thrown when rendering with a compiled JTLT template fails
  * (`TL2xxx` codes).
  */
-export declare class JtltRuntimeError extends Error {
-    code: any;
-    docPath: any;
+export declare class JtltRuntimeError extends CodedDocPathError {
     constructor(code: any, message: any, docPath: any, cause?: undefined);
 }

package/dist/types/option-variants.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @file Per-document compilation-variant caching, shared by the JSLT
+ * and JTLT one-call entry points. A document compiles differently under
+ * different options, so the cache key is the FULL option tuple — every
+ * option that changes what compiles must be part of the derived key, or
+ * a second call with different options silently reuses the first
+ * compilation (the cache-poisoning bug the JTLT cache had before the
+ * health pass). Identity-compared option values (hook functions,
+ * function-extension registries) are interned to stable per-process ids
+ * so the key is a flat string and lookup is O(1) instead of a linear
+ * scan over an unbounded variants array.
+ */
+/**
+ * A stable per-process id for an identity-compared option value.
+ * `null`/`undefined` share id 0 ("absent").
+ * @param {any} value
+ * @returns {number}
+ */
+export declare function identityOf(value: any): number;
+/**
+ * A two-axis compilation cache: documents by identity (weak, entries
+ * die with the document), variants per document by derived option key
+ * (bounded LRU — the old variants array grew without bound).
+ * @param {number} [limitPerDocument] - variant bound per document
+ * @returns {{ getOrCompile: (document: object, key: string, compile: () => any) => any }}
+ */
+export declare function createOptionVariantCache(limitPerDocument?: number): {
+    getOrCompile: (document: object, key: string, compile: () => any) => any;
+};

package/dist/types/patch.d.ts

@@ -0,0 +1,214 @@
+import { CodedError } from '@jarenjs/core/errors';
+import { CodedDocPathError } from './errors.js';
+/**
+ * Error thrown when a JSON Patch document is rejected at compile time
+ * (`JP0xxx` codes). `docPath` is an RFC 6901 JSON Pointer into the
+ * patch document (e.g. `/2/from`). A wrapped pointer syntax error is
+ * exposed through `cause`.
+ */
+export declare class JsonPatchCompileError extends CodedDocPathError {
+    constructor(code: any, message: any, docPath: any, cause?: undefined);
+}
+/**
+ * Error thrown when applying a compiled JSON Patch fails (`JP2xxx`
+ * codes). `docPath` points at the failing operation in the patch
+ * document; `dataPath` is the operation's target location in the
+ * document being patched — both render, separately identifiable, per
+ * the `@jarenjs/core` coded contract (`at` = document, `in data` =
+ * data).
+ */
+export declare class JsonPatchRuntimeError extends CodedError {
+    constructor(code: any, reason: any, docPath: any, dataPath: any);
+}
+export type JsonPatchOperation = {
+    op: 'add' | 'remove' | 'replace' | 'move' | 'copy' | 'test';
+    path: string;
+    value?: any;
+    from?: string;
+};
+export type JsonPatchApplier = (doc: any) => any;
+export type JsonPatchChangesApplier = (doc: any) => {
+    doc: any;
+    changes: string[];
+};
+export type JsonPatchOptions = {
+    /**
+     * - Apply in place instead of copy-on-write.
+     * Faster, but the input document is modified and a failing operation
+     * leaves it partially patched (application is no longer atomic).
+     */
+    mutate?: boolean;
+    /**
+     * - How operation values enter the
+     * result: `'share'` (default) inserts them by reference, so results of
+     * repeated applications share structure with the patch document and
+     * must be treated as immutable; `'fresh'` deep-copies per application.
+     * In-place mode always behaves as `'fresh'`.
+     */
+    values?: 'share' | 'fresh';
+    /**
+     * - Track changed locations: the applier
+     * returns `{ doc, changes }` where `changes` is an array of JSON
+     * Pointers, one per successful write, in application order and not
+     * deduplicated. The reported pointer is chosen to be *sound for
+     * invalidation* — everything at or below it (plus the identity of its
+     * ancestors) may have changed, and nothing outside the reported set
+     * did: object writes, array replaces and array appends report the
+     * written location itself; array inserts and removes that shift later
+     * elements report the parent array's pointer; a root write reports
+     * `''`. `test` operations report nothing.
+     */
+    changes?: boolean;
+};
+/**
+ * Compile a JSON Patch (RFC 6902) into a reusable applier.
+ *
+ * The patch document is validated once (`JsonPatchCompileError`,
+ * `JP0xxx`, with a `docPath` into the patch document); every pointer is
+ * pre-parsed and each operation becomes a specialized closure. Applying
+ * is copy-on-write: the input document is never mutated, untouched
+ * subtrees are shared with the result, and application is atomic - a
+ * failing operation (`JsonPatchRuntimeError`, `JP2xxx`) leaves nothing
+ * behind.
+ *
+ * With `changes: true` the applier is specialized at compile time to
+ * also report the changed locations: it returns `{ doc, changes }`,
+ * where `changes` holds one JSON Pointer per successful write with the
+ * invalidation-sound semantics documented on `JsonPatchOptions` — the
+ * primitive dirty-path consumers (view re-rendering, rule dependency
+ * memoization) build on.
+ *
+ * @param {JsonPatchOperation[]} patch - The RFC 6902 patch document
+ * @param {JsonPatchOptions} [options] - Application options
+ * @returns {JsonPatchApplier | JsonPatchChangesApplier} applier
+ *   returning the patched document (or `{ doc, changes }` with the
+ *   `changes` option)
+ * @throws {JsonPatchCompileError} When the patch document is invalid
+ * @example
+ * const apply = compileJSONPatch([
+ *   { op: 'test', path: '/version', value: 5 },
+ *   { op: 'replace', path: '/user/name', value: 'Bob' },
+ *   { op: 'add', path: '/user/tags/-', value: 'admin' },
+ * ]);
+ * const next = apply(doc); // doc is untouched
+ * @example
+ * const applyTracked = compileJSONPatch(
+ *   [{ op: 'replace', path: '/user/name', value: 'Bob' }],
+ *   { changes: true });
+ * const { doc: next2, changes } = applyTracked(doc);
+ * // changes: ['/user/name']
+ */
+export declare function compileJSONPatch(patch: JsonPatchOperation[], options?: JsonPatchOptions): JsonPatchApplier | JsonPatchChangesApplier;
+/**
+ * Apply a JSON Patch (RFC 6902) to a document in one shot. Compiles the
+ * patch and applies it once; on hot paths prefer `compileJSONPatch` and
+ * reuse the applier.
+ *
+ * @param {any} doc - The document to patch (never mutated unless
+ *   `options.mutate` is set)
+ * @param {JsonPatchOperation[]} patch - The RFC 6902 patch document
+ * @param {JsonPatchOptions} [options] - Application options
+ * @returns {any} The patched document, or `{ doc, changes }` when
+ *   `options.changes` is set
+ * @throws {JsonPatchCompileError} When the patch document is invalid
+ * @throws {JsonPatchRuntimeError} When an operation fails to apply
+ */
+export declare function applyJSONPatch(doc: any, patch: JsonPatchOperation[], options?: JsonPatchOptions): any;
+/**
+ * Returns true when `patch` is a structurally valid RFC 6902 patch
+ * document (an array of well-formed operation objects with valid
+ * pointers). Runtime applicability against a document is not checked.
+ * @param {any} patch - The candidate patch document
+ * @returns {boolean}
+ */
+export declare function isValidJSONPatch(patch: any): boolean;
+/**
+ * Compute a JSON Patch (RFC 6902) that transforms `source` into
+ * `target`: `applyJSONPatch(source, createJSONPatch(source, target))`
+ * is deep-equal to `target`.
+ *
+ * Objects diff member-wise; arrays trim the common prefix/suffix and
+ * diff the middle index-wise, so in-place edits and head/tail
+ * insertions produce minimal patches while a mid-array insertion falls
+ * back to correct (but larger) per-index replaces. Emitted `value`
+ * members share references with `target`.
+ *
+ * `arrayDiff: 'minimal'` aligns the changed middle instead, so a
+ * mid-array insertion or deletion is emitted as one `add`/`remove` —
+ * the smallest patch, which is what matters when patches go over the
+ * wire. The alignment minimizes the patch itself (edit distance with
+ * substitutions, not a longest common subsequence: LCS maximizes kept
+ * elements, which costs a delete plus an insert on a permutation where
+ * one rewrite would do), so it never takes more alignment steps than
+ * the index-wise pairing.
+ *
+ * It is opt-in because it costs O(m*n) time and space in the length of
+ * that middle, against the default's linear pass; above a fixed cell
+ * budget a single array falls back to the index-wise diff, so the mode
+ * never turns a large diff quadratic. Both modes produce patches that
+ * reproduce `target` exactly.
+ *
+ * @param {any} source - The original document
+ * @param {any} target - The desired document
+ * @param {{ arrayDiff?: 'index' | 'minimal' }} [options] - `arrayDiff`
+ *   selects the array strategy: `'index'` (default) or `'minimal'`
+ * @returns {JsonPatchOperation[]} The patch document (empty when equal)
+ * @throws {TypeError} When `arrayDiff` is not a known mode
+ * @example
+ * createJSONPatch({ a: 1, b: 2 }, { a: 1, b: 3, c: 4 });
+ * // [{ op: 'replace', path: '/b', value: 3 },
+ * //  { op: 'add', path: '/c', value: 4 }]
+ * @example
+ * const before = [{ id: 1 }, { id: 2 }, { id: 3, n: 0 }];
+ * const after = [{ id: 1 }, { id: 9 }, { id: 2 }, { id: 3, n: 1 }];
+ * createJSONPatch(before, after, { arrayDiff: 'minimal' });
+ * // [{ op: 'add', path: '/1', value: { id: 9 } },
+ * //  { op: 'replace', path: '/3/n', value: 1 }]
+ */
+export declare function createJSONPatch(source: any, target: any, options?: {
+    arrayDiff?: 'index' | 'minimal';
+}): JsonPatchOperation[];
+export type JsonMergePatchApplier = (doc: any) => any;
+/**
+ * Compile a JSON Merge Patch (RFC 7396) into a reusable applier.
+ *
+ * The patch pre-splits once into remove/set/merge plans per level.
+ * Applying is copy-on-write and identity-preserving: unchanged subtrees
+ * (and a wholly unchanged document) come back by reference, set values
+ * are shared with the patch document, and the input is never mutated.
+ *
+ * @param {any} patch - The merge patch (any JSON value; a non-object
+ *   replaces the document wholesale)
+ * @returns {JsonMergePatchApplier} applier returning the patched document
+ * @example
+ * const apply = compileMergePatch({ age: 31, temp: null });
+ * apply({ name: 'Alice', age: 30, temp: 'x' });
+ * // { name: 'Alice', age: 31 }
+ */
+export declare function compileMergePatch(patch: any): JsonMergePatchApplier;
+/**
+ * Apply a JSON Merge Patch (RFC 7396) to a document in one shot. On hot
+ * paths prefer `compileMergePatch` and reuse the applier.
+ *
+ * @param {any} doc - The document to patch (never mutated)
+ * @param {any} patch - The merge patch
+ * @returns {any} The patched document
+ */
+export declare function applyMergePatch(doc: any, patch: any): any;
+/**
+ * Compute a JSON Merge Patch (RFC 7396) that transforms `source` into
+ * `target`. Removed members become `null`, nested objects diff
+ * recursively, and arrays (or any kind change) replace wholesale.
+ *
+ * RFC 7396 cannot represent a member whose target value is `null`:
+ * the diff emits `null` (a removal), so applying yields an absent
+ * member instead. Emitted values share references with `target`.
+ *
+ * @param {any} source - The original document
+ * @param {any} target - The desired document
+ * @returns {any} The merge patch (`{}` when nothing changed)
+ * @example
+ * createMergePatch({ a: 'b', c: 1 }, { a: 'x' });
+ * // { a: 'x', c: null }
+ */
+export declare function createMergePatch(source: any, target: any): any;

package/dist/types/path.d.ts

@@ -1,3 +1,4 @@
+import { LabeledSyntaxError } from './errors.js';
 /**
  * Sentinel for the absence of a value ("Nothing" in RFC 9535 terms), as
  * distinct from the JSON value `null`.
@@ -7,9 +8,7 @@ export declare const JSONPATH_NOTHING: symbol;
  * Error thrown when a JSONPath query is not valid RFC 9535 syntax
  * (including queries that are not well-typed per section 2.4.3).
  */
-export declare class JSONPathSyntaxError extends SyntaxError {
-    source: any;
-    position: any;
+export declare class JSONPathSyntaxError extends LabeledSyntaxError {
     constructor(message: any, source: any, position: any);
 }
 export type JSONPathNameSelector = {
@@ -101,11 +100,34 @@ export type JSONPathQuery = ((data: any) => any[]) & {
     values: (data: any) => any[];
     first: (data: any) => any;
     exists: (data: any) => boolean;
+    iterate: (data: any) => Generator<any>;
     nodes: (data: any) => JSONPathNode[];
     paths: (data: any) => string[];
     source: string;
     ast: JSONPathAst;
 };
+export type JSONPathFunction = {
+    /**
+     * - Declared parameter types
+     */
+    params: ('value' | 'nodes' | 'logical')[];
+    /**
+     * - Declared result type
+     */
+    returns: 'value' | 'nodes' | 'logical';
+    /**
+     * - The implementation
+     */
+    evaluate: (...args: any[]) => any;
+};
+export type JSONPathOptions = {
+    /**
+     * - Custom
+     * function extensions, by name. A name must match the RFC's
+     * `function-name` production and must not redefine a built-in.
+     */
+    pathFunctions?: Record<string, JSONPathFunction>;
+};
 /**
  * Selects a named object member (RFC 9535 name selector).
  * @typedef {Object} JSONPathNameSelector
@@ -173,19 +195,44 @@ export type JSONPathQuery = ((data: any) => any[]) & {
  *   values: (data: any) => any[],
  *   first: (data: any) => any,
  *   exists: (data: any) => boolean,
+ *   iterate: (data: any) => Generator<any>,
  *   nodes: (data: any) => JSONPathNode[],
  *   paths: (data: any) => string[],
  *   source: string,
  *   ast: JSONPathAst,
  * }} JSONPathQuery
  */
+/**
+ * A custom JSONPath function extension (RFC 9535 section 2.4). The
+ * declared types are what the parser type-checks call sites against
+ * (section 2.4.3), exactly as it does for the five built-ins.
+ *
+ * `evaluate` receives one argument per declared parameter: a `value`
+ * parameter arrives as a JSON value or `JSONPATH_NOTHING`, a `nodes`
+ * parameter as an array of the selected values, a `logical` parameter
+ * as a boolean. Its result must match `returns` - a `value` function
+ * may return `undefined` to mean Nothing.
+ * @typedef {Object} JSONPathFunction
+ * @property {('value'|'nodes'|'logical')[]} params - Declared parameter types
+ * @property {'value'|'nodes'|'logical'} returns - Declared result type
+ * @property {(...args: any[]) => any} evaluate - The implementation
+ */
+/**
+ * Options accepted by the JSONPath entry points.
+ * @typedef {Object} JSONPathOptions
+ * @property {Record<string, JSONPathFunction>} [pathFunctions] - Custom
+ *   function extensions, by name. A name must match the RFC's
+ *   `function-name` production and must not redefine a built-in.
+ */
 /**
  * Parse a JSONPath query string into an AST.
  * @param {string} source - The JSONPath expression (e.g. `$.store.book[?@.price < 10].title`)
+ * @param {JSONPathOptions} [options] - Parse options
  * @returns {JSONPathAst} The parsed query AST
  * @throws {JSONPathSyntaxError} When the query violates the RFC 9535 grammar
+ * @throws {TypeError} When `options.pathFunctions` is not a valid registry
  */
-export declare function parseJSONPath(source: string): JSONPathAst;
+export declare function parseJSONPath(source: string, options?: JSONPathOptions): JSONPathAst;
 /**
  * Compile a JSONPath query (RFC 9535) into a reusable query function.
  *
@@ -196,6 +243,9 @@ export declare function parseJSONPath(source: string): JSONPathAst;
  * - `query(data)` / `query.values(data)` - array of matched values
  * - `query.first(data)` - first matched value, or `undefined`
  * - `query.exists(data)` - true when the query selects at least one node
+ * - `query.iterate(data)` - a generator yielding matched values on
+ *   demand, in document order; `first`/`exists` are one pull of it, so
+ *   none of the three builds a nodelist it does not need
  * - `query.nodes(data)` - array of `{ path, value }` with normalized paths
  * - `query.paths(data)` - array of normalized paths (RFC 9535 section 2.7)
  * - `query.source` - the original query string
@@ -203,33 +253,113 @@ export declare function parseJSONPath(source: string): JSONPathAst;
  *   compiled path mode must agree with the eagerly compiled value mode)
  *
  * @param {string} source - The JSONPath expression
+ * @param {JSONPathOptions} [options] - Compile options
  * @returns {JSONPathQuery} The compiled query function
  * @throws {JSONPathSyntaxError} When the query is not valid RFC 9535
+ * @throws {TypeError} When `options.pathFunctions` is not a valid registry
  * @example
  * const q = compileJSONPath('$.store.book[?@.price < 10].title');
  * q(data); // ['Sayings of the Century', 'Moby Dick']
  * q.paths(data); // ["$['store']['book'][0]['title']", ...]
  */
-export declare function compileJSONPath(source: string): JSONPathQuery;
+export declare function compileJSONPath(source: string, options?: JSONPathOptions): JSONPathQuery;
 /**
  * Apply a JSONPath query to a JSON value in one call. Compiled queries
- * are cached (FIFO, 512 entries), so repeated calls with the same query
- * string reuse the compiled function.
+ * are cached (bounded LRU, 512 entries), so repeated calls with the
+ * same query string reuse the compiled function. A query compiled
+ * against a function-extension registry is cached under that registry.
  * @param {string} source - The JSONPath expression
  * @param {any} data - The JSON value to query
+ * @param {JSONPathOptions} [options] - Compile options
  * @returns {any[]} Array of matched values
  * @throws {JSONPathSyntaxError} When the query is not valid RFC 9535
  */
-export declare function queryJSONPath(source: string, data: any): any[];
+export declare function queryJSONPath(source: string, data: any, options?: JSONPathOptions): any[];
 /**
  * Validates a JSONPath expression strictly against the RFC 9535 grammar,
  * including well-typedness of function expressions. Unlike the heuristic
  * `isValidJSONPath` in basic.js, this uses the full parser.
+ *
+ * Without options this recognizes the five built-in functions and
+ * nothing else, which is what the registered `json-path` string format
+ * asserts: a format is a property of the string itself, so it must mean
+ * the same thing in every schema, independent of which extensions some
+ * host happens to have installed. Pass `options.pathFunctions` to
+ * validate against a registry instead - a host that wants its
+ * extensions asserted registers a tester bound to them.
+ *
  * @param {string} str - The JSONPath expression to validate
+ * @param {JSONPathOptions} [options] - Compile options
  * @returns {boolean} True when the string is a valid RFC 9535 query
  * @example
  * isValidJSONPathStrict('$.store.book[?@.price < 10]'); // true
  * isValidJSONPathStrict('$.store.book[0 5]'); // false
  * isValidJSONPathStrict('@.name'); // false (queries start at $)
  */
-export declare function isValidJSONPathStrict(str: string): boolean;
+export declare function isValidJSONPathStrict(str: string, options?: JSONPathOptions): boolean;
+/**
+ * The head of a variable-rooted path string: `$` followed by a variable
+ * name. The Jaren query format writes a path relative to a bound
+ * variable as `$name` plus ordinary RFC 9535 segments, and the query
+ * normalizer splits on exactly this production - so schema-time
+ * validation and compile-time parsing agree on where the segments start.
+ */
+export declare const RE_JSONPATH_VARIABLE_HEAD: RegExp;
+/**
+ * Validates a variable-rooted path string: `$name`, optionally followed
+ * by RFC 9535 segments (`$book.price`, `$b[?@.isbn]`, `$item`).
+ *
+ * This is the counterpart of `isValidJSONPathStrict` for paths whose
+ * root is a bound variable rather than the document. Such a string is
+ * not a valid RFC 9535 query - the RFC's root identifier is `$` alone -
+ * so it can only be checked by recognizing the head and validating the
+ * tail as segments, which is what the query normalizer does before it
+ * raises `JQ0004`. Without this, a schema could only pattern-check the
+ * head and had to leave the segment grammar to the compiler.
+ *
+ * @param {string} str - The variable-rooted path string to validate
+ * @param {JSONPathOptions} [options] - Parse options
+ * @returns {boolean} True when the string is a well-formed variable-rooted path
+ * @example
+ * isValidJSONPathSegments('$book.price'); // true
+ * isValidJSONPathSegments('$book'); // true (no segments)
+ * isValidJSONPathSegments('$book.price['); // false (unterminated segment)
+ * isValidJSONPathSegments('$.price'); // false (no variable name; that is json-path)
+ */
+export declare function isValidJSONPathSegments(str: string, options?: JSONPathOptions): boolean;
+/**
+ * Convert a singular JSONPath query - which includes every RFC 9535
+ * normalized path - to an RFC 6901 JSON Pointer, so the two addressing
+ * standards compose.
+ *
+ * Any singular form is accepted (`$['store']['book'][0]`, `$.store.book[0]`);
+ * non-singular queries and negative (from-the-end) indexes are rejected,
+ * because a pointer cannot express them.
+ *
+ * @param {string} source - A singular JSONPath query
+ * @returns {string} The equivalent JSON Pointer
+ * @throws {JSONPathSyntaxError} When the query is invalid, not singular,
+ *   or uses a negative index
+ * @example
+ * jsonPointerFromJSONPath("$['store']['book'][0]['a/b']"); // '/store/book/0/a~1b'
+ */
+export declare function jsonPointerFromJSONPath(source: string): string;
+/**
+ * Convert an RFC 6901 JSON Pointer to an RFC 9535 normalized path.
+ *
+ * A pointer token is one text with two readings (RFC 6901 lets `"2"`
+ * address both a `"2"` member and array element 2); a normalized path
+ * must pick one. Convention: a token that is a valid array index (digits,
+ * no leading zeros) becomes an index selector `[2]`, everything else a
+ * name selector `['name']`. A pointer addressing an object member that
+ * merely looks like an index is therefore converted to the index form -
+ * convert with the document in hand (e.g. via `query.paths`) when that
+ * distinction matters.
+ *
+ * @param {string} pointer - The JSON Pointer (e.g. `/store/book/0`)
+ * @returns {string} The normalized path (e.g. `$['store']['book'][0]`)
+ * @throws {JSONPointerSyntaxError} When the pointer is not valid RFC 6901
+ * @example
+ * jsonPathFromJSONPointer('/store/book/0'); // "$['store']['book'][0]"
+ */
+export declare function jsonPathFromJSONPointer(pointer: string): string;

package/dist/types/pointer.d.ts

@@ -1,3 +1,4 @@
+import { LabeledSyntaxError } from './errors.js';
 /**
  * Sentinel for the absence of a value, as distinct from the JSON value
  * `null`. This is the same sentinel as `JSONPATH_NOTHING` in path.js, so
@@ -8,9 +9,7 @@ export declare const JSONPOINTER_NOTHING: symbol;
  * Error thrown when a (relative) JSON Pointer is not valid RFC 6901 /
  * draft-luff-relative-json-pointer syntax.
  */
-export declare class JSONPointerSyntaxError extends SyntaxError {
-    source: any;
-    position: any;
+export declare class JSONPointerSyntaxError extends LabeledSyntaxError {
     constructor(message: any, source: any, position: any);
 }
 /**
@@ -63,6 +62,62 @@ export type RelativeJsonPointerResolver = (dataRoot: any, dataPath: string) => a
  * @throws {JSONPointerSyntaxError} When the pointer violates the grammar
  */
 export declare function parseRelativeJSONPointer(pointer: string): RelativeJsonPointer;
+/**
+ * Encode a single reference token for use inside an RFC 6901 JSON
+ * Pointer: `~` becomes `~0` and `/` becomes `~1` (RFC 6901 section 3).
+ * The write-side inverse of the parser's decode; the escape-free common
+ * case returns the input unchanged.
+ * @param {string|number} segment - The raw member name or array index
+ * @returns {string} The encoded reference token
+ * @example
+ * encodeJSONPointerSegment('a/b'); // 'a~1b'
+ */
+export declare function encodeJSONPointerSegment(segment: string | number): string;
+/**
+ * Decode one RFC 6901 reference token: `~1` becomes `/` and `~0` becomes
+ * `~`. The order is normative (RFC 6901 section 4) and not an accident of
+ * implementation — decoding `~0` first would turn `~01` into `~1` and then
+ * into `/`, so a member literally named `~1` would come back as `/`.
+ * The escape-free common case returns the input unchanged.
+ * @param {string} token - One encoded reference token (no `/` separators)
+ * @returns {string} The decoded member name
+ * @example
+ * decodeJSONPointerSegment('a~1b'); // 'a/b'
+ */
+export declare function decodeJSONPointerSegment(token: string): string;
+/**
+ * Format decoded reference tokens as an RFC 6901 JSON Pointer; the
+ * inverse of `parseJSONPointer`. An empty array formats as the empty
+ * (whole-document) pointer.
+ * @param {(string|number)[]} segments - Decoded reference tokens
+ * @returns {string} The JSON Pointer
+ * @example
+ * formatJSONPointer(['a/b', 0]); // '/a~1b/0'
+ */
+export declare function formatJSONPointer(segments: (string | number)[]): string;
+/**
+ * Parse a JSON Pointer into a path array, narrowing every canonical array
+ * index to a number and leaving all other tokens as decoded strings.
+ *
+ * RFC 6901 has no types: `/items/0/id` addresses element 0 of an array and
+ * member `"0"` of an object with the same token. This function resolves that
+ * lexically, not against a document — a token is a number when it is `0` or a
+ * digit sequence without leading zeros within the array-index range, which is
+ * the same rule the pointer compiler uses to pre-parse indexes. `"01"`,
+ * `"1e0"`, `"-"` and `"1abc"` therefore stay strings.
+ *
+ * The result is the `(string|number)[]` shape that error reporters and
+ * diffing tools use for data locations, so it pairs directly with a
+ * validation error's `instancePath`. `formatJSONPointer` is the inverse.
+ * @param {string} pointer - The JSON Pointer (e.g. `/store/book/0`)
+ * @returns {(string|number)[]} Decoded tokens with array indexes as numbers
+ * @throws {JSONPointerSyntaxError} When the pointer violates the grammar
+ * @example
+ * parseJSONPointerPath('/items/0/id');  // ['items', 0, 'id']
+ * parseJSONPointerPath('/items/01');    // ['items', '01']
+ * parseJSONPointerPath('/a~1b');        // ['a/b']
+ */
+export declare function parseJSONPointerPath(pointer: string): (string | number)[];
 /**
  * Compile a JSON Pointer (RFC 6901) into a reusable getter.
  *
@@ -85,20 +140,51 @@ export declare function compileJSONPointer(pointer: string): JsonPointerGetter;
  *
  * The relative part (level count, `#` form, trailing segments) compiles
  * once; per call only `dataPath` - the current location in `dataRoot` as
- * an RFC 6901 pointer - varies. The `#` form resolves to the member name
- * or array index of the location **as a string** (`''` at the root),
- * matching the historical behavior relied on by the validator's `$data`
- * keyword.
+ * an RFC 6901 pointer - varies.
+ *
+ * The root has no name: `0#` there yields `JSONPOINTER_NOTHING`, not `''`,
+ * so it stays distinguishable from the member named `''` (`{"": 1}` at
+ * `/`), which is a name a document can genuinely have.
+ *
+ * ### The `#` form and `hashIndex`
+ *
+ * Relative JSON Pointer says `#` yields the member *name* for an object
+ * member and the *index* — a number — for an array element. Telling those
+ * apart requires looking at the container, so the two modes cost different
+ * things and you choose per compile:
+ *
+ * - `hashIndex: 'string'` (**default**) answers from `dataPath` alone and
+ *   never touches `dataRoot`: an array position comes back as the string
+ *   `'1'`. This is the historical behavior the validator's `$data` keyword
+ *   relies on, and it is a string operation — tens of nanoseconds.
+ * - `hashIndex: 'number'` is the draft's answer. It walks to the parent of
+ *   the location to see whether it is an array, and returns `1` rather than
+ *   `'1'` when it is. Object member names are unaffected. When the parent
+ *   cannot be reached (the location does not exist in `dataRoot`) it falls
+ *   back to the string, because nothing proves the position is an index.
+ *
+ * Neither mode verifies that the location itself exists; the caller is
+ * expected to pass a location it actually reached. The non-`#` form must
+ * walk regardless, because it returns the value.
  *
  * @param {string} pointer - The relative pointer (e.g. `1/sibling`, `0#`)
+ * @param {{ hashIndex?: 'string'|'number' }} [options] - `hashIndex`
+ *   selects what the `#` form yields for an array position (default
+ *   `'string'`)
  * @returns {RelativeJsonPointerResolver} resolver returning
  *   the addressed value, or `JSONPOINTER_NOTHING`
  * @throws {JSONPointerSyntaxError} When the pointer is not valid
+ * @throws {TypeError} When `hashIndex` is neither `'string'` nor `'number'`
  * @example
  * const resolve = compileRelativeJSONPointer('1/limits');
  * resolve({ limits: { min: 2 } , value: 5 }, '/value'); // { min: 2 }
+ * @example
+ * const spec = compileRelativeJSONPointer('0#', { hashIndex: 'number' });
+ * spec({ a: ['x', 'y'] }, '/a/1'); // 1  (the number, per the draft)
  */
-export declare function compileRelativeJSONPointer(pointer: string): RelativeJsonPointerResolver;
+export declare function compileRelativeJSONPointer(pointer: string, options?: {
+    hashIndex?: 'string' | 'number';
+}): RelativeJsonPointerResolver;
 /**
  * Compile a data reference - the accepted forms of the validator's
  * `data`/`$data` keywords - into a reusable resolver. The dispatch is
@@ -106,9 +192,14 @@ export declare function compileRelativeJSONPointer(pointer: string): RelativeJso
  * Pointer, a leading `/` an absolute JSON Pointer, and `''` the root.
  *
  * @param {string} ref - The reference string
+ * @param {{ hashIndex?: 'string'|'number' }} [options] - forwarded to
+ *   {@link compileRelativeJSONPointer}; only the relative forms read it
  * @returns {RelativeJsonPointerResolver} resolver returning
  *   the addressed value, or `JSONPOINTER_NOTHING`
  * @throws {JSONPointerSyntaxError} When the reference is none of the
  *   accepted forms
+ * @throws {TypeError} When `hashIndex` is neither `'string'` nor `'number'`
  */
-export declare function compileDataRef(ref: string): RelativeJsonPointerResolver;
+export declare function compileDataRef(ref: string, options?: {
+    hashIndex?: 'string' | 'number';
+}): RelativeJsonPointerResolver;

package/dist/types/query/compile.d.ts

@@ -13,6 +13,18 @@ export declare const UNBOUND: unique symbol;
  * @returns {(frame: any[]) => boolean}
  */
 export declare function compileExistsTest(node: object): (frame: any[]) => boolean;
+/**
+ * Compile a query's AST root, optionally instrumenting every node
+ * evaluation against a step limit.
+ * @param {object} root - the AST root from normalizeQuery
+ * @param {{ slot: number, limit: number } | null} steps - the step
+ *   counter's frame slot and its limit, or null for no instrumentation
+ * @returns {(frame: any[]) => any} the root getter
+ */
+export declare function compileQueryRoot(root: object, steps: {
+    slot: number;
+    limit: number;
+} | null): (frame: any[]) => any;
 /**
  * Compile a normalized AST node into its getter closure.
  * @param {object} node - a frozen AST node from normalize.js