@jarenjs/json 0.9.2 → 0.34.0

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

@@ -4,8 +4,23 @@ declare const RESULT_OPT: () => number;
 declare const RESULT_MANY: () => number;
 declare const resultOfOperand: (cards: any) => any;
 declare const resultEmptyPropagates: (cards: any) => 1 | 2;
+declare const RT_BOOLEAN: () => string;
+declare const RT_NUMBER: () => string;
+declare const RT_INTEGER: () => string;
+declare const RT_STRING: () => string;
+declare const RT_MINMAX: (types: any) => "number" | "string" | null;
 declare function compileSeqOp(gets: any, args: any): any;
 declare function compileReplace(gets: any, args: any): (f: any) => string;
+/**
+ * Check one evaluated `$range` bound. Shared with the compiler's
+ * iteration fast path (compile.js), so a range that is iterated rather
+ * than materialized still rejects exactly the same bounds.
+ * @param {any} v - an evaluated bound
+ * @param {string} docPath - the bound's document pointer
+ * @returns {number} the bound
+ * @throws {JsonQueryRuntimeError} JQ2001 when it is not an integer
+ */
+export declare function checkRangeBound(v: any, docPath: string): number;
 /**
  * The complete v0.1 operator vocabulary (QUERY-FORMAT.md section 8), one
  * entry per operator: `{ params, result, compile }` (see the module
@@ -47,6 +62,7 @@ export declare const OPERATORS: Readonly<{
             min: 2;
         }>;
         result: typeof RESULT_ONE;
+        resultType: typeof RT_BOOLEAN;
         compile: (gets: any, args: any) => (f: any) => any;
     };
     $ne: {
@@ -55,6 +71,7 @@ export declare const OPERATORS: Readonly<{
             min: 2;
         }>;
         result: typeof RESULT_ONE;
+        resultType: typeof RT_BOOLEAN;
         compile: (gets: any, args: any) => (f: any) => any;
     };
     $lt: {
@@ -63,6 +80,7 @@ export declare const OPERATORS: Readonly<{
             min: 2;
         }>;
         result: typeof RESULT_ONE;
+        resultType: typeof RT_BOOLEAN;
         compile: (gets: any, args: any) => (f: any) => any;
     };
     $le: {
@@ -71,6 +89,7 @@ export declare const OPERATORS: Readonly<{
             min: 2;
         }>;
         result: typeof RESULT_ONE;
+        resultType: typeof RT_BOOLEAN;
         compile: (gets: any, args: any) => (f: any) => any;
     };
     $gt: {
@@ -79,6 +98,7 @@ export declare const OPERATORS: Readonly<{
             min: 2;
         }>;
         result: typeof RESULT_ONE;
+        resultType: typeof RT_BOOLEAN;
         compile: (gets: any, args: any) => (f: any) => any;
     };
     $ge: {
@@ -87,6 +107,7 @@ export declare const OPERATORS: Readonly<{
             min: 2;
         }>;
         result: typeof RESULT_ONE;
+        resultType: typeof RT_BOOLEAN;
         compile: (gets: any, args: any) => (f: any) => any;
     };
     $add: {
@@ -95,6 +116,7 @@ export declare const OPERATORS: Readonly<{
             min: 2;
         }>;
         result: (cards: any) => 1 | 2;
+        resultType: typeof RT_NUMBER;
         compile: (gets: any, args: any, docPath: any) => (f: any) => any;
     };
     $sub: {
@@ -103,6 +125,7 @@ export declare const OPERATORS: Readonly<{
             min: 2;
         }>;
         result: (cards: any) => 1 | 2;
+        resultType: typeof RT_NUMBER;
         compile: (gets: any, args: any, docPath: any) => (f: any) => any;
     };
     $mul: {
@@ -111,6 +134,7 @@ export declare const OPERATORS: Readonly<{
             min: 2;
         }>;
         result: (cards: any) => 1 | 2;
+        resultType: typeof RT_NUMBER;
         compile: (gets: any, args: any, docPath: any) => (f: any) => any;
     };
     $div: {
@@ -119,6 +143,7 @@ export declare const OPERATORS: Readonly<{
             min: 2;
         }>;
         result: (cards: any) => 1 | 2;
+        resultType: typeof RT_NUMBER;
         compile: (gets: any, args: any, docPath: any) => (f: any) => any;
     };
     $idiv: {
@@ -127,6 +152,7 @@ export declare const OPERATORS: Readonly<{
             min: 2;
         }>;
         result: (cards: any) => 1 | 2;
+        resultType: typeof RT_NUMBER;
         compile: (gets: any, args: any, docPath: any) => (f: any) => any;
     };
     $mod: {
@@ -135,6 +161,7 @@ export declare const OPERATORS: Readonly<{
             min: 2;
         }>;
         result: (cards: any) => 1 | 2;
+        resultType: typeof RT_NUMBER;
         compile: (gets: any, args: any, docPath: any) => (f: any) => any;
     };
     $neg: {
@@ -172,6 +199,7 @@ export declare const OPERATORS: Readonly<{
             variadic: true;
         }>;
         result: typeof RESULT_ONE;
+        resultType: typeof RT_STRING;
         compile: (gets: any, args: any) => (f: any) => string;
     };
     '$string-join': {
@@ -180,6 +208,7 @@ export declare const OPERATORS: Readonly<{
             min: 1;
         }>;
         result: typeof RESULT_ONE;
+        resultType: typeof RT_STRING;
         compile: (gets: any, args: any) => (f: any) => string;
     };
     $substring: {
@@ -188,6 +217,7 @@ export declare const OPERATORS: Readonly<{
             min: 2;
         }>;
         result: typeof RESULT_ONE;
+        resultType: typeof RT_STRING;
         compile: (gets: any, args: any) => (f: any) => string;
     };
     $contains: {
@@ -196,6 +226,7 @@ export declare const OPERATORS: Readonly<{
             min: 2;
         }>;
         result: typeof RESULT_ONE;
+        resultType: typeof RT_BOOLEAN;
         compile: (gets: any, args: any) => (f: any) => any;
     };
     '$starts-with': {
@@ -204,6 +235,7 @@ export declare const OPERATORS: Readonly<{
             min: 2;
         }>;
         result: typeof RESULT_ONE;
+        resultType: typeof RT_BOOLEAN;
         compile: (gets: any, args: any) => (f: any) => any;
     };
     '$ends-with': {
@@ -212,26 +244,31 @@ export declare const OPERATORS: Readonly<{
             min: 2;
         }>;
         result: typeof RESULT_ONE;
+        resultType: typeof RT_BOOLEAN;
         compile: (gets: any, args: any) => (f: any) => any;
     };
     $upper: {
         params: string;
         result: typeof RESULT_ONE;
+        resultType: typeof RT_STRING;
         compile: (gets: any, args: any) => (f: any) => any;
     };
     $lower: {
         params: string;
         result: typeof RESULT_ONE;
+        resultType: typeof RT_STRING;
         compile: (gets: any, args: any) => (f: any) => any;
     };
     '$string-length': {
         params: string;
         result: typeof RESULT_ONE;
+        resultType: typeof RT_STRING;
         compile: (gets: any, args: any) => (f: any) => any;
     };
     '$normalize-space': {
         params: string;
         result: typeof RESULT_ONE;
+        resultType: typeof RT_STRING;
         compile: (gets: any, args: any) => (f: any) => any;
     };
     $match: {
@@ -240,6 +277,7 @@ export declare const OPERATORS: Readonly<{
             min: 2;
         }>;
         result: typeof RESULT_ONE;
+        resultType: typeof RT_BOOLEAN;
         compile: (gets: any, args: any) => (f: any) => any;
     };
     $search: {
@@ -248,6 +286,7 @@ export declare const OPERATORS: Readonly<{
             min: 2;
         }>;
         result: typeof RESULT_ONE;
+        resultType: typeof RT_BOOLEAN;
         compile: (gets: any, args: any) => (f: any) => any;
     };
     $replace: {
@@ -256,31 +295,37 @@ export declare const OPERATORS: Readonly<{
             min: 3;
         }>;
         result: typeof RESULT_ONE;
+        resultType: typeof RT_STRING;
         compile: typeof compileReplace;
     };
     $count: {
         params: string;
         result: typeof RESULT_ONE;
+        resultType: typeof RT_INTEGER;
         compile: (gets: any) => (f: any) => number;
     };
     $sum: {
         params: string;
         result: typeof RESULT_ONE;
+        resultType: typeof RT_NUMBER;
         compile: (gets: any, args: any) => (f: any) => number;
     };
     $avg: {
         params: string;
         result: typeof resultEmptyPropagates;
+        resultType: typeof RT_NUMBER;
         compile: (gets: any, args: any) => (f: any) => number | typeof EMPTY;
     };
     $min: {
         params: string;
         result: typeof resultEmptyPropagates;
+        resultType: typeof RT_MINMAX;
         compile: (gets: any, args: any) => (f: any) => any;
     };
     $max: {
         params: string;
         result: typeof resultEmptyPropagates;
+        resultType: typeof RT_MINMAX;
         compile: (gets: any, args: any) => (f: any) => any;
     };
     $distinct: {
@@ -330,7 +375,7 @@ export declare const OPERATORS: Readonly<{
             min: 2;
         }>;
         result: typeof RESULT_MANY;
-        compile: (gets: any, args: any, docPath: any) => (f: any) => any;
+        compile: (gets: any, args: any, docPath: any, node: any) => (f: any) => any;
     };
     $get: {
         params: Readonly<{
@@ -340,6 +385,16 @@ export declare const OPERATORS: Readonly<{
         result: typeof RESULT_OPT;
         compile: (gets: any) => (f: any) => any;
     };
+    $entries: {
+        params: string;
+        result: typeof RESULT_MANY;
+        compile: (gets: any) => (f: any) => any;
+    };
+    '$from-entries': {
+        params: string;
+        result: typeof RESULT_ONE;
+        compile: (gets: any) => (f: any) => Record<string, any>;
+    };
     '$is-string': {
         params: string;
         result: typeof RESULT_ONE;
@@ -418,6 +473,191 @@ export declare const OPERATORS: Readonly<{
         result: typeof resultOfOperand;
         compile: (gets: any, args: any, docPath: any) => (f: any) => any;
     };
+    '$is-date': {
+        params: string;
+        result: typeof RESULT_ONE;
+        compile: (gets: any) => (f: any) => any;
+    };
+    '$is-time': {
+        params: string;
+        result: typeof RESULT_ONE;
+        compile: (gets: any) => (f: any) => any;
+    };
+    '$is-datetime': {
+        params: string;
+        result: typeof RESULT_ONE;
+        compile: (gets: any) => (f: any) => any;
+    };
+    '$is-duration': {
+        params: string;
+        result: typeof RESULT_ONE;
+        compile: (gets: any) => (f: any) => any;
+    };
+    $bbox: {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $area: {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $length: {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $centroid: {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $distance: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_OPT;
+        compile: (gets: any, args: any) => (f: any) => number | typeof EMPTY;
+    };
+    $within: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => boolean;
+    };
+    '$bbox-intersects': {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => boolean;
+    };
+    $geohash: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 1;
+        }>;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => string | typeof EMPTY;
+    };
+    '$date-add': {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => string | typeof EMPTY;
+    };
+    '$date-sub': {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => string | typeof EMPTY;
+    };
+    '$start-of': {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => string | typeof EMPTY;
+    };
+    '$end-of': {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => string | typeof EMPTY;
+    };
+    '$date-diff': {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 3;
+        }>;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => number | typeof EMPTY;
+    };
+    '$date-format': {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any, docPath: any) => (f: any) => any;
+    };
+    $week: {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    '$week-year': {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $quarter: {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $weekday: {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $year: {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $month: {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $day: {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $hours: {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $minutes: {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $seconds: {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $offset: {
+        params: string;
+        result: typeof RESULT_OPT;
+        compile: (gets: any, args: any) => (f: any) => number | typeof EMPTY;
+    };
+    $epoch: {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => number | typeof EMPTY;
+    };
+    $datetime: {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => string | typeof EMPTY;
+    };
 }>;
 declare function coalesceCard(cards: any): 0 | 1 | 2 | 3;
 declare function compileCoalesce(gets: any): any;

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

@@ -26,12 +26,6 @@ export declare function seqOf(items: any[]): any;
  * @param {any} v - a sequence value (EMPTY, item, or Seq)
  */
 export declare function appendItem(list: any[], v: any): void;
