@jarenjs/json 0.9.2

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

@@ -0,0 +1,57 @@
+export { JtltCompileError, JtltRuntimeError } from './errors.js';
+/**
+ * Compile a Jaren JTLT 0.1 template into a reusable renderer.
+ *
+ * The returned function renders any input document to a string in the
+ * template's output method ('text' by default, 'xml' for markup with
+ * escaped interpolation). Metadata:
+ *
+ * - `render.externals` - user parameter names in first-appearance order
+ *   (`root` and `path` are engine-bound and excluded)
+ * - `render.output` - the resolved output method
+ * - `render.doc` - an independent, deeply frozen template copy
+ * - `render.stylesheet` - the frozen JSLT stylesheet it compiled to
+ *
+ * @param {any} doc - a bare rule array or `{"$jtlt":"0.1","output":...,
+ *   "rules":[]}` template envelope
+ * @param {object} [options] - compile options, passed to the JSLT layer
+ * @param {(schemaJson: any, docPath: string) => ((value: any) => boolean)}
+ *   [options.compileTypeTest] - validator-agnostic hook for schema
+ *   matches and schema operators inside segment expressions
+ * @param {number} [options.maxDepth=1024] - maximum dispatch nesting depth
+ * @returns {function} reusable `render(data, externals?)` function
+ * @throws {JtltCompileError} when compilation fails
+ * @example
+ * const render = compileJtltStylesheet([
+ *   { match: '$.items[*]', body: ['- ', '$.name', '\n'] },
+ * ]);
+ * render({ items: [{ name: 'a' }, { name: 'b' }] });
+ * // '- a\n- b\n'
+ */
+export declare function compileJtltStylesheet(doc: any, options?: {
+    compileTypeTest?: (schemaJson: any, docPath: string) => ((value: any) => boolean);
+    maxDepth?: number;
+}): Function;
+/**
+ * Render a JSON value with a JTLT template in one call. Object/array
+ * template documents are compiled once and cached by identity in a
+ * WeakMap.
+ * @param {any} template - JTLT template document
+ * @param {any} data - input JSON value
+ * @param {object} [externals] - user parameter bindings
+ * @param {object} [options] - compile options used on a cache miss
+ * @param {(schemaJson: any, docPath: string) => ((value: any) => boolean)}
+ *   [options.compileTypeTest] - schema type-test compiler
+ * @param {number} [options.maxDepth=1024] - maximum dispatch nesting depth
+ * @returns {string} the rendered output text
+ * @throws {JtltCompileError} when compilation fails
+ * @throws {JtltRuntimeError} when rendering fails
+ * @example
+ * renderText([{ match: '$.name', body: ['Hello ', '$', '!'] }],
+ *   { name: 'world' });
+ * // 'Hello world!'
+ */
+export declare function renderText(template: any, data: any, externals?: object, options?: {
+    compileTypeTest?: (schemaJson: any, docPath: string) => ((value: any) => boolean);
+    maxDepth?: number;
+}): string;

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

@@ -0,0 +1,8 @@
+export declare const RESERVED_PRIORITY_FLOOR = -1e+307;
+/**
+ * Normalize a frozen JTLT template document into a frozen model.
+ * @param {any} doc - deeply frozen template document
+ * @returns {object} frozen template model
+ * @throws {JtltCompileError} on TL0001-TL0003 and TL0006 shape errors
+ */
+export declare function normalizeJtltTemplate(doc: any): object;

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

@@ -0,0 +1,6 @@
+/**
+ * Create the serializer for one output method.
+ * @param {'text' | 'xml'} method - the template's output method
+ * @returns {(value: any) => string} segment-stream serializer
+ */
+export declare function createWriter(method: 'text' | 'xml'): (value: any) => string;

