@jarenjs/json 0.9.2 → 0.34.2

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

@@ -1,18 +1,82 @@
+import { CodedError } from '@jarenjs/core/errors';
+/**
+ * The runtime code table (the `CSV_CODES` shape): one entry per code
+ * the engine can raise, proven in sync with QUERY-FORMAT.md §10's
+ * normative tables by a test — the table cannot silently drift from
+ * the spec.
+ */
+export declare const QUERY_CODES: Readonly<{
+    JQ0001: "object mixes $-prefixed and plain keys";
+    JQ0002: "unknown operator or $-key outside the vocabulary";
+    JQ0003: "known phrase with bad arity, value shape, or key combination";
+    JQ0004: "string starting $ is not a valid path or escape";
+    JQ0005: "variable reference neither bound nor a declared external";
+    JQ0006: "version envelope with unknown or non-string $query";
+    JQ0007: "duplicate variable binding within one phrase";
+    JQ0008: "schema operator in a query compiled without a type-test compiler";
+    JQ0009: "schema literal rejected by the type-test compiler";
+    JQ0010: "$call/$collation naming no registered function/collation";
+    JQ0011: "expression nesting deeper than limits.depth";
+    JQ2001: "runtime type error";
+    JQ2002: "$idiv/$mod by zero";
+    JQ2003: "EBV of a multi-item sequence";
+    JQ2004: "$map key expression not a single string";
+    JQ2005: "incomparable $orderby/$sort keys";
+    JQ2006: "reference to an unbound external parameter";
+    JQ2007: "resource guard: an operator result exceeding an implementation limit";
+    JQ2008: "schema assertion failure";
+    JQ2009: "an execution limit exceeded";
+    JQ2010: "a registered $call function threw";
+    JQ2011: "the input document is undefined";
+}>;
+/**
+ * Shared constructor body for the two query error classes: `cause`
+ * retains what host code threw, BY VALUE — set via an own property
+ * even for `undefined`, so presence is testable (the base's `hasOwn`
+ * options form, passed through unchanged).
+ */
+declare class JsonQueryError extends CodedError {
+    /**
+     * @param {string} name - The public class name for `error.name`
+     * @param {string} code
+     * @param {string} reason
+     * @param {string} docPath
+     * @param {{ cause?: unknown }} [options]
+     */
+    constructor(name: string, code: string, reason: string, docPath: string, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * 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);
+export declare class JsonQueryCompileError extends JsonQueryError {
+    /**
+     * @param {string} code
+     * @param {string} reason
+     * @param {string} docPath
+     * @param {{ cause?: unknown }} [options] - `cause` retains what a
+     *   host hook (e.g. `compileTypeTest`) threw
+     */
+    constructor(code: string, reason: string, docPath: string, options?: {
+        cause?: unknown;
+    });
 }
 /**
  * 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);
+export declare class JsonQueryRuntimeError extends JsonQueryError {
+    /**
+     * @param {string} code
+     * @param {string} reason
+     * @param {string} docPath
+     * @param {{ cause?: unknown }} [options] - `cause` retains what host
+     *   code threw
+     */
+    constructor(code: string, reason: string, docPath: string, options?: {
+        cause?: unknown;
+    });
 }
+export {};

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

