json-p3 0.2.1 → 0.3.1

package/dist/json-p3.iife.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
@@ -646,10 +646,6 @@ var json_p3 = (function (exports) {
    * 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_.
@@ -659,9 +655,12 @@ var json_p3 = (function (exports) {
       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("")
+      );
     }
 
     /**
@@ -913,7 +912,7 @@ var json_p3 = (function (exports) {
   }
   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)}`;
@@ -921,7 +920,7 @@ var json_p3 = (function (exports) {
   }
   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();
@@ -939,12 +938,26 @@ var json_p3 = (function (exports) {
       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;
+      }
+    }
   }
 
   /**
@@ -1723,6 +1736,10 @@ var json_p3 = (function (exports) {
       this.token = token;
     }
 
+    /**
+     * @param nodes - Nodes matched by preceding selectors.
+     */
+
     /**
      * @param nodes - Nodes matched by preceding selectors.
      */
@@ -1750,7 +1767,14 @@ var json_p3 = (function (exports) {
           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}'`;
@@ -1780,7 +1804,17 @@ var json_p3 = (function (exports) {
           }
         }
       }
-      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);
@@ -1808,7 +1842,15 @@ var json_p3 = (function (exports) {
           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 : "";
@@ -1891,22 +1933,92 @@ var json_p3 = (function (exports) {
           }
         }
       }
-      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;
@@ -1914,19 +2026,25 @@ var json_p3 = (function (exports) {
         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 {
@@ -1967,7 +2085,40 @@ var json_p3 = (function (exports) {
           }
         }
       }
-      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()}`;
@@ -1984,10 +2135,19 @@ var json_p3 = (function (exports) {
       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(", ")}]`;
@@ -2026,10 +2186,23 @@ var json_p3 = (function (exports) {
      * @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;
     }
 
@@ -2042,7 +2215,10 @@ var json_p3 = (function (exports) {
      * 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;
     }
 
     /**
@@ -2062,13 +2238,17 @@ var json_p3 = (function (exports) {
   }
 
   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;
@@ -2085,30 +2265,41 @@ var json_p3 = (function (exports) {
     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);
@@ -2229,7 +2420,7 @@ var json_p3 = (function (exports) {
     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();
@@ -2239,11 +2430,9 @@ var json_p3 = (function (exports) {
       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);
     }
@@ -2331,16 +2520,15 @@ var json_p3 = (function (exports) {
         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);
+        }
       }
     }
   }
@@ -2351,7 +2539,10 @@ var json_p3 = (function (exports) {
    */
 
   /**
+   * 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 {
     /**
@@ -2384,8 +2575,7 @@ var json_p3 = (function (exports) {
      */
     functionRegister = new Map();
     /**
-     *
-     * @param options -
+     * @param options - Environment configuration options.
      */
     constructor() {
       let options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
@@ -2398,9 +2588,8 @@ var json_p3 = (function (exports) {
     }
 
     /**
-     *
-     * @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))));
@@ -2408,14 +2597,28 @@ var json_p3 = (function (exports) {
 
     /**
      *
-     * @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_.
@@ -2428,6 +2631,11 @@ var json_p3 = (function (exports) {
     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());
@@ -2437,9 +2645,18 @@ var json_p3 = (function (exports) {
     }
 
     /**
+     * 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) {
@@ -2506,6 +2723,27 @@ var json_p3 = (function (exports) {
     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.
@@ -2555,6 +2793,7 @@ var json_p3 = (function (exports) {
     compile: compile,
     expressions: expression,
     functions: index$2,
+    lazyQuery: lazyQuery,
     match: match,
     query: query,
     selectors: selectors
@@ -3040,7 +3279,7 @@ var json_p3 = (function (exports) {
     apply: apply
   });
 
-  const version = "0.2.0";
+  const version = "0.3.1";
 
   exports.DEFAULT_ENVIRONMENT = DEFAULT_ENVIRONMENT;
   exports.FunctionExpressionType = FunctionExpressionType;
@@ -3068,6 +3307,7 @@ var json_p3 = (function (exports) {
   exports.jsonpatch = index;
   exports.jsonpath = index$1;
   exports.jsonpointer = index$3;
+  exports.lazyQuery = lazyQuery;
   exports.query = query;
   exports.resolve = resolve;
   exports.version = version;