json-p3 0.2.1 → 0.3.1

package/dist/json-p3.esm.js

@@ -1,5 +1,5 @@
 /*
- * json-p3 version 0.2.0
+ * json-p3 version 0.3.1
  * https://github.com/jg-rp/json-p3
  * 
  * MIT License
@@ -643,10 +643,6 @@ var index$3 = /*#__PURE__*/Object.freeze({
  * The pair of a JSON value and its location found in the target JSON value.
  */
 class JSONPathNode {
-  /**
-   * The normalized path to this node in the target JSON value.
-   */
-
   /**
    * @param value - The JSON value found at _location_.
    * @param location - The parts of a normalized path to _value_.
@@ -656,9 +652,12 @@ class JSONPathNode {
     this.value = value;
     this.location = location;
     this.root = root;
-    this.path =
-    // eslint-disable-next-line prefer-template
-    "$" + location.map(s => isString(s) ? `['${s}']` : `[${s}]`).join("");
+  }
+  get path() {
+    return (
+      // eslint-disable-next-line prefer-template
+      "$" + this.location.map(s => isString(s) ? `['${s}']` : `[${s}]`).join("")
+    );
   }
 
   /**
@@ -910,7 +909,7 @@ class JSONPathQuery extends FilterExpression {
 }
 class RelativeQuery extends JSONPathQuery {
   evaluate(context) {
-    return this.path.query(context.currentValue);
+    return context.lazy ? new JSONPathNodeList(Array.from(this.path.lazyQuery(context.currentValue))) : this.path.query(context.currentValue);
   }
   toString() {
     return `@${this.path.toString().slice(1)}`;
@@ -918,7 +917,7 @@ class RelativeQuery extends JSONPathQuery {
 }
 class RootQuery extends JSONPathQuery {
   evaluate(context) {
-    return this.path.query(context.rootValue);
+    return context.lazy ? new JSONPathNodeList(Array.from(this.path.lazyQuery(context.rootValue))) : this.path.query(context.rootValue);
   }
   toString() {
     return this.path.toString();
@@ -936,12 +935,26 @@ class FunctionExtension extends FilterExpression {
     if (!func) {
       throw new UndefinedFilterFunctionError(`filter function '${this.name}' is undefined`, this.token);
     }
-    const args = this.args.map(arg => arg.evaluate(context)).map((arg, idx) => func.argTypes[idx] !== FunctionExpressionType.NodesType && arg instanceof JSONPathNodeList ? arg.valuesOrSingular() : arg);
+    const args = this.args.map(arg => arg.evaluate(context)).map((arg, idx) => func.argTypes[idx] !== FunctionExpressionType.NodesType && arg instanceof JSONPathNodeList ? this.unpack_node_list(arg) : arg);
     return func.call(...args);
   }
   toString() {
     return `${this.name}(${this.args.map(e => e.toString()).join(", ")})`;
   }
+  unpack_node_list(arg) {
+    switch (arg.length) {
+      case 0:
+        // If the query results in an empty node list, the argument
+        // is the special result Nothing.
+        return Nothing;
+      case 1:
+        // If the query results in a node list consisting of a single
+        // node, the argument is the value of the node
+        return arg.nodes[0].value;
+      default:
+        return arg;
+    }
+  }
 }
 
 /**
@@ -1720,6 +1733,10 @@ class JSONPathSelector {
     this.token = token;
   }
 
+  /**
+   * @param nodes - Nodes matched by preceding selectors.
+   */
+
   /**
    * @param nodes - Nodes matched by preceding selectors.
    */
@@ -1747,7 +1764,14 @@ class NameSelector extends JSONPathSelector {
         rv.push(new JSONPathNode(node.value[this.name], node.location.concat(this.name), node.root));
       }
     }
-    return new JSONPathNodeList(rv);
+    return rv;
+  }
+  *lazyResolve(nodes) {
+    for (const node of nodes) {
+      if (hasStringKey(node.value, this.name)) {
+        yield new JSONPathNode(node.value[this.name], node.location.concat(this.name), node.root);
+      }
+    }
   }
   toString() {
     return this.shorthand ? `['${this.name}']` : `'${this.name}'`;
@@ -1777,7 +1801,17 @@ class IndexSelector extends JSONPathSelector {
         }
       }
     }