package/dist/types/path.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Sentinel for the absence of a value ("Nothing" in RFC 9535 terms), as
+ * distinct from the JSON value `null`.
+ */
+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;
+    constructor(message: any, source: any, position: any);
+}
+export type JSONPathNameSelector = {
+    /**
+     * - Discriminator
+     */
+    kind: 'name';
+    /**
+     * - The member name to select
+     */
+    name: string;
+};
+export type JSONPathWildcardSelector = {
+    /**
+     * - Discriminator
+     */
+    kind: 'wildcard';
+};
+export type JSONPathIndexSelector = {
+    /**
+     * - Discriminator
+     */
+    kind: 'index';
+    /**
+     * - The array index to select
+     */
+    index: number;
+};
+export type JSONPathSliceSelector = {
+    /**
+     * - Discriminator
+     */
+    kind: 'slice';
+    /**
+     * - Slice start, or null when omitted
+     */
+    start: number | null;
+    /**
+     * - Slice end (exclusive), or null when omitted
+     */
+    end: number | null;
+    /**
+     * - Slice step, or null when omitted
+     */
+    step: number | null;
+};
+export type JSONPathFilterSelector = {
+    /**
+     * - Discriminator
+     */
+    kind: 'filter';
+    /**
+     * - The parsed filter expression tree
+     */
+    expr: object;
+};
+export type JSONPathSelector = JSONPathNameSelector | JSONPathWildcardSelector | JSONPathIndexSelector | JSONPathSliceSelector | JSONPathFilterSelector;
+export type JSONPathSegment = {
+    /**
+     * - True for a descendant (`..`) segment
+     */
+    descendant: boolean;
+    /**
+     * - The segment's selectors
+     */
+    selectors: JSONPathSelector[];
+};
+export type JSONPathAst = {
+    /**
+     * - True for a relative query (`@`), false for a root query (`$`)
+     */
+    relative: boolean;
+    /**
+     * - The query's segments in order
+     */
+    segments: JSONPathSegment[];
+};
+export type JSONPathNode = {
+    /**
+     * - The normalized path (e.g. `$['store']['book'][0]`)
+     */
+    path: string;
+    /**
+     * - The matched value
+     */
+    value: any;
+};
+export type JSONPathQuery = ((data: any) => any[]) & {
+    values: (data: any) => any[];
+    first: (data: any) => any;
+    exists: (data: any) => boolean;
+    nodes: (data: any) => JSONPathNode[];
+    paths: (data: any) => string[];
+    source: string;
+    ast: JSONPathAst;
+};
+/**
+ * Selects a named object member (RFC 9535 name selector).
+ * @typedef {Object} JSONPathNameSelector
+ * @property {'name'} kind - Discriminator
+ * @property {string} name - The member name to select
+ */
+/**
+ * Selects all members of an object / all elements of an array
+ * (RFC 9535 wildcard selector).
+ * @typedef {Object} JSONPathWildcardSelector
+ * @property {'wildcard'} kind - Discriminator
+ */
+/**
+ * Selects an array element by index; negative indexes count from the end
+ * (RFC 9535 index selector).
+ * @typedef {Object} JSONPathIndexSelector
+ * @property {'index'} kind - Discriminator
+ * @property {number} index - The array index to select
+ */
+/**
+ * Selects a range of array elements (RFC 9535 array slice selector).
+ * `null` means the bound was omitted in the query.
+ * @typedef {Object} JSONPathSliceSelector
+ * @property {'slice'} kind - Discriminator
+ * @property {number | null} start - Slice start, or null when omitted
+ * @property {number | null} end - Slice end (exclusive), or null when omitted
+ * @property {number | null} step - Slice step, or null when omitted
+ */
+/**
+ * Selects children for which a filter expression yields a truthy result
+ * (RFC 9535 filter selector).
+ * @typedef {Object} JSONPathFilterSelector
+ * @property {'filter'} kind - Discriminator
+ * @property {object} expr - The parsed filter expression tree
+ */
+/**
+ * Any RFC 9535 selector, discriminated by its `kind` property.
+ * @typedef {JSONPathNameSelector | JSONPathWildcardSelector | JSONPathIndexSelector | JSONPathSliceSelector | JSONPathFilterSelector} JSONPathSelector
+ */
+/**
+ * One segment of a JSONPath query: a child (`.` / `[...]`) or descendant
+ * (`..`) step holding one or more selectors.
+ * @typedef {Object} JSONPathSegment
+ * @property {boolean} descendant - True for a descendant (`..`) segment
+ * @property {JSONPathSelector[]} selectors - The segment's selectors
+ */
+/**
+ * The parsed AST of a JSONPath query.
+ * @typedef {Object} JSONPathAst
+ * @property {boolean} relative - True for a relative query (`@`), false for a root query (`$`)
+ * @property {JSONPathSegment[]} segments - The query's segments in order
+ */
+/**
+ * One result of a JSONPath query in nodes mode: the matched value together
+ * with its normalized path (RFC 9535 section 2.7).
+ * @typedef {Object} JSONPathNode
+ * @property {string} path - The normalized path (e.g. `$['store']['book'][0]`)
+ * @property {any} value - The matched value
+ */
+/**
+ * A compiled JSONPath query. Calling it returns the matched values; the
+ * attached methods expose the other result modes, and `source`/`ast`
+ * expose the original query string and its parsed (deeply frozen) AST.
+ * @typedef {((data: any) => any[]) & {
+ *   values: (data: any) => any[],
+ *   first: (data: any) => any,
+ *   exists: (data: any) => boolean,
+ *   nodes: (data: any) => JSONPathNode[],
+ *   paths: (data: any) => string[],
+ *   source: string,
+ *   ast: JSONPathAst,
+ * }} JSONPathQuery
+ */
+/**
+ * Parse a JSONPath query string into an AST.
+ * @param {string} source - The JSONPath expression (e.g. `$.store.book[?@.price < 10].title`)
+ * @returns {JSONPathAst} The parsed query AST
+ * @throws {JSONPathSyntaxError} When the query violates the RFC 9535 grammar
+ */
+export declare function parseJSONPath(source: string): JSONPathAst;
+/**
+ * Compile a JSONPath query (RFC 9535) into a reusable query function.
+ *
+ * The returned function applies the query to a JSON value and returns
+ * the resulting nodelist as an array of values. It also carries helper
+ * methods:
+ *
+ * - `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.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
+ * - `query.ast` - the parsed query AST (deeply frozen; the lazily
+ *   compiled path mode must agree with the eagerly compiled value mode)
+ *
+ * @param {string} source - The JSONPath expression
+ * @returns {JSONPathQuery} The compiled query function
+ * @throws {JSONPathSyntaxError} When the query is not valid RFC 9535
+ * @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;
+/**
+ * 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.
+ * @param {string} source - The JSONPath expression
+ * @param {any} data - The JSON value to query
+ * @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[];
+/**
+ * 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.
+ * @param {string} str - The JSONPath expression to validate
+ * @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;

package/dist/types/pointer.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 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
+ * pointer and path results can share checks.
+ */
+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;
+    constructor(message: any, source: any, position: any);
+}
+/**
+ * Parse a JSON Pointer strictly per RFC 6901 into its decoded segments.
+ * @param {string} pointer - The JSON Pointer (e.g. `/store/book/0`)
+ * @returns {string[]} Array of decoded reference tokens
+ * @throws {JSONPointerSyntaxError} When the pointer violates the grammar
+ */
+export declare function parseJSONPointer(pointer: string): string[];
+export type RelativeJsonPointer = {
+    /**
+     * - Number of levels to ascend from the current location
+     */
+    levels: number;
+    /**
+     * - True for the `#` form, which addresses the member name or array index itself
+     */
+    hash: boolean;
+    /**
+     * - Decoded reference tokens applied after ascending
+     */
+    segments: string[];
+};
+export type JsonPointerGetter = (root: any) => any;
+export type RelativeJsonPointerResolver = (dataRoot: any, dataPath: string) => any;
+/**
+ * A parsed Relative JSON Pointer (draft-luff-relative-json-pointer).
+ * @typedef {Object} RelativeJsonPointer
+ * @property {number} levels - Number of levels to ascend from the current location
+ * @property {boolean} hash - True for the `#` form, which addresses the member name or array index itself
+ * @property {string[]} segments - Decoded reference tokens applied after ascending
+ */
+/**
+ * A compiled JSON Pointer: returns the value addressed in `root`, or the
+ * `JSONPOINTER_NOTHING` sentinel when the pointer does not address a location.
+ * @typedef {(root: any) => any} JsonPointerGetter
+ */
+/**
+ * A compiled Relative JSON Pointer / data reference: resolves against the
+ * RFC 6901 location `dataPath` inside `dataRoot`, returning the addressed
+ * value or the `JSONPOINTER_NOTHING` sentinel.
+ * @typedef {(dataRoot: any, dataPath: string) => any} RelativeJsonPointerResolver
+ */
+/**
+ * Parse a Relative JSON Pointer strictly per
+ * draft-luff-relative-json-pointer: a non-negative integer without
+ * leading zeros, followed by `#` or a JSON Pointer.
+ * @param {string} pointer - The relative pointer (e.g. `1/sibling`, `0#`)
+ * @returns {RelativeJsonPointer} The parsed relative pointer
+ * @throws {JSONPointerSyntaxError} When the pointer violates the grammar
+ */
+export declare function parseRelativeJSONPointer(pointer: string): RelativeJsonPointer;
+/**
+ * Compile a JSON Pointer (RFC 6901) into a reusable getter.
+ *
+ * All decisions are taken at compile time: member names are pre-decoded,
+ * array indexes pre-parsed, and the getter is specialized by segment
+ * count. Resolution allocates nothing.
+ *
+ * @param {string} pointer - The JSON Pointer (e.g. `/store/book/0`)
+ * @returns {JsonPointerGetter} getter returning the addressed value, or
+ *   `JSONPOINTER_NOTHING` when the pointer does not address a location
+ * @throws {JSONPointerSyntaxError} When the pointer is not valid RFC 6901
+ * @example
+ * const get = compileJSONPointer('/limits/min');
+ * get({ limits: { min: 2 } }); // 2
+ * get({}); // JSONPOINTER_NOTHING
+ */
+export declare function compileJSONPointer(pointer: string): JsonPointerGetter;
+/**
+ * Compile a Relative JSON Pointer into a reusable resolver.
+ *
+ * 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.
+ *
+ * @param {string} pointer - The relative pointer (e.g. `1/sibling`, `0#`)
+ * @returns {RelativeJsonPointerResolver} resolver returning
+ *   the addressed value, or `JSONPOINTER_NOTHING`
+ * @throws {JSONPointerSyntaxError} When the pointer is not valid
+ * @example
+ * const resolve = compileRelativeJSONPointer('1/limits');
+ * resolve({ limits: { min: 2 } , value: 5 }, '/value'); // { min: 2 }
+ */
+export declare function compileRelativeJSONPointer(pointer: string): RelativeJsonPointerResolver;
+/**
+ * Compile a data reference - the accepted forms of the validator's
+ * `data`/`$data` keywords - into a reusable resolver. The dispatch is
+ * decided once at compile time: a leading digit is a Relative JSON
+ * Pointer, a leading `/` an absolute JSON Pointer, and `''` the root.
+ *
+ * @param {string} ref - The reference string
+ * @returns {RelativeJsonPointerResolver} resolver returning
+ *   the addressed value, or `JSONPOINTER_NOTHING`
+ * @throws {JSONPointerSyntaxError} When the reference is none of the
+ *   accepted forms
+ */
+export declare function compileDataRef(ref: string): RelativeJsonPointerResolver;

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

