@jarenjs/json 0.9.2 → 0.34.2

package/src/path.js

@@ -16,7 +16,10 @@
 //   - Singular queries (`$.a.b[3]`) compile to a direct property walk with
 //     no intermediate arrays.
 //   - Filter comparables compile to sentinel-returning getters; existence
-//     tests on singular queries never materialize nodelists.
+//     tests on singular queries never materialize nodelists. A `$`-rooted
+//     comparable is memoized per filter application (its value is invariant
+//     across the candidates), with the memo reset before each application so
+//     a mutated document re-queried under the same root reads fresh.
 //   - `match()`/`search()` with a literal pattern precompile their RegExp;
 //     dynamic patterns use a per-callsite monomorphic cache.
 //   - Normalized-path production (RFC 9535 section 2.7) is compiled lazily,
@@ -30,9 +33,17 @@ import {
   compileSingularGetter,
   compileSegmentV,
   runSegmentsV,
+  compileSegmentG,
+  runSegmentsG,
   compileSegmentP,
   runSegmentsP,
+  scanArrayIndex,
+  appendName,
 } from './segments.js';
+import {
+  parseJSONPointer,
+  encodeJSONPointerSegment,
+} from './pointer.js';
 import {
   CC_TAB,
   CC_LF,
@@ -64,7 +75,12 @@ import {
   CC_UNDERSCORE,
   CC_PIPE,
   isDigitCode,
+  isNameStartCode,
+  isNameCharCode,
 } from '@jarenjs/core/scan';
+import { deepFreeze } from '@jarenjs/core/object';
+import { createBoundedCache, createWeakCache } from '@jarenjs/core/cache';
+import { LabeledSyntaxError } from './errors.js';
 
 /**
  * Sentinel for the absence of a value ("Nothing" in RFC 9535 terms), as
@@ -72,32 +88,23 @@ import {
  */
 export const JSONPATH_NOTHING = NOTHING;
 
-function deepFreeze(value) {
-  if (typeof value !== 'object' || value === null)
-    return value;
-  const keys = Object.keys(value);
-  for (let i = 0; i < keys.length; i++)
-    deepFreeze(value[keys[i]]);
-  return Object.freeze(value);
-}
-
 /**
  * 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 class JSONPathSyntaxError extends SyntaxError {
+export class JSONPathSyntaxError extends LabeledSyntaxError {
   constructor(message, source, position) {
-    super(`Invalid JSONPath: ${message} at position ${position} in '${source}'`);
-    this.name = 'JSONPathSyntaxError';
-    this.source = source;
-    this.position = position;
+    super('JSONPathSyntaxError', 'JSONPath', message, source, position);
   }
 }
 
 // Built-in function extensions (RFC 9535 section 2.4).
 // Parameter/return types: 'value' = ValueType, 'nodes' = NodesType,
-// 'logical' = LogicalType.
+// 'logical' = LogicalType. Null-prototype, so an inherited member name
+// (`constructor`, `tostring`) is an unknown function and not a
+// half-formed descriptor.
 const FUNCTIONS = {
+  __proto__: null,
   length: { params: ['value'], returns: 'value' },
   count: { params: ['nodes'], returns: 'value' },
   match: { params: ['value', 'value'], returns: 'logical' },
@@ -105,21 +112,83 @@ const FUNCTIONS = {
   value: { params: ['nodes'], returns: 'value' },
 };
 
-//#endregion
+// function-name = LCALPHA *(LCALPHA / "_" / DIGIT)   (RFC 9535 2.4.1)
+const RE_FUNCTION_NAME = /^[a-z][a-z0-9_]*$/;
+const TYPE_NAMES = ['value', 'nodes', 'logical'];
 
-//#region parser
+// Registries are validated once and memoized on the registry object, so
+// compiling a thousand queries against one registry validates it once.
+const FUNCTION_TABLES = new WeakMap();
 
-function isNameFirstCode(c) {
-  return (c >= 0x41 && c <= 0x5A) // A-Z
-    || (c >= 0x61 && c <= 0x7A) // a-z
-    || c === CC_UNDERSCORE
-    || c >= 0x80; // any non-ASCII code unit
+function registryError(message) {
+  return new TypeError(`options.pathFunctions: ${message}`);
 }
 
-function isNameCharCode(c) {
-  return isNameFirstCode(c) || isDigitCode(c);
+function validateType(type, what) {
+  if (!TYPE_NAMES.includes(type))
+    throw registryError(`${what} must be one of ${TYPE_NAMES.join(', ')}`);
 }
 
+/**
+ * Validate a registry of custom function extensions and merge it over
+ * the built-ins. A registry entry declares its parameter and result
+ * types exactly like a built-in, which is what lets the parser apply
+ * the same well-typedness rules (RFC 9535 section 2.4.3) to it.
+ * @param {object} functions - name to `{ params, returns, evaluate }`
+ * @returns {object} the merged, null-prototype function table
+ */
+function resolveFunctionTable(functions) {
+  const cached = FUNCTION_TABLES.get(functions);
+  if (cached !== undefined)
+    return cached;
+  const table = { __proto__: null, ...FUNCTIONS };
+  for (const name of Object.keys(functions)) {
+    const def = functions[name];
+    if (!RE_FUNCTION_NAME.test(name))
+      throw registryError(`'${name}' is not a valid function name`);
+    // section 2.4.1: an extension must not redefine a built-in, and a
+    // literal keyword would be unreadable as a call
+    if (FUNCTIONS[name] !== undefined)
+      throw registryError(`'${name}' is a built-in function`);
+    if (name === 'true' || name === 'false' || name === 'null')
+      throw registryError(`'${name}' is a literal, not a function name`);
+    if (def === null || typeof def !== 'object')
+      throw registryError(`'${name}' must be a { params, returns, evaluate } object`);
+    if (!Array.isArray(def.params))
+      throw registryError(`'${name}'.params must be an array of parameter types`);
+    for (let i = 0; i < def.params.length; i++)
+      validateType(def.params[i], `'${name}'.params[${i}]`);
+    validateType(def.returns, `'${name}'.returns`);
+    if (typeof def.evaluate !== 'function')
+      throw registryError(`'${name}'.evaluate must be a function`);
+    table[name] = {
+      params: [...def.params],
+      returns: def.returns,
+      evaluate: def.evaluate,
+    };
+  }
+  Object.freeze(table);
+  FUNCTION_TABLES.set(functions, table);
+  return table;
+}
+
+// Resolve the function table a parse should use. The overwhelmingly
+// common call has no options at all and reaches the built-ins directly.
+function functionTableOf(options) {
+  if (options == null)
+    return FUNCTIONS;
+  const functions = options.pathFunctions;
+  if (functions == null)
+    return FUNCTIONS;
+  if (typeof functions !== 'object' || Array.isArray(functions))
+    throw registryError('must be a plain object of function extensions');
+  return resolveFunctionTable(functions);
+}
+
+//#endregion
+
+//#region parser
+
 /**
  * Selects a named object member (RFC 9535 name selector).
  * @typedef {Object} JSONPathNameSelector
@@ -196,6 +265,7 @@ function isNameCharCode(c) {
  *   values: (data: any) => any[],
  *   first: (data: any) => any,
  *   exists: (data: any) => boolean,
+ *   iterate: (data: any) => Generator<any>,
  *   nodes: (data: any) => JSONPathNode[],
  *   paths: (data: any) => string[],
  *   source: string,
@@ -203,16 +273,43 @@ function isNameCharCode(c) {
  * }} JSONPathQuery
  */
 
+/**
+ * A custom JSONPath function extension (RFC 9535 section 2.4). The
+ * declared types are what the parser type-checks call sites against
+ * (section 2.4.3), exactly as it does for the five built-ins.
+ *
+ * `evaluate` receives one argument per declared parameter: a `value`
+ * parameter arrives as a JSON value or `JSONPATH_NOTHING`, a `nodes`
+ * parameter as an array of the selected values, a `logical` parameter
+ * as a boolean. Its result must match `returns` - a `value` function
+ * may return `undefined` to mean Nothing.
+ * @typedef {Object} JSONPathFunction
+ * @property {('value'|'nodes'|'logical')[]} params - Declared parameter types
+ * @property {'value'|'nodes'|'logical'} returns - Declared result type
+ * @property {(...args: any[]) => any} evaluate - The implementation
+ */
+
+/**
+ * Options accepted by the JSONPath entry points.
+ * @typedef {Object} JSONPathOptions
+ * @property {Record<string, JSONPathFunction>} [pathFunctions] - Custom
+ *   function extensions, by name. A name must match the RFC's
+ *   `function-name` production and must not redefine a built-in.
+ */
+
 /**
  * Parse a JSONPath query string into an AST.
  * @param {string} source - The JSONPath expression (e.g. `$.store.book[?@.price < 10].title`)
+ * @param {JSONPathOptions} [options] - Parse options
  * @returns {JSONPathAst} The parsed query AST
  * @throws {JSONPathSyntaxError} When the query violates the RFC 9535 grammar
+ * @throws {TypeError} When `options.pathFunctions` is not a valid registry
  */
-export function parseJSONPath(source) {
+export function parseJSONPath(source, options = undefined) {
   if (typeof source !== 'string')
     throw new JSONPathSyntaxError('query must be a string', String(source), 0);
 
+  const FUNCS = functionTableOf(options);
   const len = source.length;
   let pos = 0;
 
@@ -247,7 +344,7 @@ export function parseJSONPath(source) {
 
   function parseMemberNameShorthand() {
     const start = pos;
-    if (!isNameFirstCode(cc(pos)))
+    if (!isNameStartCode(cc(pos)))
       fail('expected member name');
     while (pos < len) {
       const c = source.charCodeAt(pos);
@@ -779,7 +876,7 @@ export function parseJSONPath(source) {
   }
 
   function parseFunctionExpr(name, at) {
-    const def = FUNCTIONS[name];
+    const def = FUNCS[name];
     if (def === undefined)
       fail(`unknown function '${name}'`, at);
     pos++; // consume '('
@@ -787,7 +884,12 @@ export function parseJSONPath(source) {
     const args = [];
     if (cc(pos) !== CC_RPAREN) {
       for (;;) {
-        args.push(parseFunctionArg());
+        // argument parsing is type-directed: a LogicalType parameter
+        // takes the whole logical-expr production (RFC 9535 2.4.3), so
+        // `!`, `(`, comparisons and `&&`/`||` are only legal there
+        args.push(def.params[args.length] === 'logical'
+          ? { kind: 'logical', expr: parseLogicalOr() }
+          : parseFunctionArg());
         skipWS();
         if (cc(pos) === CC_COMMA) {
           pos++;
@@ -816,15 +918,22 @@ export function parseJSONPath(source) {
           continue;
         fail(`argument ${i + 1} of '${name}' must be of type ValueType`, at);
       }
-      else { // 'nodes'
+      else if (param === 'nodes') {
         if (arg.kind === 'query')
           continue;
         if (arg.kind === 'func' && arg.returns === 'nodes')
           continue;
         fail(`argument ${i + 1} of '${name}' must be a query (NodesType)`, at);
       }
+      // 'logical': parseLogicalOr only produces well-typed logical
+      // expressions, and it already rejects a ValueType function there
+    }
+    const node = { kind: 'func', name, args, returns: def.returns };
+    if (def.evaluate !== undefined) {
+      node.params = def.params;
+      node.evaluate = def.evaluate;
     }
-    return { kind: 'func', name, args, returns: def.returns };
+    return node;
   }
 
   //#endregion
@@ -860,6 +969,9 @@ export function parseJSONPath(source) {
  * - `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.iterate(data)` - a generator yielding matched values on
+ *   demand, in document order; `first`/`exists` are one pull of it, so
+ *   none of the three builds a nodelist it does not need
  * - `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
@@ -867,18 +979,20 @@ export function parseJSONPath(source) {
  *   compiled path mode must agree with the eagerly compiled value mode)
  *
  * @param {string} source - The JSONPath expression
+ * @param {JSONPathOptions} [options] - Compile options
  * @returns {JSONPathQuery} The compiled query function
  * @throws {JSONPathSyntaxError} When the query is not valid RFC 9535
+ * @throws {TypeError} When `options.pathFunctions` is not a valid registry
  * @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 function compileJSONPath(source) {
-  const ast = deepFreeze(parseJSONPath(source));
+export function compileJSONPath(source, options = undefined) {
+  const ast = deepFreeze(parseJSONPath(source, options));
   const segments = ast.segments;
 
-  let values, first, exists;
+  let values, first, exists, iterate;
   if (isSingularSegments(segments)) {
     const getter = compileSingularGetter(segments, false);
     values = (data) => {
@@ -890,15 +1004,29 @@ export function compileJSONPath(source) {
       return v === NOTHING ? undefined : v;
     };
     exists = (data) => getter(data, data) !== NOTHING;
+    iterate = function* iterateSingular(data) {
+      const v = getter(data, data);
+      if (v !== NOTHING)
+        yield v;
+    };
   }
   else {
     const segs = segments.map(compileSegmentV);
     values = (data) => runSegmentsV(segs, data, data);
+    // the lazy chain is a second compilation of the same selectors, so
+    // it is built on first use - a query that only ever calls values()
+    // never pays for it
+    let gens = null;
+    iterate = (data) => {
+      if (gens === null)
+        gens = segments.map(compileSegmentG);
+      return runSegmentsG(gens, 0, data, data);
+    };
     first = (data) => {
-      const result = runSegmentsV(segs, data, data);
-      return result.length !== 0 ? result[0] : undefined;
+      const r = iterate(data).next();
+      return r.done ? undefined : r.value;
     };
-    exists = (data) => runSegmentsV(segs, data, data).length !== 0;
+    exists = (data) => !iterate(data).next().done;
   }
 
   // nodes mode is compiled lazily; value-only queries never pay for it
@@ -913,6 +1041,7 @@ export function compileJSONPath(source) {
   query.values = values;
   query.first = first;
   query.exists = exists;
+  query.iterate = iterate;
   query.nodes = (data) => {
     const { vals, paths } = runNodes(data);
     const nodes = new Array(vals.length);
@@ -926,26 +1055,31 @@ export function compileJSONPath(source) {
   return query;
 }
 
-const QUERY_CACHE = new Map();
-const QUERY_CACHE_LIMIT = 512;
+const QUERY_CACHE = createBoundedCache(512);
+// One cache per registry, because the same source compiles differently
+// under different extensions; keyed weakly so a registry that goes out
+// of scope takes its compiled queries with it. A WeakMap of bounded
+// caches — the two axes of `@jarenjs/core/cache`, composed.
+const REGISTRY_CACHES = createWeakCache();
+const boundedCacheFor = () => createBoundedCache(512);
 
 /**
  * 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.
+ * are cached (bounded LRU, 512 entries), so repeated calls with the
+ * same query string reuse the compiled function. A query compiled
+ * against a function-extension registry is cached under that registry.
  * @param {string} source - The JSONPath expression
  * @param {any} data - The JSON value to query
+ * @param {JSONPathOptions} [options] - Compile options
  * @returns {any[]} Array of matched values
  * @throws {JSONPathSyntaxError} When the query is not valid RFC 9535
  */
-export function queryJSONPath(source, data) {
-  let query = QUERY_CACHE.get(source);
-  if (query === undefined) {
-    query = compileJSONPath(source);
-    if (QUERY_CACHE.size >= QUERY_CACHE_LIMIT)
-      QUERY_CACHE.delete(QUERY_CACHE.keys().next().value);
-    QUERY_CACHE.set(source, query);
-  }
+export function queryJSONPath(source, data, options = undefined) {
+  const functions = options == null ? null : options.pathFunctions;
+  const cache = functions == null
+    ? QUERY_CACHE
+    : REGISTRY_CACHES.getOrCreate(functions, boundedCacheFor);
+  const query = cache.getOrCreate(source, (src) => compileJSONPath(src, options));
   return query(data);
 }
 
@@ -953,25 +1087,158 @@ export function queryJSONPath(source, data) {
  * 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.
+ *
+ * Without options this recognizes the five built-in functions and
+ * nothing else, which is what the registered `json-path` string format
+ * asserts: a format is a property of the string itself, so it must mean
+ * the same thing in every schema, independent of which extensions some
+ * host happens to have installed. Pass `options.pathFunctions` to
+ * validate against a registry instead - a host that wants its
+ * extensions asserted registers a tester bound to them.
+ *
  * @param {string} str - The JSONPath expression to validate
+ * @param {JSONPathOptions} [options] - Compile options
  * @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 function isValidJSONPathStrict(str) {
+export function isValidJSONPathStrict(str, options = undefined) {
   if (typeof str !== 'string')
     return false;
   try {
-    parseJSONPath(str);
+    parseJSONPath(str, options);
     return true;
   }
-  catch {
+  catch (error) {
+    // a malformed registry is the host's bug, not the string's
+    if (!(error instanceof JSONPathSyntaxError))
+      throw error;
     return false;
   }
 }
 
+/**
+ * The head of a variable-rooted path string: `$` followed by a variable
+ * name. The Jaren query format writes a path relative to a bound
+ * variable as `$name` plus ordinary RFC 9535 segments, and the query
+ * normalizer splits on exactly this production - so schema-time
+ * validation and compile-time parsing agree on where the segments start.
+ */
+export const RE_JSONPATH_VARIABLE_HEAD = /^\$([A-Za-z_][A-Za-z0-9_]*)/;
+
+/**
+ * Validates a variable-rooted path string: `$name`, optionally followed
+ * by RFC 9535 segments (`$book.price`, `$b[?@.isbn]`, `$item`).
+ *
+ * This is the counterpart of `isValidJSONPathStrict` for paths whose
+ * root is a bound variable rather than the document. Such a string is
+ * not a valid RFC 9535 query - the RFC's root identifier is `$` alone -
+ * so it can only be checked by recognizing the head and validating the
+ * tail as segments, which is what the query normalizer does before it
+ * raises `JQ0004`. Without this, a schema could only pattern-check the
+ * head and had to leave the segment grammar to the compiler.
+ *
+ * @param {string} str - The variable-rooted path string to validate
+ * @param {JSONPathOptions} [options] - Parse options
+ * @returns {boolean} True when the string is a well-formed variable-rooted path
+ * @example
+ * isValidJSONPathSegments('$book.price'); // true
+ * isValidJSONPathSegments('$book'); // true (no segments)
+ * isValidJSONPathSegments('$book.price['); // false (unterminated segment)
+ * isValidJSONPathSegments('$.price'); // false (no variable name; that is json-path)
+ */
+export function isValidJSONPathSegments(str, options = undefined) {
+  if (typeof str !== 'string')
+    return false;
+  const head = RE_JSONPATH_VARIABLE_HEAD.exec(str);
+  if (head === null)
+    return false;
+  const rest = str.slice(head[0].length);
+  if (rest === '')
+    return true;
+  try {
+    // the tail is validated by parsing it under a substituted root,
+    // exactly as the normalizer compiles it
+    parseJSONPath('$' + rest, options);
+    return true;
+  }
+  catch (error) {
+    if (!(error instanceof JSONPathSyntaxError))
+      throw error;
+    return false;
+  }
+}
+
+//#endregion
+
+//#region normalized path <-> JSON Pointer bridge
+
+/**
+ * Convert a singular JSONPath query - which includes every RFC 9535
+ * normalized path - to an RFC 6901 JSON Pointer, so the two addressing
+ * standards compose.
+ *
+ * Any singular form is accepted (`$['store']['book'][0]`, `$.store.book[0]`);
+ * non-singular queries and negative (from-the-end) indexes are rejected,
+ * because a pointer cannot express them.
+ *
+ * @param {string} source - A singular JSONPath query
+ * @returns {string} The equivalent JSON Pointer
+ * @throws {JSONPathSyntaxError} When the query is invalid, not singular,
+ *   or uses a negative index
+ * @example
+ * jsonPointerFromJSONPath("$['store']['book'][0]['a/b']"); // '/store/book/0/a~1b'
+ */
+export function jsonPointerFromJSONPath(source) {
+  const { segments } = parseJSONPath(source);
+  if (!isSingularSegments(segments))
+    throw new JSONPathSyntaxError('only a singular query converts to a JSON Pointer', source, 0);
+  let pointer = '';
+  for (let i = 0; i < segments.length; i++) {
+    const sel = segments[i].selectors[0];
+    if (sel.kind === 'name') {
+      pointer += '/' + encodeJSONPointerSegment(sel.name);
+    }
+    else {
+      if (sel.index < 0)
+        throw new JSONPathSyntaxError('a negative index has no JSON Pointer form', source, 0);
+      pointer += '/' + sel.index;
+    }
+  }
+  return pointer;
+}
+
+/**
+ * Convert an RFC 6901 JSON Pointer to an RFC 9535 normalized path.
+ *
+ * A pointer token is one text with two readings (RFC 6901 lets `"2"`
+ * address both a `"2"` member and array element 2); a normalized path
+ * must pick one. Convention: a token that is a valid array index (digits,
+ * no leading zeros) becomes an index selector `[2]`, everything else a
+ * name selector `['name']`. A pointer addressing an object member that
+ * merely looks like an index is therefore converted to the index form -
+ * convert with the document in hand (e.g. via `query.paths`) when that
+ * distinction matters.
+ *
+ * @param {string} pointer - The JSON Pointer (e.g. `/store/book/0`)
+ * @returns {string} The normalized path (e.g. `$['store']['book'][0]`)
+ * @throws {JSONPointerSyntaxError} When the pointer is not valid RFC 6901
+ * @example
+ * jsonPathFromJSONPointer('/store/book/0'); // "$['store']['book'][0]"
+ */
+export function jsonPathFromJSONPointer(pointer) {
+  const segments = parseJSONPointer(pointer);
+  let path = '$';
+  for (let i = 0; i < segments.length; i++) {
+    const name = segments[i];
+    const index = scanArrayIndex(name, 0, name.length);
+    path = index >= 0 ? path + '[' + index + ']' : appendName(path, name);
+  }
+  return path;
+}
+
 //#endregion
 
 //#endregion