-    return new JSONPathNodeList(rv);
+    return rv;
+  }
+  *lazyResolve(nodes) {
+    for (const node of nodes) {
+      if (isArray(node.value)) {
+        const normIndex = this.normalizedIndex(node.value.length);
+        if (normIndex in node.value) {
+          yield new JSONPathNode(node.value[normIndex], node.location.concat(normIndex), node.root);
+        }
+      }
+    }
   }
   toString() {
     return String(this.index);
@@ -1805,7 +1839,15 @@ class SliceSelector extends JSONPathSelector {
         rv.push(new JSONPathNode(value, node.location.concat(i), node.root));
       }
     }
-    return new JSONPathNodeList(rv);
+    return rv;
+  }
+  *lazyResolve(nodes) {
+    for (const node of nodes) {
+      if (!isArray(node.value)) continue;
+      for (const [i, value] of this.slice(node.value, this.start, this.stop, this.step)) {
+        yield new JSONPathNode(value, node.location.concat(i), node.root);
+      }
+    }
   }
   toString() {
     const start = this.start ? this.start : "";
@@ -1888,22 +1930,92 @@ class WildcardSelector extends JSONPathSelector {
         }
       }
     }
-    return new JSONPathNodeList(rv);
+    return rv;
+  }
+  *lazyResolve(nodes) {
+    for (const node of nodes) {
+      if (node.value instanceof String) continue;
+      if (isArray(node.value)) {
+        for (let i = 0; i < node.value.length; i++) {
+          yield new JSONPathNode(node.value[i], node.location.concat(i), node.root);
+        }
+      } else if (isObject(node.value)) {
+        for (const [key, value] of Object.entries(node.value)) {
+          yield new JSONPathNode(value, node.location.concat(key), node.root);
+        }
+      }
+    }
   }
   toString() {
     return this.shorthand ? "[*]" : "*";
   }
 }
 class RecursiveDescentSegment extends JSONPathSelector {
+  constructor(environment, token, selector) {
+    super(environment, token);
+    this.environment = environment;
+    this.token = token;
+    this.selector = selector;
+  }
   resolve(nodes) {
     const rv = [];
     for (const node of nodes) {
-      rv.push(node, ...this.visit(node));
+      rv.push(node);
+      for (const _node of this.visit(node)) {
+        rv.push(_node);
+      }
+    }
+    return this.selector.resolve(rv);
+  }
+  *lazyResolve(nodes) {
+    yield* this.selector.lazyResolve(this._lazyResolve(nodes));
+  }
+
+  // eslint-disable-next-line sonarjs/cognitive-complexity
+  *_lazyResolve(nodes) {
+    for (const _node of nodes) {
+      const stack = [{
+        node: _node,
+        depth: 0
+      }];
+      yield _node;
+      while (stack.length) {
+        const {
+          node: currentNode,
+          depth
+        } = stack.pop();
+        if (depth >= this.environment.maxRecursionDepth) {
+          throw new JSONPathRecursionLimitError("recursion limit reached", this.token);
+        }
+        if (currentNode.value instanceof String) continue;
+        if (isArray(currentNode.value)) {
+          for (let i = 0; i < currentNode.value.length; i++) {
+            const __node = new JSONPathNode(currentNode.value[i], currentNode.location.concat(i), currentNode.root);
+            yield __node;
+            if (isObject(__node.value)) {
+              stack.push({
+                node: __node,
+                depth: depth + 1
+              });
+            }
+          }
+        } else if (isObject(currentNode.value)) {
+          for (const [key, value] of Object.entries(currentNode.value)) {
+            const __node = new JSONPathNode(value, currentNode.location.concat(key), currentNode.root);
+            yield __node;
+            if (isObject(__node.value)) {
+              stack.push({
+                node: __node,
+                depth: depth + 1
+              });
+            }
+          }
+        }
+      }
     }
-    return new JSONPathNodeList(rv);
   }
   toString() {
-    return "..";
+    return `..${this.selector.toString()}`;
   }
   visit(node) {
     let depth = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 1;
@@ -1911,19 +2023,25 @@ class RecursiveDescentSegment extends JSONPathSelector {
       throw new JSONPathRecursionLimitError("recursion limit reached", this.token);
     }
     const rv = [];
-    if (node.value instanceof String) return new JSONPathNodeList(rv);
+    if (node.value instanceof String) return rv;
     if (isArray(node.value)) {
       for (let i = 0; i < node.value.length; i++) {
         const _node = new JSONPathNode(node.value[i], node.location.concat(i), node.root);
-        rv.push(_node, ...this.visit(_node, depth + 1));
+        rv.push(_node);
+        for (const __node of this.visit(_node, depth + 1)) {
+          rv.push(__node);
+        }
       }
     } else if (isObject(node.value)) {
       for (const [key, value] of Object.entries(node.value)) {
         const _node = new JSONPathNode(value, node.location.concat(key), node.root);
-        rv.push(_node, ...this.visit(_node, depth + 1));
+        rv.push(_node);
+        for (const __node of this.visit(_node, depth + 1)) {
+          rv.push(__node);
+        }
       }
     }
-    return new JSONPathNodeList(rv);
+    return rv;
   }
 }
 class FilterSelector extends JSONPathSelector {
@@ -1964,7 +2082,40 @@ class FilterSelector extends JSONPathSelector {
         }
       }
     }