@@ -0,0 +1,21 @@
+/**
+ * Sentinel stored in the frame slot of an external parameter the caller
+ * did not bind; evaluating a reference to it raises JQ2006.
+ */
+export declare const UNBOUND: unique symbol;
+/**
+ * Existence-only compilation for `$exists`/`$empty` (and any future
+ * boolean context): paths never materialize a result sequence (the
+ * analogue of path.js's compileExists). Takes the operand AST node -
+ * this is why registry `compile` functions receive arg nodes, not just
+ * getters.
+ * @param {object} node - a frozen AST node from normalize.js
+ * @returns {(frame: any[]) => boolean}
+ */
+export declare function compileExistsTest(node: object): (frame: any[]) => boolean;
+/**
+ * Compile a normalized AST node into its getter closure.
+ * @param {object} node - a frozen AST node from normalize.js
+ * @returns {(frame: any[]) => any} getter returning an item, EMPTY, or a Seq
+ */
+export declare function compileNode(node: object): (frame: any[]) => any;

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

@@ -0,0 +1,18 @@
+/**
+ * Error thrown when a query document is rejected at compile time
+ * (`JQ0xxx` codes, QUERY-FORMAT.md section 10.2).
+ */
+export declare class JsonQueryCompileError extends Error {
+    code: any;
+    docPath: any;
+    constructor(code: any, message: any, docPath: any);
+}
+/**
+ * Error thrown when evaluating a compiled query fails
+ * (`JQ2xxx` codes, QUERY-FORMAT.md section 10.3).
+ */
+export declare class JsonQueryRuntimeError extends Error {
+    code: any;
+    docPath: any;
+    constructor(code: any, message: any, docPath: any);
+}

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