-/**
- * Invoke `fn(item)` for each item of a sequence value, in order.
- * @param {any} v - a sequence value (EMPTY, item, or Seq)
- * @param {(item: any) => void} fn
- */
-export declare function forEachItem(v: any, fn: (item: any) => void): void;
 /**
  * Number of items in a sequence value.
  * @param {any} v - a sequence value (EMPTY, item, or Seq)
@@ -63,8 +57,11 @@ export declare function describeItem(v: any): string;
 /**
  * Deterministic serialization of one JSON item, for `$groupby` keys
  * (QUERY-FORMAT.md section 6.5) — **engine-internal**, not an interchange
- * format (related to the roadmap's canonical-JSON item). It exists solely
- * so that deep-equal items (D2) map to the same string:
+ * format. For interchange (hashing, signing) use `canonicalizeJson`
+ * (canonical.js, RFC 8785), which is deliberately NOT this function: JCS
+ * rejects `NaN`/`Infinity` outright, where grouping needs them to be
+ * representable so that `NaN` groups with `NaN`. This exists solely so
+ * that deep-equal items (D2) map to the same string:
  *
  *   - object members serialize sorted by key (code-unit order), so key
  *     order never matters;

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

@@ -0,0 +1,34 @@
+/**
+ * @file Optional type annotation over the published normalized form
+ * (QUERY-FORMAT.md Appendix C.8). The AST carries cardinality but no
+ * value types; a consumer that owns a type source — a store's JSON
+ * Schema, a model document — supplies `typeOf(pathNode)` and gets back
+ * a NEW frozen tree mirroring the input with a `type` tag on every
+ * node. The pass never mutates its input and never runs during
+ * compilation.
+ *
+ * The lattice is small and closed: `unknown` is the top and always a
+ * safe answer; a wrong tag is a defect. Operators propagate through the
+ * registry's declared `resultType` families (comparison, arithmetic,
+ * string, aggregate); everything undeclared yields `unknown` rather
+ * than a guess.
+ */
+/** The closed set of type-tag names, sorted. */
+export declare const TYPE_TAGS: readonly string[];
+/**
+ * Annotate a normalized analysis with type tags (Appendix C.8): a NEW
+ * frozen analysis whose tree mirrors the input with `type` on every
+ * node. The input analysis and its tree are never mutated.
+ * @param {{ astVersion: number, root: any }} analysis - an
+ *   `analyzeQuery` result (or any record carrying the frozen `root`)
+ * @param {{ typeOf?: (pathNode: any) => any }} [hooks] - `typeOf`
+ *   answers for `path` nodes: a tag name, a `{ type, optional }`
+ *   object, or `null` for unknown
+ * @returns {any} the annotated analysis
+ */
+export declare function annotateTypes(analysis: {
+    astVersion: number;
+    root: any;
+}, hooks?: {
+    typeOf?: (pathNode: any) => any;
+}): any;

