@jarenjs/json 0.9.2

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

@@ -0,0 +1,424 @@
+import { EMPTY } from './runtime.js';
+declare const RESULT_ONE: () => number;
+declare const RESULT_OPT: () => number;
+declare const RESULT_MANY: () => number;
+declare const resultOfOperand: (cards: any) => any;
+declare const resultEmptyPropagates: (cards: any) => 1 | 2;
+declare function compileSeqOp(gets: any, args: any): any;
+declare function compileReplace(gets: any, args: any): (f: any) => string;
+/**
+ * The complete v0.1 operator vocabulary (QUERY-FORMAT.md section 8), one
+ * entry per operator: `{ params, result, compile }` (see the module
+ * comment for the descriptor contract). Frozen; the closed vocabulary is
+ * exactly the keys of this table plus the phrase keys and escape hatches
+ * handled by normalize.js.
+ */
+export declare const OPERATORS: Readonly<{
+    $seq: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 0;
+            variadic: true;
+        }>;
+        result: (cards: any) => number;
+        compile: typeof compileSeqOp;
+    };
+    $exists: {
+        params: string;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (frame: any[]) => boolean;
+    };
+    $empty: {
+        params: string;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => boolean;
+    };
+    $if: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: (cards: any) => number;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $eq: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $ne: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $lt: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $le: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $gt: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $ge: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $add: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: (cards: any) => 1 | 2;
+        compile: (gets: any, args: any, docPath: any) => (f: any) => any;
+    };
+    $sub: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: (cards: any) => 1 | 2;
+        compile: (gets: any, args: any, docPath: any) => (f: any) => any;
+    };
+    $mul: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: (cards: any) => 1 | 2;
+        compile: (gets: any, args: any, docPath: any) => (f: any) => any;
+    };
+    $div: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: (cards: any) => 1 | 2;
+        compile: (gets: any, args: any, docPath: any) => (f: any) => any;
+    };
+    $idiv: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: (cards: any) => 1 | 2;
+        compile: (gets: any, args: any, docPath: any) => (f: any) => any;
+    };
+    $mod: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: (cards: any) => 1 | 2;
+        compile: (gets: any, args: any, docPath: any) => (f: any) => any;
+    };
+    $neg: {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => number | typeof EMPTY;
+    };
+    $and: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 1;
+            variadic: true;
+        }>;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $or: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 1;
+            variadic: true;
+        }>;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $not: {
+        params: string;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => boolean;
+    };
+    $concat: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 0;
+            variadic: true;
+        }>;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => string;
+    };
+    '$string-join': {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 1;
+        }>;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => string;
+    };
+    $substring: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => string;
+    };
+    $contains: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    '$starts-with': {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    '$ends-with': {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $upper: {
+        params: string;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $lower: {
+        params: string;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    '$string-length': {
+        params: string;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    '$normalize-space': {
+        params: string;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $match: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $search: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $replace: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 3;
+        }>;
+        result: typeof RESULT_ONE;
+        compile: typeof compileReplace;
+    };
+    $count: {
+        params: string;
+        result: typeof RESULT_ONE;
+        compile: (gets: any) => (f: any) => number;
+    };
+    $sum: {
+        params: string;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => number;
+    };
+    $avg: {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => number | typeof EMPTY;
+    };
+    $min: {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $max: {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $distinct: {
+        params: string;
+        result: typeof resultOfOperand;
+        compile: (gets: any) => (f: any) => any;
+    };
+    $reverse: {
+        params: string;
+        result: typeof resultOfOperand;
+        compile: (gets: any) => (f: any) => any;
+    };
+    $sort: {
+        params: string;
+        result: typeof resultOfOperand;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $head: {
+        params: string;
+        result: (cards: any) => any;
+        compile: (gets: any) => (f: any) => any;
+    };
+    $tail: {
+        params: string;
+        result: (cards: any) => 0 | 3;
+        compile: (gets: any) => (f: any) => any;
+    };
+    $subsequence: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: (cards: any) => 0 | 2 | 3;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    '$index-of': {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: (cards: any) => 0 | 2 | 3;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $range: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_MANY;
+        compile: (gets: any, args: any, docPath: any) => (f: any) => any;
+    };
+    $get: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_OPT;
+        compile: (gets: any) => (f: any) => any;
+    };
+    '$is-string': {
+        params: string;
+        result: typeof RESULT_ONE;
+        compile: (gets: any) => (f: any) => any;
+    };
+    '$is-number': {
+        params: string;
+        result: typeof RESULT_ONE;
+        compile: (gets: any) => (f: any) => any;
+    };
+    '$is-boolean': {
+        params: string;
+        result: typeof RESULT_ONE;
+        compile: (gets: any) => (f: any) => any;
+    };
+    '$is-null': {
+        params: string;
+        result: typeof RESULT_ONE;
+        compile: (gets: any) => (f: any) => any;
+    };
+    '$is-array': {
+        params: string;
+        result: typeof RESULT_ONE;
+        compile: (gets: any) => (f: any) => any;
+    };
+    '$is-object': {
+        params: string;
+        result: typeof RESULT_ONE;
+        compile: (gets: any) => (f: any) => any;
+    };
+    $string: {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => string | typeof EMPTY;
+    };
+    $number: {
+        params: string;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => number | typeof EMPTY;
+    };
+    $boolean: {
+        params: string;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => boolean;
+    };
+    $coalesce: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 1;
+            variadic: true;
+        }>;
+        result: typeof coalesceCard;
+        compile: typeof compileCoalesce;
+    };
+    $default: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof coalesceCard;
+        compile: typeof compileCoalesce;
+    };
+    $valid: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_ONE;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    $assert: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof resultOfOperand;
+        compile: (gets: any, args: any, docPath: any) => (f: any) => any;
+    };
+}>;
+declare function coalesceCard(cards: any): 0 | 1 | 2 | 3;
+declare function compileCoalesce(gets: any): any;
+export {};

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

@@ -0,0 +1,93 @@
+/**
+ * The empty sequence `()` (same singleton-sentinel pattern as
+ * `JSONPATH_NOTHING`).
+ */
+export declare const EMPTY: unique symbol;
+/**
+ * A sequence of two or more items. Never constructed directly by
+ * operator code - use `seqOf` so the flatness invariant holds.
+ */
+export declare class Seq {
+    items: any;
+    constructor(items: any);
+}
+/**
+ * Build a sequence value from a flat accumulator array of items.
+ * Returns EMPTY for zero items, the raw item for one, a Seq otherwise.
+ * The array is adopted, not copied; callers hand over ownership.
+ * @param {any[]} items - flat array of items (no Seq, no EMPTY inside)
+ * @returns {any} EMPTY, a single item, or a Seq
+ */
+export declare function seqOf(items: any[]): any;
+/**
+ * Append a sequence value's items to a plain accumulator array
+ * (the shared flattening step of array constructors and `$seq`).
+ * @param {any[]} list - accumulator array of items
+ * @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)
+ * @returns {number}
+ */
+export declare function itemCount(v: any): number;
+/**
+ * First item of a sequence value, or EMPTY for the empty sequence.
+ * @param {any} v - a sequence value (EMPTY, item, or Seq)
+ * @returns {any}
+ */
+export declare function firstItem(v: any): any;
+/**
+ * Effective boolean value of a sequence value per the EBV table of
+ * QUERY-FORMAT.md section 2.2 (D3: singleton array/object is true).
+ * @param {any} v - a sequence value (EMPTY, item, or Seq)
+ * @param {string} docPath - RFC 6901 pointer for the JQ2003 error
+ * @returns {boolean}
+ * @throws {JsonQueryRuntimeError} JQ2003 on a sequence of two or more items
+ */
+export declare function ebv(v: any, docPath: string): boolean;
+/**
+ * Describe a sequence value for a runtime error message (non-normative,
+ * human-readable).
+ * @param {any} v - a sequence value (EMPTY, item, or Seq)
+ * @returns {string}
+ */
+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:
+ *
+ *   - object members serialize sorted by key (code-unit order), so key
+ *     order never matters;
+ *   - `-0` normalizes to `0` (D2: `-0` equals `0`);
+ *   - strings serialize via `JSON.stringify` (its escape discipline means
+ *     no raw control character ever appears in the output, so a control
+ *     character is safe as a composite-key separator);
+ *   - numbers serialize bare via `String(n)` — `NaN` and `±Infinity`
+ *     (reachable through `$div`) serialize as `NaN`/`Infinity`, which
+ *     cannot collide with quoted strings. Note this makes `NaN` group
+ *     with `NaN`, the XQuery grouping rule, even though `NaN` never
+ *     equals itself under `$eq`.
+ *
+ * @param {any} value - a JSON item (not EMPTY, not a Seq)
+ * @returns {string} a deterministic serialization for grouping
+ */
+export declare function stableKeyString(value: any): string;
+/**
+ * Debug-only invariant check: asserts a sequence value is well-formed
+ * (a Seq holds 2+ items and contains no nested Seq or EMPTY). Used by
+ * tests; never called on hot paths.
+ * @param {any} v - a sequence value to check
+ * @returns {any} v itself when well-formed
+ * @throws {Error} when the flatness invariant is violated
+ */
+export declare function assertSeqInvariant(v: any): any;

package/dist/types/segments.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Sentinel for the absence of a value ("Nothing" in RFC 9535 terms), as
+ * distinct from the JSON value `null`. Re-exported from path.js as
+ * `JSONPATH_NOTHING`.
+ */
+export declare const NOTHING: unique symbol;
+/**
+ * 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).
+ * @param {object[]} segments - Parsed query segments
+ * @returns {boolean}
+ */
+export declare function isSingularSegments(segments: object[]): boolean;
+/**
+ * Compile a singular query into a direct property walk.
+ * @returns {(current: any, root: any) => any} getter returning the value or NOTHING
+ */
+export declare function compileSingularGetter(segments: any, relative: any): (current: any, root: any) => any;
+/**
+ * Run a chain of compiled value-mode segment functions over a start value.
+ * @returns {any[]} the resulting nodelist as an array of values
+ */
+export declare function runSegmentsV(segs: any, start: any, root: any): any[];
+/**
+ * Compile an existence test for a filter query; singular queries never
+ * materialize nodelists.
+ * @returns {(current: any, root: any) => boolean}
+ */
+export declare function compileExists(query: any): (current: any, root: any) => boolean;
+/**
+ * Compile a filter logical expression to a predicate.
+ * @returns {(current: any, root: any) => boolean}
+ */
+export declare function compileLogicalExpr(expr: any): (current: any, root: any) => boolean;
+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;
+export declare const RE_NAME_NEEDS_ESCAPE: RegExp;
+/**
+ * Escape a member name for use inside a normalized path name selector
+ * (RFC 9535 section 2.7).
+ */
+export declare function escapeNormalizedName(name: any): any;
+export declare function appendName(path: any, name: any): string;
+export declare function compileSelectorNodeP(sel: any): (v: any, p: any, outV: any, outP: any, root: any) => void;
+export declare function descendP(v: any, p: any, outV: any, outP: any, root: any, apply: any): void;
+export declare function compileSegmentP(seg: any): (inV: any, inP: any, outV: any, outP: any, root: any) => void;
+/**
+ * Run a chain of compiled nodes-mode segment functions over a start
+ * value, threading normalized paths alongside values.
+ * @param {Function[]} segs - segment functions from compileSegmentP
+ * @param {any} startValue - the value the first segment applies to
+ * @param {string} startPath - the base normalized path of startValue
+ *   (`'$'` for the document root)
+ * @param {any} root - the query root (`$` inside embedded filters)
+ * @returns {{ vals: any[], paths: string[] }} parallel arrays of the
+ *   resulting nodelist's values and normalized paths
+ */
+export declare function runSegmentsP(segs: Function[], startValue: any, startPath: string, root: any): {
+    vals: any[];
+    paths: string[];
+};

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

@@ -0,0 +1,19 @@
+export { parseXQuery, XQuerySyntaxError } from './parse.js';
+/**
+ * Parse XQuery text and compile the resulting query document in one call.
+ * Returns the engine's compiled query function (see `compileJsonQuery`):
+ * `query(data, externals?)` plus the `first`/`exists`/`externals`/`doc`
+ * helpers - `doc` holds the emitted query document.
+ * @param {string} text - XQuery text in the supported subset
+ * @param {object} [options] - passed through to `compileJsonQuery`
+ * @returns {function} the compiled query function
+ * @throws {XQuerySyntaxError} when the text is invalid or outside the subset
+ * @throws {import('../query/errors.js').JsonQueryCompileError} when the
+ *   emitted document is rejected by the compiler (e.g. duplicate variable
+ *   bindings, JQ0007)
+ * @example
+ * const q = compileXQuery('for $b in $doc?store?book?* where $b?price lt 10 return $b?title');
+ * q.externals; // ['doc']
+ * q(null, { doc: data }); // ['Sayings of the Century', 'Moby Dick']
+ */
+export declare function compileXQuery(text: string, options?: object): Function;

package/dist/types/xquery/parse.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Error thrown when XQuery text is not valid for the supported subset -
+ * either invalid XQuery 3.1 syntax or a recognized construct outside the
+ * subset (mirrors JSONPathSyntaxError: `source` and `position` locate the
+ * offending token).
+ */
+export declare class XQuerySyntaxError extends SyntaxError {
+    source: any;
+    position: any;
+    constructor(message: any, source: any, position: any);
+}
+/**
+ * Parse XQuery 3.1 text (the supported subset, see XQUERY-FRONTEND.md)
+ * into a Jaren JSON Query document.
+ * @param {string} source - the XQuery text (e.g. `for $b in $doc?store?book?* return $b?title`)
+ * @returns {any} a valid query document for `compileJsonQuery` (envelope omitted)
+ * @throws {XQuerySyntaxError} when the text is invalid or uses a construct
+ *   outside the subset (named `unsupported ...` messages)
+ */
+export declare function parseXQuery(source: string): any;