@@ -0,0 +1,70 @@
+export { JsonQueryCompileError, JsonQueryRuntimeError } from './errors.js';
+/**
+ * Compile a Jaren JSON Query document into a reusable query function.
+ *
+ * The returned function applies the query to a JSON value and returns the
+ * result as plain JSON: `undefined` for the empty sequence, the item
+ * itself for a singleton result, an array of items for a longer sequence.
+ * It also carries helper methods and metadata:
+ *
+ * - `query(data, externals?)` - the query result as described above
+ * - `query.first(data, externals?)` - first item of the result, or `undefined`
+ * - `query.exists(data, externals?)` - true when the result is non-empty
+ * - `query.ebv(data, externals?)` - the effective boolean value of the
+ *   result per the EBV table (section 2.2): empty -> false, a singleton
+ *   per its type (array/object -> true, D3), two or more items ->
+ *   `JsonQueryRuntimeError` JQ2003. Computed on the internal sequence
+ *   value, before the plain-JSON mapping - the mapped result is ambiguous
+ *   there (an array is both a multi-item sequence and one array item).
+ * - `query.externals` - names of the external parameters (section 9), in
+ *   order of first appearance; bind them via the `externals` argument
+ *   (`{ name: value, ... }`). Evaluating a reference to an unbound
+ *   external raises `JQ2006`.
+ * - `query.doc` - a deeply frozen copy of the query document (the
+ *   caller's object is never frozen)
+ *
+ * @param {any} doc - the query document (any JSON value; a bare RFC 9535
+ *   JSONPath string is the degenerate query)
+ * @param {object} [options] - compile options
+ * @param {(schemaJson: any, docPath: string) => ((value: any) => boolean)}
+ *   [options.compileTypeTest] - hook compiling a JSON Schema literal into
+ *   a boolean item predicate, called once per schema literal at query
+ *   compile time (QUERY-FORMAT.md section 8.11). `@jarenjs/validate/query`
+ *   exports `createTypeTestCompiler()` producing one; any conforming
+ *   implementation works - this package never imports the validator.
+ *   Without a hook, the schema operators `$valid`/`$assert`/`$as` are
+ *   compile error JQ0008.
+ * @param {object} [options.extensions] - package-internal operator
+ *   extension point, the operator analogue of `compileTypeTest` (used by
+ *   the JSLT layer; not a public contract). A plain object of
+ *   `name -> entry` following the operator registry contract; see
+ *   normalizeQuery in normalize.js for the full shape. The published
+ *   format vocabulary is unchanged: without extensions, documents using
+ *   such operators fail JQ0002.
+ * @returns {function} the compiled query function
+ * @throws {JsonQueryCompileError} when the document violates the format
+ * @example
+ * const q = compileJsonQuery({
+ *   "$let": { "b": "$.store.book[0]" },
+ *   "$return": { "title": "$b.title", "cheap": { "$lt": ["$b.price", "$max"] } }
+ * });
+ * q.externals; // ['max']
+ * q(data, { max: 10 }); // { title: 'Sayings of the Century', cheap: true }
+ */
+export declare function compileJsonQuery(doc: any, options?: {
+    compileTypeTest?: (schemaJson: any, docPath: string) => ((value: any) => boolean);
+    extensions?: object;
+}): Function;
+/**
+ * Apply a Jaren JSON Query document to a JSON value in one call.
+ * Compiled queries are cached: object documents by identity (WeakMap),
+ * string documents (the degenerate JSONPath case) by value (FIFO, 512
+ * entries - the same pattern as `queryJSONPath`).
+ * @param {any} doc - the query document
+ * @param {any} data - the JSON value to query
+ * @param {object} [externals] - external parameter bindings (`{ name: value }`)
+ * @returns {any} the query result (undefined | item | array of items)
+ * @throws {JsonQueryCompileError} when the document violates the format
+ * @throws {JsonQueryRuntimeError} on any JQ2xxx runtime condition
+ */
+export declare function queryJson(doc: any, data: any, externals?: object): any;

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