package/dist/types/segments.d.ts

@@ -4,6 +4,13 @@
  * `JSONPATH_NOTHING`.
  */
 export declare const NOTHING: unique symbol;
+/**
+ * Scan `source[start..end)` as an RFC 6901 array index: `0`, or a digit
+ * sequence without leading zeros. Returns -1 when the range is not a
+ * valid index (`-` is never a valid read index). Shared by the JSON
+ * Pointer compiler (pointer.js) and the JSON Patch engine (patch.js).
+ */
+export declare function scanArrayIndex(source: any, start: any, end: any): number;
 /**
  * Returns true when every segment is a child segment with exactly one
  * name or index selector (a "singular query", RFC 9535 section 2.3.5.1).
@@ -24,6 +31,13 @@ export declare function runSegmentsV(segs: any, start: any, root: any): any[];
 /**
  * Compile an existence test for a filter query; singular queries never
  * materialize nodelists.
+ *
+ * The non-singular case builds its nodelist rather than pulling the
+ * lazy chain (compileSegmentG), even though it only needs one node: a
+ * filter runs this per candidate node, where nodelists are a handful of
+ * items and generator setup costs more than the pushes it saves - it
+ * benched ~9x slower on `$.items[?@.tags[*]]` over 2000 items. Laziness
+ * pays at the top of a query, not inside a filter.
  * @returns {(current: any, root: any) => boolean}
  */
 export declare function compileExists(query: any): (current: any, root: any) => boolean;
