@jarenjs/json 0.9.2 → 0.34.0

package/src/segments.js

@@ -7,8 +7,8 @@
 // (value, normalized-path) pairs. This module is package-internal and is
 // deliberately not listed in the package exports.
 
-import { equalsJson } from '@jarenjs/core/object';
-import { countCodePoints, compareCodePoints } from '@jarenjs/core/string';
+import { equalsJson, compareJsonScalarLt } from '@jarenjs/core/object';
+import { countCodePoints } from '@jarenjs/core/string';
 import { compileIRegexp } from '@jarenjs/core/text/iregexp';
 import {
   CC_TAB,
@@ -17,6 +17,8 @@ import {
   CC_SPACE,
   CC_SQUOTE,
   CC_BACKSLASH,
+  CC_0,
+  isDigitCode,
 } from '@jarenjs/core/scan';
 
 /**
@@ -28,6 +30,35 @@ export const NOTHING = Symbol('JSONPath.Nothing');
 
 const hasOwn = Object.hasOwn;
 
+// Array indexes are bounded by the maximum array length (2^32 - 1), so a
+// valid index has at most 10 digits and is strictly below 2^32 - 1.
+const MAX_ARRAY_INDEX = 4294967294;
+
+/**
+ * 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 function scanArrayIndex(source, start, end) {
+  const digits = end - start;
+  if (digits === 0 || digits > 10)
+    return -1;
+  const first = source.charCodeAt(start);
+  if (!isDigitCode(first))
+    return -1;
+  if (first === CC_0)
+    return digits === 1 ? 0 : -1;
+  let index = first - CC_0;
+  for (let i = start + 1; i < end; i++) {
+    const c = source.charCodeAt(i);
+    if (!isDigitCode(c))
+      return -1;
+    index = index * 10 + (c - CC_0);
+  }
+  return index <= MAX_ARRAY_INDEX ? index : -1;
+}
+
 /**
  * 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).
@@ -56,16 +87,6 @@ function cmpEquals(a, b) {
   return equalsJson(a, b);
 }
 
-// numbers by value, strings by Unicode scalar values (RFC 9535
-// section 2.3.5.2.2); other types do not order
-function cmpLess(a, b) {
-  if (typeof a === 'number')
-    return typeof b === 'number' && a < b;
-  if (typeof a === 'string')
-    return typeof b === 'string' && compareCodePoints(a, b) < 0;
-  return false;
-}
-
 function countOwnKeys(obj) {
   let count = 0;
   for (const key in obj) {
@@ -129,6 +150,13 @@ export function runSegmentsV(segs, start, root) {
 /**
  * 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 function compileExists(query) {
@@ -141,17 +169,86 @@ export function compileExists(query) {
   return (current, root) => runSegmentsV(segs, relative ? current : root, root).length > 0;
 }
 
+// Collector for the reset hooks of `$`-rooted comparable memos, active
+// while compileFilterPredicate compiles a filter's predicate tree; null
+// outside a filter, where a memo would have no reset and go stale.
+let pendingResets = null;
+
+// Hand-back from compileFilterPredicate to the filter selector that ran
+// it - module scope like sliceFrom/sliceTo: read immediately, never kept.
+let filterReset = null;
+
+/**
+ * Compile a filter's predicate expression, collecting the reset hooks of
+ * the `$`-rooted comparable memos inside it (see compileComparable) and
+ * handing their combined reset - or null when the tree has none - back
+ * through `filterReset`. The filter selector runs the reset before each
+ * application. A nested filter collects into its own frame, so an inner
+ * filter's memos reset per inner application.
+ * @returns {(current: any, root: any) => boolean}
+ */
+function compileFilterPredicate(expr) {
+  const saved = pendingResets;
+  pendingResets = [];
+  const pred = compileLogicalExpr(expr);
+  const resets = pendingResets;
+  pendingResets = saved;
+  if (resets.length === 0) {
+    filterReset = null;
+  }
+  else if (resets.length === 1) {
+    filterReset = resets[0];
+  }
+  else {
+    filterReset = () => {
+      for (let i = 0; i < resets.length; i++)
+        resets[i]();
+    };
+  }
+  return pred;
+}
+
 // getter producing a ValueType result (a JSON value or NOTHING)
 function compileComparable(node) {
   if (node.kind === 'literal') {
     const value = node.value;
     return () => value;
   }
-  if (node.kind === 'query')
-    return compileSingularGetter(node.query.segments, node.query.relative);
+  if (node.kind === 'query') {
+    const getter = compileSingularGetter(node.query.segments, node.query.relative);
+    if (node.query.relative || pendingResets === null)
+      return getter;
+    // A `$`-rooted comparable is invariant for one filter application,
+    // so it is computed at the first candidate and reused for the rest
+    // instead of re-walking from the root per candidate. The filter
+    // resets the memo before each application (a caller may mutate the
+    // document and re-run the query on the same root identity); the
+    // root check covers a reentrant run against a different document.
+    let cachedRoot = NOTHING;
+    let cachedValue = NOTHING;
+    pendingResets.push(() => { cachedRoot = NOTHING; });
+    return (current, root) => {
+      if (root !== cachedRoot) {
+        cachedValue = getter(current, root);
+        cachedRoot = root;
+      }
+      return cachedValue;
+    };
+  }
   return compileValueFunction(node);
 }
 
+// getter producing a NodesType result (an array of the selected values).
+// The argument is a filter query or a nodes-returning extension.
+function compileNodesGetter(arg) {
+  if (arg.kind !== 'query')
+    return compileUserFunction(arg);
+  const query = arg.query;
+  const segs = query.segments.map(compileSegmentV);
+  const relative = query.relative;
+  return (current, root) => runSegmentsV(segs, relative ? current : root, root);
+}
+
 function compileValueFunction(func) {
   switch (func.name) {
     case 'length': {
@@ -168,32 +265,97 @@ function compileValueFunction(func) {
       };
     }
     case 'count': {
-      const query = func.args[0].query;
-      if (isSingularSegments(query.segments)) {
-        const getter = compileSingularGetter(query.segments, query.relative);
+      const arg = func.args[0];
+      if (arg.kind === 'query' && isSingularSegments(arg.query.segments)) {
+        const getter = compileSingularGetter(arg.query.segments, arg.query.relative);
         return (current, root) => (getter(current, root) === NOTHING ? 0 : 1);
       }
-      const segs = query.segments.map(compileSegmentV);
-      const relative = query.relative;
-      return (current, root) => runSegmentsV(segs, relative ? current : root, root).length;
+      const get = compileNodesGetter(arg);
+      return (current, root) => get(current, root).length;
     }
     case 'value': {
-      const query = func.args[0].query;
-      if (isSingularSegments(query.segments))
-        return compileSingularGetter(query.segments, query.relative);
-      const segs = query.segments.map(compileSegmentV);
-      const relative = query.relative;
+      const arg = func.args[0];
+      if (arg.kind === 'query' && isSingularSegments(arg.query.segments))
+        return compileSingularGetter(arg.query.segments, arg.query.relative);
+      // eager for the same reason as compileExists: this runs per
+      // candidate node inside a filter
+      const get = compileNodesGetter(arg);
       return (current, root) => {
-        const result = runSegmentsV(segs, relative ? current : root, root);
+        const result = get(current, root);
         return result.length === 1 ? result[0] : NOTHING;
       };
     }
-    /* c8 ignore next 2 -- guarded by the parser's well-typedness checks */
     default:
-      throw new Error(`JSONPath: function '${func.name}' does not return ValueType`);
+      return compileUserFunction(func);
   }
 }
 
+// Compile a registered function extension (RFC 9535 section 2.4).
+// Arguments are marshalled to their declared types - ValueType is a
+// JSON value or NOTHING, NodesType an array of values, LogicalType a
+// boolean - and the result is checked against the declared return type,
+// because a registry entry that lies about its type would otherwise
+// corrupt the comparison rules further up.
+function compileUserFunction(func) {
+  /* c8 ignore next 2 -- guarded by the parser's well-typedness checks */
+  if (typeof func.evaluate !== 'function')
+    throw new Error(`JSONPath: function '${func.name}' has no implementation`);
+  const evaluate = func.evaluate;
+  const name = func.name;
+  const params = func.params;
+  const gets = new Array(func.args.length);
+  for (let i = 0; i < gets.length; i++) {
+    const arg = func.args[i];
+    gets[i] = params[i] === 'value'
+      ? compileComparable(arg)
+      : params[i] === 'nodes'
+        ? compileNodesGetter(arg)
+        : compileLogicalExpr(arg.expr);
+  }
+
+  let call;
+  switch (gets.length) {
+    case 0:
+      call = () => evaluate();
+      break;
+    case 1: {
+      const a = gets[0];
+      call = (c, r) => evaluate(a(c, r));
+      break;
+    }
+    case 2: {
+      const a = gets[0];
+      const b = gets[1];
+      call = (c, r) => evaluate(a(c, r), b(c, r));
+      break;
+    }
+    default:
+      call = (c, r) => {
+        const argv = new Array(gets.length);
+        for (let i = 0; i < gets.length; i++)
+          argv[i] = gets[i](c, r);
+        return evaluate(...argv);
+      };
+  }
+
+  if (func.returns === 'logical')
+    return (c, r) => call(c, r) === true;
+  if (func.returns === 'value') {
+    // a function may legitimately return Nothing; `undefined` is not a
+    // JSON value, so it is the natural spelling of it
+    return (c, r) => {
+      const v = call(c, r);
+      return v === undefined ? NOTHING : v;
+    };
+  }
+  return (c, r) => {
+    const v = call(c, r);
+    if (!Array.isArray(v))
+      throw new TypeError(`JSONPath: function '${name}' must return an array of nodes (NodesType)`);
+    return v;
+  };
+}
+
 function compileRegexTest(func, fullMatch) {
   const inputGet = compileComparable(func.args[0]);
   const patternArg = func.args[1];
@@ -236,20 +398,20 @@ function compileComparison(expr) {
     case '!=':
       return (c, r) => !cmpEquals(left(c, r), right(c, r));
     case '<':
-      return (c, r) => cmpLess(left(c, r), right(c, r));
+      return (c, r) => compareJsonScalarLt(left(c, r), right(c, r));
     case '>':
-      return (c, r) => cmpLess(right(c, r), left(c, r));
+      return (c, r) => compareJsonScalarLt(right(c, r), left(c, r));
     case '<=':
       return (c, r) => {
         const a = left(c, r);
         const b = right(c, r);
-        return cmpLess(a, b) || cmpEquals(a, b);
+        return compareJsonScalarLt(a, b) || cmpEquals(a, b);
       };
     default: // '>='
       return (c, r) => {
         const a = left(c, r);
         const b = right(c, r);
-        return cmpLess(b, a) || cmpEquals(a, b);
+        return compareJsonScalarLt(b, a) || cmpEquals(a, b);
       };
   }
 }
@@ -288,8 +450,17 @@ export function compileLogicalExpr(expr) {
     }
     case 'exists':
       return compileExists(expr.query);
-    case 'ftest':
-      return compileRegexTest(expr.func, expr.func.name === 'match');
+    case 'ftest': {
+      const func = expr.func;
+      if (func.name === 'match' || func.name === 'search')
+        return compileRegexTest(func, func.name === 'match');
+      // a registered extension as a test expression: LogicalType is the
+      // answer itself, NodesType is true for a non-empty nodelist
+      const fn = compileUserFunction(func);
+      if (func.returns === 'logical')
+        return fn;
+      return (c, r) => fn(c, r).length > 0;
+    }
     default: // 'cmp'
       return compileComparison(expr);
   }
@@ -299,6 +470,29 @@ export function compileLogicalExpr(expr) {
 
 //#region segment compilation (values mode)
 
+// Resolve a slice selector's bounds against an array length (RFC 9535
+// section 2.3.4.2.2) for a `for (i = sliceFrom; i != sliceTo; i += step)`
+// walk - exclusive at `sliceTo` in both directions. The two results are
+// handed back through module scope rather than an object or a pair,
+// because this runs once per input node on every slice selector in all
+// three segment modes and must not allocate. Read them immediately; no
+// slice applier calls anything in between.
+let sliceFrom = 0;
+let sliceTo = 0;
+
+function sliceBounds(start, end, step, len) {
+  const s = start === null ? (step > 0 ? 0 : len - 1) : (start < 0 ? len + start : start);
+  const e = end === null ? (step > 0 ? len : -1) : (end < 0 ? len + end : end);
+  if (step > 0) {
+    sliceFrom = s < 0 ? 0 : (s > len ? len : s);
+    sliceTo = e < 0 ? 0 : (e > len ? len : e);
+  }
+  else {
+    sliceFrom = s < -1 ? -1 : (s > len - 1 ? len - 1 : s);
+    sliceTo = e < -1 ? -1 : (e > len - 1 ? len - 1 : e);
+  }
+}
+
 // selector-node functions: (value, output, root) => void
 
 export function compileSelectorNodeV(sel) {
@@ -351,26 +545,23 @@ export function compileSelectorNodeV(sel) {
         const len = v.length;
         if (len === 0)
           return;
-        // bounds per RFC 9535 section 2.3.4.2.2
-        const s = start === null ? (step > 0 ? 0 : len - 1) : (start < 0 ? len + start : start);
-        const e = end === null ? (step > 0 ? len : -1) : (end < 0 ? len + end : end);
+        sliceBounds(start, end, step, len);
         if (step > 0) {
-          const lower = s < 0 ? 0 : (s > len ? len : s);
-          const upper = e < 0 ? 0 : (e > len ? len : e);
-          for (let i = lower; i < upper; i += step)
+          for (let i = sliceFrom; i < sliceTo; i += step)
             out.push(v[i]);
         }
         else {
-          const upper = s < -1 ? -1 : (s > len - 1 ? len - 1 : s);
-          const lower = e < -1 ? -1 : (e > len - 1 ? len - 1 : e);
-          for (let i = upper; i > lower; i += step)
+          for (let i = sliceFrom; i > sliceTo; i += step)
             out.push(v[i]);
         }
       };
     }
     default: { // 'filter'
-      const pred = compileLogicalExpr(sel.expr);
+      const pred = compileFilterPredicate(sel.expr);
+      const reset = filterReset;
       return (v, out, root) => {
+        if (reset !== null)
+          reset();
         if (Array.isArray(v)) {
           for (let i = 0; i < v.length; i++) {
             if (pred(v[i], root))
@@ -402,15 +593,21 @@ export function descendV(v, output, root, apply) {
   }
 }
 
+// Combine a segment's selectors into one (value, output, root) => void
+// applier; a single selector is its own applier.
+function compileSelectorsV(seg) {
+  const fns = seg.selectors.map(compileSelectorNodeV);
+  if (fns.length === 1)
+    return fns[0];
+  return (v, out, root) => {
+    for (let i = 0; i < fns.length; i++)
+      fns[i](v, out, root);
+  };
+}
+
 // segment functions: (input, output, root) => void
 export function compileSegmentV(seg) {
-  const fns = seg.selectors.map(compileSelectorNodeV);
-  const apply = fns.length === 1
-    ? fns[0]
-    : (v, out, root) => {
-      for (let i = 0; i < fns.length; i++)
-        fns[i](v, out, root);
-    };
+  const apply = compileSelectorsV(seg);
   if (seg.descendant) {
     return (input, output, root) => {
       for (let i = 0; i < input.length; i++)
@@ -425,11 +622,161 @@ export function compileSegmentV(seg) {
 
 //#endregion
 
+//#region segment compilation (lazy values mode)
+// The same selectors as values mode, pulled one node at a time instead
+// of pushed into a nodelist. A consumer that stops early (`first`,
+// `exists`, `value()`'s two-node test) never visits the rest of the
+// document: a filter evaluates its predicate only until a node passes,
+// a wildcard reads only the children actually pulled, and a descendant
+// segment abandons the walk mid-subtree.
+//
+// Nothing here is buffered - every applier yields directly - so the
+// laziness is per node, not per segment. Enumeration order is identical
+// to runSegmentsV: a segment maps each input node to its outputs in
+// order and concatenates them, so pulling the chain depth-first visits
+// exactly the sequence values mode builds breadth-first.
+
+// selector-node functions: (value, root) => Generator<any>
+
+function compileSelectorNodeG(sel) {
+  switch (sel.kind) {
+    case 'name': {
+      const name = sel.name;
+      return function* nameG(v) {
+        if (typeof v === 'object' && v !== null && !Array.isArray(v) && hasOwn(v, name))
+          yield v[name];
+      };
+    }
+    case 'index': {
+      const index = sel.index;
+      return function* indexG(v) {
+        if (!Array.isArray(v))
+          return;
+        const idx = index < 0 ? v.length + index : index;
+        if (idx >= 0 && idx < v.length)
+          yield v[idx];
+      };
+    }
+    case 'wildcard':
+      return function* wildcardG(v) {
+        if (Array.isArray(v)) {
+          yield* v;
+        }
+        else if (typeof v === 'object' && v !== null) {
+          for (const key in v) {
+            if (hasOwn(v, key))
+              yield v[key];
+          }
+        }
+      };
+    case 'slice': {
+      const start = sel.start;
+      const end = sel.end;
+      const step = sel.step === null ? 1 : sel.step;
+      if (step === 0)
+        return function* emptySliceG() { };
+      return function* sliceG(v) {
+        if (!Array.isArray(v))
+          return;
+        const len = v.length;
+        if (len === 0)
+          return;
+        sliceBounds(start, end, step, len);
+        // read the bounds out before the first yield: a suspended
+        // generator must not depend on the shared scratch surviving
+        const from = sliceFrom;
+        const to = sliceTo;
+        if (step > 0) {
+          for (let i = from; i < to; i += step)
+            yield v[i];
+        }
+        else {
+          for (let i = from; i > to; i += step)
+            yield v[i];
+        }
+      };
+    }
+    default: { // 'filter'
+      const pred = compileFilterPredicate(sel.expr);
+      const reset = filterReset;
+      return function* filterG(v, root) {
+        if (reset !== null)
+          reset();
+        if (Array.isArray(v)) {
+          for (let i = 0; i < v.length; i++) {
+            if (pred(v[i], root))
+              yield v[i];
+          }
+        }
+        else if (typeof v === 'object' && v !== null) {
+          for (const key in v) {
+            if (hasOwn(v, key) && pred(v[key], root))
+              yield v[key];
+          }
+        }
+      };
+    }
+  }
+}
+
+function* descendG(v, root, apply) {
+  yield* apply(v, root);
+  if (Array.isArray(v)) {
+    for (let i = 0; i < v.length; i++)
+      yield* descendG(v[i], root, apply);
+  }
+  else if (typeof v === 'object' && v !== null) {
+    for (const key in v) {
+      if (hasOwn(v, key))
+        yield* descendG(v[key], root, apply);
+    }
+  }
+}
+
+/**
+ * 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 function compileSegmentG(seg) {
+  const fns = seg.selectors.map(compileSelectorNodeG);
+  const apply = fns.length === 1
+    ? fns[0]
+    : function* applyG(v, root) {
+      for (let i = 0; i < fns.length; i++)
+        yield* fns[i](v, root);
+    };
+  if (seg.descendant)
+    return function* segmentDescendantG(v, root) { yield* descendG(v, root, apply); };
+  return apply;
+}
+
+/**
+ * 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 function* runSegmentsG(gens, i, value, root) {
+  if (i === gens.length) {
+    yield value;
+    return;
+  }
+  for (const v of gens[i](value, root))
+    yield* runSegmentsG(gens, i + 1, v, root);
+}
+
+//#endregion
+
 //#region segment compilation (nodes mode, normalized paths)
-// Moved verbatim from path.js: the selector/segment compilers producing
-// (value, normalized-path) pairs per RFC 9535 section 2.7. path.js
-// imports them back for `query.nodes()`/`query.paths()`; nodes mode
-// stays lazily compiled there, so value-only queries never pay for it.
+// The selector/segment compilers producing (value, normalized-path)
+// pairs per RFC 9535 section 2.7. path.js imports them for
+// `query.nodes()`/`query.paths()`; nodes mode stays lazily compiled
+// there, so value-only queries never pay for it.
 
 // eslint-disable-next-line no-control-regex
 export const RE_NAME_NEEDS_ESCAPE = /['\\\u0000-\u001f]/;
@@ -516,20 +863,15 @@ export function compileSelectorNodeP(sel) {
         const len = v.length;
         if (len === 0)
           return;
-        const s = start === null ? (step > 0 ? 0 : len - 1) : (start < 0 ? len + start : start);
-        const e = end === null ? (step > 0 ? len : -1) : (end < 0 ? len + end : end);
+        sliceBounds(start, end, step, len);
         if (step > 0) {
-          const lower = s < 0 ? 0 : (s > len ? len : s);
-          const upper = e < 0 ? 0 : (e > len ? len : e);
-          for (let i = lower; i < upper; i += step) {
+          for (let i = sliceFrom; i < sliceTo; i += step) {
             outV.push(v[i]);
             outP.push(p + '[' + i + ']');
           }
         }
         else {
-          const upper = s < -1 ? -1 : (s > len - 1 ? len - 1 : s);
-          const lower = e < -1 ? -1 : (e > len - 1 ? len - 1 : e);
-          for (let i = upper; i > lower; i += step) {
+          for (let i = sliceFrom; i > sliceTo; i += step) {
             outV.push(v[i]);
             outP.push(p + '[' + i + ']');
           }
@@ -537,8 +879,11 @@ export function compileSelectorNodeP(sel) {
       };
     }
     default: { // 'filter'
-      const pred = compileLogicalExpr(sel.expr);
+      const pred = compileFilterPredicate(sel.expr);
+      const reset = filterReset;
       return (v, p, outV, outP, root) => {
+        if (reset !== null)
+          reset();
         if (Array.isArray(v)) {
           for (let i = 0; i < v.length; i++) {
             if (pred(v[i], root)) {