@@ -0,0 +1,68 @@
+/** Statically empty (the node always evaluates to the empty sequence). */
+export declare const CARD_ZERO = 0;
+/** Always exactly one item; compile.js skips all sequence checks. */
+export declare const CARD_ONE = 1;
+/** Zero or one item. */
+export declare const CARD_OPT = 2;
+/** Any number of items (the analysis top). */
+export declare const CARD_MANY = 3;
+/**
+ * join = least upper bound over {ZERO, ONE, OPT, MANY}: the cardinality
+ * of "one of the two branches" ($if).
+ * @param {number} a - a CARD_* value
+ * @param {number} b - a CARD_* value
+ * @returns {number}
+ */
+export declare function joinCard(a: number, b: number): number;
+/**
+ * sum = cardinality of two concatenated sequences ($seq); two non-empty
+ * contributions can exceed one item, which only MANY can express.
+ * @param {number} a - a CARD_* value
+ * @param {number} b - a CARD_* value
+ * @returns {number}
+ */
+export declare function sumCard(a: number, b: number): number;
+/**
+ * Deep-copy a JSON value and freeze every object/array in the copy.
+ * Used for `$const` values and the compiled query's `.doc` property, so
+ * the engine never freezes (or shares mutable state with) caller objects.
+ * @param {any} value - a JSON value
+ * @returns {any} an independent, deeply frozen copy
+ */
+export declare function deepFreezeCopy(value: any): any;
+/**
+ * Normalize a query document into the internal AST.
+ * @param {any} doc - the query document (any JSON value)
+ * @param {object} [options] - compile options
+ * @param {(schemaJson: any, docPath: string) => ((value: any) => boolean)}
+ *   [options.compileTypeTest] - host hook compiling a JSON Schema literal
+ *   into a boolean item predicate (QUERY-FORMAT.md section 8.11). Called
+ *   once per schema literal, at query compile time. Without it, schema
+ *   operators ($valid/$assert/$as) are compile error JQ0008.
+ * @param {object} [options.extensions] - package-internal operator
+ *   extension point, the operator analogue of `compileTypeTest` (used by
+ *   the JSLT layer; not a public contract). A plain object of
+ *   `name -> entry`, where entry follows the operator registry contract
+ *   (`params`/`result`/`compile`, operators.js header) plus an optional
+ *   `normalize(arg, docPath, opPath, scope, ctx, helpers) -> {args, card?}`
+ *   override for polymorphic value shapes. Names must start with '$' and
+ *   must not collide with the core vocabulary (TypeError - a host
+ *   programming error, not a JQ0xxx document error). The published format
+ *   and its schema are unchanged: without extensions, the same documents
+ *   fail JQ0002.
+ * @returns {{ root: object, frameSize: number, externals: {name: string, slot: number}[] }}
+ *   the AST root, the frame size, and the external parameters in order of
+ *   first appearance (slot order)
+ * @throws {JsonQueryCompileError} on any JQ0xxx condition
+ */
+export declare function normalizeQuery(doc: any, options?: {
+    compileTypeTest?: (schemaJson: any, docPath: string) => ((value: any) => boolean);
+    extensions?: object;
+}): {
+    root: object;
+    frameSize: number;
+    externals: {
+        name: string;
+        slot: number;
+    }[];
+};