@@ -35,6 +49,23 @@ export declare function compileLogicalExpr(expr: any): (current: any, root: any)
 export declare function compileSelectorNodeV(sel: any): (v: any, out: any, root: any) => void;
 export declare function descendV(v: any, output: any, root: any, apply: any): void;
 export declare function compileSegmentV(seg: any): (input: any, output: any, root: any) => void;
+/**
+ * Compile a segment into its lazy form: a generator function yielding
+ * the nodes one input value contributes, in document order.
+ * @param {object} seg - a parsed query segment
+ * @returns {(value: any, root: any) => Generator<any>}
+ */
+export declare function compileSegmentG(seg: object): (value: any, root: any) => Generator<any>;
+/**
+ * Lazily enumerate the nodelist a compiled segment chain selects,
+ * yielding values in document order.
+ * @param {Function[]} gens - segment generators from compileSegmentG
+ * @param {number} i - the segment to apply (0 to start the chain)
+ * @param {any} value - the value this segment applies to
+ * @param {any} root - the query root (`$` inside embedded filters)
+ * @returns {Generator<any>}
+ */
+export declare function runSegmentsG(gens: Function[], i: number, value: any, root: any): Generator<any>;
 export declare const RE_NAME_NEEDS_ESCAPE: RegExp;
 /**
  * Escape a member name for use inside a normalized path name selector