@@ -1,10 +1,274 @@
-export { JsonQueryCompileError, JsonQueryRuntimeError } from './errors.js';
+import { NODE_KINDS } from './normalize.js';
+export { JsonQueryCompileError, JsonQueryRuntimeError, QUERY_CODES } from './errors.js';
+export { NODE_KINDS };
+export { annotateTypes, TYPE_TAGS } from './types.js';
+export type JsonQueryLimits = {
+    /**
+     * - Caps every FLWOR phrase
+     * materialization and tightens `$range`'s resource guard; exceeding
+     * it is `JQ2009` (`$range` keeps its historical `JQ2007`).
+     */
+    sequenceItems?: number;
+    /**
+     * - Caps the final result at the
+     * query boundary (`JQ2009`); checked after evaluation, and
+     * deliberately bypassed by `first`/`exists`/`ebv`.
+     */
+    resultItems?: number;
+    /**
+     * - Caps expression-node evaluations
+     * (`JQ2009`). This is the one limit that bounds *work* rather than
+     * output, so it is also the one that costs: setting it compiles a
+     * counter check into every node, roughly halving throughput. A step
+     * is one node evaluation, not one primitive operation - a single
+     * node that loops internally (`$range` materialization, a general
+     * comparison's cross product) counts once.
+     */
+    steps?: number;
+    /**
+     * - Caps expression nesting, enforced at
+     * compile time (`JQ0011`). The language has no recursion, so the
+     * compiled closure tree's evaluation depth IS the document's static
+     * nesting: checking it once is exact and costs nothing to evaluate.
+     */
+    depth?: number;
+};
+export type JsonQueryOptions = {
+    /**
+     * 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.
+     */
+    compileTypeTest?: (schemaJson: any, docPath: string) => ((value: any) => boolean);
+    /**
+     * - 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.
+     */
+    extensions?: object;
+    /**
+     * Registry of named trusted pure host functions for `$call`
+     * (QUERY-FORMAT.md section 8.12); an unregistered or empty name is
+     * rejected at compile time (JQ0010 / TypeError).
+     */
+    functions?: Record<string, (...args: any[]) => any>;
+    /**
+     * Registry of named pure compare functions for `$orderby`'s
+     * `$collation` member (QUERY-FORMAT.md section 6.6).
+     */
+    collations?: Record<string, (a: string, b: string) => number>;
+    /**
+     * Registry of custom JSONPath function extensions (RFC 9535 section
+     * 2.4), available inside the filters of every path string the
+     * document contains. Deliberately separate from `functions`: that
+     * registry extends the query vocabulary through `$call`, this one
+     * extends the RFC 9535 grammar the path strings are written in.
+     */
+    pathFunctions?: Record<string, import('../path.js').JSONPathFunction>;
+    /**
+     * - Enforced execution limits.
+     */
+    limits?: JsonQueryLimits;
+    /**
+     * - Closed-world compilation:
+     * the variable names (no `$` sigil) the document may leave free.
+     * Every other free variable is compile error `JQ0005` at its own
+     * reference site, so a query cannot silently acquire a parameter the
+     * host never meant to expose. `[]` declares none. Omitted, the open
+     * world of QUERY-FORMAT.md section 9 applies: use is the declaration.
+     */
+    externals?: readonly string[];
+    /**
+     * - On `compileJsonQuery`: additionally
+     * expose the normalized-form record (QUERY-FORMAT.md Appendix C.1) at
+     * `query.analysis`, from the same normalization. Compilation itself
+     * stays strict — schema hooks remain required.
+     */
+    analysis?: boolean;
+};
+export type JsonQueryAnalysis = {
+    /**
+     * - see the compatibility policy (C.7)
+     */
+    astVersion: number;
+    /**
+     * - the frozen node tree (C.3)
+     */
+    root: object;
+    externals: readonly {
+        name: string;
+        slot: number;
+    }[];
+    frameSize: number;
+    dependencies: Readonly<JsonQueryDependencies>;
+    limits: object | null;
+};
+export type JsonQueryDependencies = {
+    externals: readonly string[];
+    operators: readonly string[];
+    functions: readonly string[];
+    collations: readonly string[];
+};
+export type JsonQueryExplanation = {
+    externals: string[];
+    operators: string[];
+    functions: string[];
+    collations: string[];
+    limits: {
+        sequenceItems: number | null;
+        resultItems: number | null;
+        steps: number | null;
+        depth: number | null;
+    } | null;
+};
+export type CompiledJsonQuery = ((data: any, externals?: Record<string, any>) => any) & {
+    first: (data: any, externals?: Record<string, any>) => any;
+    exists: (data: any, externals?: Record<string, any>) => boolean;
+    ebv: (data: any, externals?: Record<string, any>) => boolean;
+    externals: readonly string[];
+    doc: any;
+    dependencies: Readonly<JsonQueryDependencies>;
+    explain: () => JsonQueryExplanation;
+    analysis?: Readonly<JsonQueryAnalysis>;
+};
+/**
+ * The enforced query limits (QUERY-FORMAT.md section 8.12). These are
+ * deterministic result/phrase-OUTPUT caps, not general resource
+ * budgets: they bound what a phrase or the query hands onward, never
+ * the memory, work, fan-out or recursion spent producing it (a group
+ * or order barrier may accumulate arbitrarily many items behind a
+ * small final result). Untrusted queries need worker isolation, not
+ * these limits.
+ * @typedef {Object} JsonQueryLimits
+ * @property {number} [sequenceItems] - Caps every FLWOR phrase
+ *   materialization and tightens `$range`'s resource guard; exceeding
+ *   it is `JQ2009` (`$range` keeps its historical `JQ2007`).
+ * @property {number} [resultItems] - Caps the final result at the
+ *   query boundary (`JQ2009`); checked after evaluation, and
+ *   deliberately bypassed by `first`/`exists`/`ebv`.
+ * @property {number} [steps] - Caps expression-node evaluations
+ *   (`JQ2009`). This is the one limit that bounds *work* rather than
+ *   output, so it is also the one that costs: setting it compiles a
+ *   counter check into every node, roughly halving throughput. A step
+ *   is one node evaluation, not one primitive operation - a single
+ *   node that loops internally (`$range` materialization, a general
+ *   comparison's cross product) counts once.
+ * @property {number} [depth] - Caps expression nesting, enforced at
+ *   compile time (`JQ0011`). The language has no recursion, so the
+ *   compiled closure tree's evaluation depth IS the document's static
+ *   nesting: checking it once is exact and costs nothing to evaluate.
+ */
+/**
+ * Compile options for {@link compileJsonQuery}.
+ * @typedef {Object} JsonQueryOptions
+ * @property {(schemaJson: any, docPath: string) => ((value: any) => boolean)} [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.
+ * @property {object} [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.
+ * @property {Record<string, (...args: any[]) => any>} [functions]
+ *   Registry of named trusted pure host functions for `$call`
+ *   (QUERY-FORMAT.md section 8.12); an unregistered or empty name is
+ *   rejected at compile time (JQ0010 / TypeError).
+ * @property {Record<string, (a: string, b: string) => number>} [collations]
+ *   Registry of named pure compare functions for `$orderby`'s
+ *   `$collation` member (QUERY-FORMAT.md section 6.6).
+ * @property {Record<string, import('../path.js').JSONPathFunction>} [pathFunctions]
+ *   Registry of custom JSONPath function extensions (RFC 9535 section
+ *   2.4), available inside the filters of every path string the
+ *   document contains. Deliberately separate from `functions`: that
+ *   registry extends the query vocabulary through `$call`, this one
+ *   extends the RFC 9535 grammar the path strings are written in.
+ * @property {JsonQueryLimits} [limits] - Enforced execution limits.
+ * @property {readonly string[]} [externals] - Closed-world compilation:
+ *   the variable names (no `$` sigil) the document may leave free.
+ *   Every other free variable is compile error `JQ0005` at its own
+ *   reference site, so a query cannot silently acquire a parameter the
+ *   host never meant to expose. `[]` declares none. Omitted, the open
+ *   world of QUERY-FORMAT.md section 9 applies: use is the declaration.
+ * @property {boolean} [analysis] - On `compileJsonQuery`: additionally
+ *   expose the normalized-form record (QUERY-FORMAT.md Appendix C.1) at
+ *   `query.analysis`, from the same normalization. Compilation itself
+ *   stays strict — schema hooks remain required.
+ */
+/**
+ * The published normalized-form record (QUERY-FORMAT.md Appendix C.1):
+ * what `analyzeQuery` returns and `compileJsonQuery`'s `analysis`
+ * option exposes.
+ * @typedef {Object} JsonQueryAnalysis
+ * @property {number} astVersion - see the compatibility policy (C.7)
+ * @property {object} root - the frozen node tree (C.3)
+ * @property {readonly { name: string, slot: number }[]} externals
+ * @property {number} frameSize
+ * @property {Readonly<JsonQueryDependencies>} dependencies
+ * @property {object | null} limits
+ */
+/**
+ * The frozen dependency record of a compiled query (saved-rule
+ * vetting): the external names it binds, the operators it uses, and
+ * the registered functions/collations it resolved.
+ * @typedef {Object} JsonQueryDependencies
+ * @property {readonly string[]} externals
+ * @property {readonly string[]} operators
+ * @property {readonly string[]} functions
+ * @property {readonly string[]} collations
+ */
+/**
+ * A plain-JSON explanation of a compiled query: its dependencies plus
+ * the enforced limits. A fresh value each `explain()` call.
+ * @typedef {Object} JsonQueryExplanation
+ * @property {string[]} externals
+ * @property {string[]} operators
+ * @property {string[]} functions
+ * @property {string[]} collations
+ * @property {{ sequenceItems: number | null, resultItems: number | null, steps: number | null, depth: number | null } | null} limits
+ */
+/**
+ * The compiled query returned by {@link compileJsonQuery}: the query
+ * function itself, carrying its helper methods and metadata.
+ * @typedef {((data: any, externals?: Record<string, any>) => any) & {
+ *   first: (data: any, externals?: Record<string, any>) => any,
+ *   exists: (data: any, externals?: Record<string, any>) => boolean,
+ *   ebv: (data: any, externals?: Record<string, any>) => boolean,
+ *   externals: readonly string[],
+ *   doc: any,
+ *   dependencies: Readonly<JsonQueryDependencies>,
+ *   explain: () => JsonQueryExplanation,
+ *   analysis?: Readonly<JsonQueryAnalysis>,
+ * }} CompiledJsonQuery
+ */
 /**
  * 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.
+ *
+ * The `data` argument MUST be a JSON value (section 2.1). The engine does
+ * not deep-validate it - that would cost a full walk per call - so a
+ * non-JSON value inside the document simply flows through as an opaque
+ * item. The single exception is `undefined`, rejected with `JQ2011`
+ * because this API already spends `undefined` on the empty sequence.
+ * An external bound to `undefined` reads as unbound (`JQ2006` on use).
+ *
  * It also carries helper methods and metadata:
  *
  * - `query(data, externals?)` - the query result as described above
@@ -22,26 +286,15 @@ export { JsonQueryCompileError, JsonQueryRuntimeError } from './errors.js';
  *   external raises `JQ2006`.
  * - `query.doc` - a deeply frozen copy of the query document (the
  *   caller's object is never frozen)
+ * - `query.dependencies` - what the query depends on (frozen JSON):
+ *   external names, operators, registered functions and collations
+ * - `query.explain()` - a fresh plain-JSON explanation: the
+ *   dependencies plus the enforced limits
  *
  * @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
+ * @param {JsonQueryOptions} [options] - compile options
+ * @returns {CompiledJsonQuery} the compiled query function
  * @throws {JsonQueryCompileError} when the document violates the format
  * @example
  * const q = compileJsonQuery({
@@ -51,15 +304,54 @@ export { JsonQueryCompileError, JsonQueryRuntimeError } from './errors.js';
  * 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;
+export declare function compileJsonQuery(doc: any, options?: JsonQueryOptions): CompiledJsonQuery;
+/**
+ * The version of the published normalized form (QUERY-FORMAT.md
+ * Appendix C.7): bumped when a node kind is added or removed, a
+ * published field is removed or retyped, or an appendix invariant
+ * changes. Adding an optional field is NOT a bump.
+ */
+export declare const AST_VERSION = 1;
+/**
+ * Analyse a query document WITHOUT compiling it: the engine's own
+ * normalized reading of the document — the frozen node tree, the
+ * externals in first-appearance order, the frame size and the
+ * dependency sets — published as the versioned contract of
+ * QUERY-FORMAT.md Appendix C. Another package walks this instead of
+ * re-implementing the grammar, and an unknown `kind` in its dispatch is
+ * a loud failure instead of a silent divergence.
+ *
+ * Analysis applies every JQ0xxx rejection compilation would, with one
+ * difference (Appendix C.1): schema literals do not require
+ * `options.compileTypeTest` — without the hook they normalize to `raw`
+ * nodes whose `test` is `null`, so a document can be analysed by a
+ * consumer that could not execute it. With the hook supplied, analysis
+ * compiles the predicates exactly as compilation would.
+ * @param {any} doc - the query document (any JSON value)
+ * @param {JsonQueryOptions} [options] - the same options as
+ *   `compileJsonQuery`
+ * @returns {{ astVersion: number, root: object, externals: readonly
+ *   { name: string, slot: number }[], frameSize: number,
+ *   dependencies: Readonly<JsonQueryDependencies>, limits: object | null }}
+ * @throws {JsonQueryCompileError} on any JQ0xxx condition (except
+ *   JQ0008, which analysis does not raise)
+ */
+export declare function analyzeQuery(doc: any, options?: JsonQueryOptions): {
+    astVersion: number;
+    root: object;
+    externals: readonly {
+        name: string;
+        slot: number;
+    }[];
+    frameSize: number;
+    dependencies: Readonly<JsonQueryDependencies>;
+    limits: object | null;
+};
 /**
  * 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`).
+ * Compiled queries are cached: object documents by identity (weak),
+ * string documents (the degenerate JSONPath case) by value (bounded
+ * LRU, 512 entries — the shared `@jarenjs/core/cache` primitive).
  * @param {any} doc - the query document
  * @param {any} data - the JSON value to query
  * @param {object} [externals] - external parameter bindings (`{ name: value }`)

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

@@ -1,3 +1,10 @@
+/**
+ * The twelve node kinds of the normalized form, sorted — the published
+ * AST contract (QUERY-FORMAT.md Appendix C). An exhaustiveness gate
+ * asserts a corpus exercising every construct produces exactly this
+ * set, so a new kind cannot ship undocumented.
+ */
+export declare const NODE_KINDS: readonly string[];
 /** 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. */
@@ -22,6 +29,15 @@ export declare function joinCard(a: number, b: number): number;
  * @returns {number}
  */
 export declare function sumCard(a: number, b: number): number;
+/**
+ * Project a safe diagnostic string from whatever a host hook threw:
+ * no `.message` read on a raw value, no user coercion, no
+ * proxy-observable reflection — the compiler must never fail while
+ * describing a host failure.
+ * @param {unknown} e
+ * @returns {string}
+ */
+export declare function hostFailureText(e: unknown): string;
 /**
  * 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
@@ -30,6 +46,14 @@ export declare function sumCard(a: number, b: number): number;
  * @returns {any} an independent, deeply frozen copy
  */
 export declare function deepFreezeCopy(value: any): any;
+/**
+ * Collect the frame slots an expression subtree reads (variable
+ * references and path roots) into `out`. Over-approximation is safe.
+ * @param {object} node - a frozen AST node
+ * @param {Set<number>} out - accumulator of slot indexes
+ */
+export declare function collectReadSlots(node: object, out: Set<number>): void;
+export declare function isReservedQueryName(name: any): boolean;
 /**
  * Normalize a query document into the internal AST.
  * @param {any} doc - the query document (any JSON value)