json-p3 0.2.0 → 0.3.0

package/README.md

@@ -39,6 +39,7 @@ console.log(nodes.values()); // [ 'John', 'Sally', 'Jane' ]
 
 - Docs: https://jg-rp.github.io/json-p3/
 - Install: https://jg-rp.github.io/json-p3/#install
+- JSONPath playground: https://jg-rp.github.io/json-p3/playground
 - JSONPath syntax: https://jg-rp.github.io/json-p3/guides/jsonpath-syntax
 - API reference: https://jg-rp.github.io/json-p3/api
 - Change log: https://github.com/jg-rp/json-p3/blob/main/CHANGELOG.md

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export declare const version = "__VERSION__";
 export * as jsonpath from "./path";
-export { DEFAULT_ENVIRONMENT, FunctionExpressionType, JSONPath, JSONPathEnvironment, JSONPathError, JSONPathIndexError, JSONPathLexerError, JSONPathNode, JSONPathNodeList, JSONPathSyntaxError, JSONPathTypeError, JSONPathRecursionLimitError, Token, TokenKind, Nothing, query, compile, } from "./path";
+export { DEFAULT_ENVIRONMENT, FunctionExpressionType, JSONPath, JSONPathEnvironment, JSONPathError, JSONPathIndexError, JSONPathLexerError, JSONPathNode, JSONPathNodeList, JSONPathSyntaxError, JSONPathTypeError, JSONPathRecursionLimitError, Token, TokenKind, Nothing, lazyQuery, query, compile, } from "./path";
 export type { JSONPathEnvironmentOptions, FilterFunction } from "./path";
 export * as jsonpointer from "./pointer";
 export { JSONPointer, RelativeJSONPointer, resolve, UNDEFINED, } from "./pointer";

package/dist/json-p3.cjs.js

@@ -1,5 +1,5 @@
 /*
- * json-p3 version 0.2.0
+ * json-p3 version 0.3.0
  * https://github.com/jg-rp/json-p3
  * 
  * MIT License
@@ -645,10 +645,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_.
@@ -658,9 +654,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("")
+    );
   }
 
   /**
@@ -912,7 +911,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)}`;
@@ -920,7 +919,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();
@@ -1722,6 +1721,10 @@ class JSONPathSelector {
     this.token = token;
   }
 
+  /**
+   * @param nodes - Nodes matched by preceding selectors.
+   */
+
   /**
    * @param nodes - Nodes matched by preceding selectors.
    */
@@ -1749,7 +1752,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}'`;
@@ -1779,7 +1789,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);
@@ -1807,7 +1827,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 : "";
@@ -1890,22 +1918,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;
@@ -1913,19 +2011,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 {
@@ -1966,7 +2070,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()}`;
@@ -1983,10 +2120,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(", ")}]`;
@@ -2025,10 +2171,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;
   }
 
@@ -2041,7 +2200,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;
   }
 
   /**
@@ -2061,13 +2223,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;
@@ -2084,30 +2250,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);
@@ -2228,7 +2405,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();
@@ -2350,7 +2527,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 {
   /**
@@ -2383,8 +2563,7 @@ class JSONPathEnvironment {
    */
   functionRegister = new Map();
   /**
-   *
-   * @param options -
+   * @param options - Environment configuration options.
    */
   constructor() {
     let options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
@@ -2397,9 +2576,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))));
@@ -2407,14 +2585,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_.
@@ -2427,6 +2619,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());
@@ -2436,9 +2633,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) {
@@ -2505,6 +2711,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.
@@ -2554,6 +2781,7 @@ var index$1 = /*#__PURE__*/Object.freeze({
   compile: compile,
   expressions: expression,
   functions: index$2,
+  lazyQuery: lazyQuery,
   match: match,
   query: query,
   selectors: selectors
@@ -3039,7 +3267,7 @@ var index = /*#__PURE__*/Object.freeze({
   apply: apply
 });
 
-const version = "0.2.0";
+const version = "0.3.0";
 
 exports.DEFAULT_ENVIRONMENT = DEFAULT_ENVIRONMENT;
 exports.FunctionExpressionType = FunctionExpressionType;
@@ -3067,6 +3295,7 @@ exports.compile = compile;
 exports.jsonpatch = index;
 exports.jsonpath = index$1;
 exports.jsonpointer = index$3;
+exports.lazyQuery = lazyQuery;
 exports.query = query;
 exports.resolve = resolve;
 exports.version = version;