-    return new JSONPathNodeList(rv);
+    return rv;
+  }
+
+  // eslint-disable-next-line sonarjs/cognitive-complexity
+  *lazyResolve(nodes) {
+    for (const node of nodes) {
+      if (node.value instanceof String) continue;
+      if (isArray(node.value)) {
+        for (let i = 0; i < node.value.length; i++) {
+          const value = node.value[i];
+          const filterContext = {
+            environment: this.environment,
+            currentValue: value,
+            rootValue: node.root,
+            lazy: true
+          };
+          if (this.expression.evaluate(filterContext)) {
+            yield new JSONPathNode(value, node.location.concat(i), node.root);
+          }
+        }
+      } else if (isObject(node.value)) {
+        for (const [key, value] of Object.entries(node.value)) {
+          const filterContext = {
+            environment: this.environment,
+            currentValue: value,
+            rootValue: node.root,
+            lazy: true
+          };
+          if (this.expression.evaluate(filterContext)) {
+            yield new JSONPathNode(value, node.location.concat(key), node.root);
+          }
+        }
+      }
+    }
   }
   toString() {
     return `?${this.expression.toString()}`;
@@ -1981,10 +2132,19 @@ class BracketedSelection extends JSONPathSelector {
     const rv = [];
     for (const node of nodes) {
       for (const item of this.items) {
-        rv.push(...item.resolve(new JSONPathNodeList([node])));
+        for (const _node of item.resolve([node])) {
+          rv.push(_node);
+        }
+      }
+    }
+    return rv;
+  }
+  *lazyResolve(nodes) {
+    for (const node of nodes) {
+      for (const item of this.items) {
+        yield* item.lazyResolve([node]);
       }
     }
-    return new JSONPathNodeList(rv);
   }
   toString() {
     return `[${this.items.map(itm => itm.toString()).join(", ")}]`;
@@ -2023,10 +2183,23 @@ class JSONPath {
    * @returns
    */
   query(value) {
-    let nodes = new JSONPathNodeList([new JSONPathNode(value, [], value)]);
+    let nodes = [new JSONPathNode(value, [], value)];
     for (const selector of this.selectors) {
       nodes = selector.resolve(nodes);
     }
+    return new JSONPathNodeList(nodes);
+  }
+
+  /**
+   *
+   * @param value -
+   * @returns
+   */
+  lazyQuery(value) {
+    let nodes = [new JSONPathNode(value, [], value)][Symbol.iterator]();
+    for (const selector of this.selectors) {
+      nodes = selector.lazyResolve(nodes);
+    }
     return nodes;
   }
 
@@ -2039,7 +2212,10 @@ class JSONPath {
    * there are no matches.
    */
   match(value) {
-    return this.query(value).nodes.at(0);
+    const it = this.lazyQuery(value);
+    const rv = it.next();
+    if (rv.done) return undefined;
+    return rv.value;
   }
 
   /**
@@ -2059,13 +2235,17 @@ class JSONPath {
 }
 
 const PRECEDENCE_LOWEST = 1;
-const PRECEDENCE_LOGICALRIGHT = 3;
 const PRECEDENCE_LOGICAL_AND = 4;
 const PRECEDENCE_LOGICAL_OR = 5;
 const PRECEDENCE_COMPARISON = 6;
-const PRECEDENCES = new Map([[TokenKind.AND, PRECEDENCE_LOGICAL_AND], [TokenKind.EQ, PRECEDENCE_COMPARISON], [TokenKind.GE, PRECEDENCE_COMPARISON], [TokenKind.GT, PRECEDENCE_COMPARISON], [TokenKind.LE, PRECEDENCE_COMPARISON], [TokenKind.LT, PRECEDENCE_COMPARISON], [TokenKind.NE, PRECEDENCE_COMPARISON], [TokenKind.NOT, PRECEDENCE_LOGICALRIGHT], [TokenKind.OR, PRECEDENCE_LOGICAL_OR], [TokenKind.RPAREN, PRECEDENCE_LOWEST]]);
+const PRECEDENCE_PREFIX = 7;
+const PRECEDENCES = new Map([[TokenKind.AND, PRECEDENCE_LOGICAL_AND], [TokenKind.EQ, PRECEDENCE_COMPARISON], [TokenKind.GE, PRECEDENCE_COMPARISON], [TokenKind.GT, PRECEDENCE_COMPARISON], [TokenKind.LE, PRECEDENCE_COMPARISON], [TokenKind.LT, PRECEDENCE_COMPARISON], [TokenKind.NE, PRECEDENCE_COMPARISON], [TokenKind.NOT, PRECEDENCE_PREFIX], [TokenKind.OR, PRECEDENCE_LOGICAL_OR], [TokenKind.RPAREN, PRECEDENCE_LOWEST]]);
 const BINARY_OPERATORS = new Map([[TokenKind.AND, "&&"], [TokenKind.EQ, "=="], [TokenKind.GE, ">="], [TokenKind.GT, ">"], [TokenKind.LE, "<="], [TokenKind.LT, "<"], [TokenKind.NE, "!="], [TokenKind.OR, "||"]]);
 const COMPARISON_OPERATORS = new Set(["==", ">=", ">", "<=", "<", "!="]);
+
+/**
+ * JSONPath token stream parser.
+ */
 class Parser {
   constructor(environment) {
     this.environment = environment;
@@ -2082,30 +2262,41 @@ class Parser {
   parsePath(stream) {
     let inFilter = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
     const selectors = [];
-    loop: for (;;) {
-      switch (stream.current.kind) {
-        case TokenKind.NAME:
-          selectors.push(new NameSelector(this.environment, stream.current, stream.current.value, true));
-          break;
-        case TokenKind.WILD:
-          selectors.push(new WildcardSelector(this.environment, stream.current, true));
-          break;
-        case TokenKind.DDOT:
-          selectors.push(new RecursiveDescentSegment(this.environment, stream.current));
-          break;
-        case TokenKind.LBRACKET:
-          selectors.push(this.parseBracketedSelection(stream));
-          break;
-        default:
-          if (inFilter) {
-            stream.backup();
-          }
-          break loop;
+    for (;;) {
+      const selector = this.parseSegment(stream);
+      if (!selector) {
+        if (inFilter) {
+          stream.backup();
+        }
+        break;
       }
+      selectors.push(selector);
       stream.next();
     }
     return selectors;
   }
+  parseSegment(stream) {
+    switch (stream.current.kind) {
+      case TokenKind.NAME:
+        return new NameSelector(this.environment, stream.current, stream.current.value, true);
+      case TokenKind.WILD:
+        return new WildcardSelector(this.environment, stream.current, true);
+      case TokenKind.DDOT:
+        {
+          const segmentToken = stream.current;
+          stream.next();
+          const selector = this.parseSegment(stream);
+          if (!selector) {
+            throw new JSONPathSyntaxError("bald descendant segment", stream.current);
+          }
+          return new RecursiveDescentSegment(this.environment, segmentToken, selector);
+        }
+      case TokenKind.LBRACKET:
+        return this.parseBracketedSelection(stream);
+      default:
+        return null;
+    }
+  }
   parseIndex(stream) {
     if (stream.current.value.length > 1 && stream.current.value.startsWith("0") || stream.current.value.startsWith("-0")) {
       throw new JSONPathSyntaxError("leading zero in index selector", stream.current);
@@ -2226,7 +2417,7 @@ class Parser {
   parsePrefixExpression(stream) {
     stream.expect(TokenKind.NOT);
     stream.next();
-    return new PrefixExpression(stream.current, "!", this.parseFilterExpression(stream, PRECEDENCE_LOGICALRIGHT));
+    return new PrefixExpression(stream.current, "!", this.parseFilterExpression(stream, PRECEDENCE_PREFIX));
   }
   parseInfixExpression(stream, left) {
     const tok = stream.next();
@@ -2236,11 +2427,9 @@ class Parser {
     if (!operator) {
       throw new JSONPathSyntaxError(`unknown operator '${tok.kind}'`, tok);
     }
-    this.throwForNonSingularQuery(left);
-    this.throwForNonSingularQuery(right);
     if (COMPARISON_OPERATORS.has(operator)) {
-      this.throwForNonComparableFunction(left);
-      this.throwForNonComparableFunction(right);
+      this.throwForNonComparable(left);
+      this.throwForNonComparable(right);
     }
     return new InfixExpression(tok, left, operator, right);
   }
@@ -2328,16 +2517,15 @@ class Parser {
       throw new JSONPathSyntaxError(`invalid ${isName ? "name selector" : "string literal"} '${token.value}'`, token);
     }
   }
-  throwForNonSingularQuery(expr) {
+  throwForNonComparable(expr) {
     if ((expr instanceof RootQuery || expr instanceof RelativeQuery) && !expr.path.singularQuery()) {
-      throw new JSONPathSyntaxError("non-singular query is not comparable", expr.token);
+      throw new JSONPathTypeError("non-singular query is not comparable", expr.token);
     }
-  }
-  throwForNonComparableFunction(expr) {
-    if (!(expr instanceof FunctionExtension)) return;
-    const func = this.environment.functionRegister.get(expr.name);
-    if (func && func.returnType !== FunctionExpressionType.ValueType) {
-      throw new JSONPathTypeError(`result of ${expr.name}() is not comparable`, expr.token);
+    if (expr instanceof FunctionExtension) {
+      const func = this.environment.functionRegister.get(expr.name);
+      if (func && func.returnType !== FunctionExpressionType.ValueType) {
+        throw new JSONPathTypeError(`result of ${expr.name}() is not comparable`, expr.token);
+      }
     }
   }
 }
@@ -2348,7 +2536,10 @@ class Parser {
  */
 
 /**
+ * A configuration object from which JSONPath queries can be evaluated.
  *
+ * An environment is where you'd register custom function extensions or set
+ * the maximum recursion depth limit, for example.
  */
 class JSONPathEnvironment {
   /**
@@ -2381,8 +2572,7 @@ class JSONPathEnvironment {
    */
   functionRegister = new Map();
   /**
-   *
-   * @param options -
+   * @param options - Environment configuration options.
    */
   constructor() {
     let options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
@@ -2395,9 +2585,8 @@ class JSONPathEnvironment {
   }
 
   /**
-   *
-   * @param path -
-   * @returns
+   * @param path - A JSONPath query to parse.
+   * @returns A new {@link JSONPath} object, bound to this environment.
    */
   compile(path) {
     return new JSONPath(this, this.parser.parse(new TokenStream(tokenize(path))));
@@ -2405,14 +2594,28 @@ class JSONPathEnvironment {
 
   /**
    *
-   * @param path -
-   * @param value -
-   * @returns
+   * @param path - A JSONPath query to parse and evaluate against _value_.
+   * @param value - Data to which _path_ will be applied.
+   * @returns The {@link JSONPathNodeList} resulting from applying _path_
+   * to _value_.
    */
   query(path, value) {
     return this.compile(path).query(value);
   }
 
+  /**
+   * A lazy version of {@link query} which is faster and more memory
+   * efficient when querying some large datasets.
+   *
+   * @param path - A JSONPath query to parse and evaluate against _value_.
+   * @param value - Data to which _path_ will be applied.
+   * @returns A sequence of {@link JSONPathNode} objects resulting from
+   * applying _path_ to _value_.
+   */
+  lazyQuery(path, value) {
+    return this.compile(path).lazyQuery(value);
+  }
+
   /**
    * Return a {@link JSONPathNode} instance for the first object found in
    * _value_ matching _path_.
@@ -2425,6 +2628,11 @@ class JSONPathEnvironment {
   match(path, value) {
     return this.compile(path).match(value);
   }
+
+  /**
+   * A hook for setting up the function register. You are encouraged to
+   * override this method in classes extending `JSONPathEnvironment`.
+   */
   setupFilterFunctions() {
     this.functionRegister.set("count", new Count());
     this.functionRegister.set("length", new Length());
@@ -2434,9 +2642,18 @@ class JSONPathEnvironment {
   }
 
   /**
+   * Check the well-typedness of a function's arguments at compile-time.
+   *
+   * This method is called by the {@link Parser} when parsing function calls.
+   * It is expected to throw a {@link JSONPathTypeError} if the function's
+   * parameters are not well-typed.
+   *
+   * Override this if you want to deviate from the JSONPath Spec's function
+   * extension type system.
    *
-   * @param token -
-   * @param args -
+   * @param token - The {@link Token} starting the function call. `Token.value`
+   * will contain the name of the function.
+   * @param args - One {@link FilterExpression} for each argument.
    */
   // eslint-disable-next-line sonarjs/cognitive-complexity
   checkWellTypedness(token, args) {
@@ -2503,6 +2720,27 @@ function query(path, value) {
   return DEFAULT_ENVIRONMENT.query(path, value);
 }
 
+/**
+ * Lazily query JSON value _value_ with JSONPath expression _path_.
+ * Lazy queries can be faster and more memory efficient when querying
+ * large datasets, especially when using recursive decent selectors.
+ *
+ * @param path - A JSONPath expression/query.
+ * @param value - The JSON-like value the JSONPath query is applied to.
+ * @returns A sequence of {@link JSONPathNode} objects resulting from
+ * applying _path_ to _value_.
+ *
+ * @throws {@link JSONPathSyntaxError}
+ * If the path does not conform to standard syntax.
+ *
+ * @throws {@link JSONPathTypeError}
+ * If filter function arguments are invalid, or filter expression are
+ * used in an invalid way.
+ */
+function lazyQuery(path, value) {
+  return DEFAULT_ENVIRONMENT.lazyQuery(path, value);
+}
+
 /**
  * Compile JSONPath _path_ for later use.
  * @param path - A JSONPath expression/query.
@@ -2552,6 +2790,7 @@ var index$1 = /*#__PURE__*/Object.freeze({
   compile: compile,
   expressions: expression,
   functions: index$2,
+  lazyQuery: lazyQuery,
   match: match,
   query: query,
   selectors: selectors
@@ -3037,6 +3276,6 @@ var index = /*#__PURE__*/Object.freeze({
   apply: apply
 });
 
-const version = "0.2.0";
+const version = "0.3.1";
 
-export { DEFAULT_ENVIRONMENT, FunctionExpressionType, JSONPatch, JSONPatchError, JSONPatchTestFailure, JSONPath, JSONPathEnvironment, JSONPathError, JSONPathIndexError, JSONPathLexerError, JSONPathNode, JSONPathNodeList, JSONPathRecursionLimitError, JSONPathSyntaxError, JSONPathTypeError, JSONPointer, Nothing, RelativeJSONPointer, Token, TokenKind, UNDEFINED, apply, compile, index as jsonpatch, index$1 as jsonpath, index$3 as jsonpointer, query, resolve, version };
+export { DEFAULT_ENVIRONMENT, FunctionExpressionType, JSONPatch, JSONPatchError, JSONPatchTestFailure, JSONPath, JSONPathEnvironment, JSONPathError, JSONPathIndexError, JSONPathLexerError, JSONPathNode, JSONPathNodeList, JSONPathRecursionLimitError, JSONPathSyntaxError, JSONPathTypeError, JSONPointer, Nothing, RelativeJSONPointer, Token, TokenKind, UNDEFINED, apply, compile, index as jsonpatch, index$1 as jsonpath, index$3 as jsonpointer, lazyQuery, query, resolve, version };