json-p3 0.1.0 → 0.2.0

package/dist/json-p3.iife.js

@@ -1,5 +1,5 @@
 /*
- * json-p3 version 0.1.0
+ * json-p3 version 0.2.0
  * https://github.com/jg-rp/json-p3
  * 
  * MIT License
@@ -125,6 +125,20 @@ var json_p3 = (function (exports) {
     }
   }
 
+  /**
+   * Error thrown when the maximum recursion depth is reached.
+   */
+  class JSONPathRecursionLimitError extends JSONPathError {
+    constructor(message, token) {
+      super(message, token);
+      this.message = message;
+      this.token = token;
+      Object.setPrototypeOf(this, new.target.prototype);
+      this.name = "JSONPathRecursionLimitError";
+      this.message = withErrorContext(message, token);
+    }
+  }
+
   /**
    * Common types and type predicates.
    */
@@ -233,6 +247,10 @@ var json_p3 = (function (exports) {
       this.name = "JSONPointerError";
     }
   }
+
+  /**
+   * Base class for JSON Pointer resolution errors.
+   */
   class JSONPointerResolutionError extends JSONPointerError {
     constructor(message) {
       super(message);
@@ -241,6 +259,10 @@ var json_p3 = (function (exports) {
       this.name = "JSONPointerResolutionError";
     }
   }
+
+  /**
+   * Error thrown due to an out of range index when resolving a JSON Pointer.
+   */
   class JSONPointerIndexError extends JSONPointerResolutionError {
     constructor(message) {
       super(message);
@@ -249,6 +271,10 @@ var json_p3 = (function (exports) {
       this.name = "JSONPointerIndexError";
     }
   }
+
+  /**
+   * Error thrown due to a missing property when resolving a JSON Pointer.
+   */
   class JSONPointerKeyError extends JSONPointerResolutionError {
     constructor(message) {
       super(message);
@@ -257,6 +283,10 @@ var json_p3 = (function (exports) {
       this.name = "JSONPointerKeyError";
     }
   }
+
+  /**
+   * Error thrown due to invalid JSON Pointer syntax.
+   */
   class JSONPointerSyntaxError extends JSONPointerError {
     constructor(message) {
       super(message);
@@ -265,6 +295,10 @@ var json_p3 = (function (exports) {
       this.name = "JSONPointerSyntaxError";
     }
   }
+
+  /**
+   * Error thrown when trying to resolve a property or index against a primitive value.
+   */
   class JSONPointerTypeError extends JSONPointerResolutionError {
     constructor(message) {
       super(message);
@@ -324,8 +358,6 @@ var json_p3 = (function (exports) {
       }
     }
 
-    // TODO: add `resolveWithFallback` to handle explicit `undefined`
-
     /**
      *
      * @param value -
@@ -364,6 +396,8 @@ var json_p3 = (function (exports) {
       }
       return pointer.split("/").map(token => token.replaceAll("~1", "/").replaceAll("~0", "~")).slice(1);
     }
+
+    // eslint-disable-next-line sonarjs/cognitive-complexity
     getItem(val, token, idx) {
       // NOTE:
       //   - string primitives "have own" indices and `length`.
@@ -373,12 +407,23 @@ var json_p3 = (function (exports) {
       if (isArray(val)) {
         if (token !== "length" && Object.hasOwn(val, token)) {
           return val[Number(token)];
+        } else if (token.startsWith("#")) {
+          // handle non-standard '#' from relative json pointer
+          const maybeIndex = token.slice(1);
+          if (RE_INT.test(maybeIndex) && Object.hasOwn(val, maybeIndex)) {
+            return Number(maybeIndex);
+          } else {
+            throw new JSONPointerIndexError(`index out of range '${JSONPointer.encode(this.tokens.slice(0, idx + 1))}'`);
+          }
         } else {
           throw new JSONPointerIndexError(`index out of range '${JSONPointer.encode(this.tokens.slice(0, idx + 1))}'`);
         }
       } else if (isObject(val)) {
         if (Object.hasOwn(val, token)) {
           return val[token];
+        } else if (token.startsWith("#") && Object.hasOwn(val, token.slice(1))) {
+          // handle non-standard '#' from relative json pointer
+          return token.slice(1);
         } else {
           throw new JSONPointerKeyError(`no such property '${JSONPointer.encode(this.tokens.slice(0, idx + 1))}'`);
         }
@@ -398,10 +443,12 @@ var json_p3 = (function (exports) {
 
     /**
      * Join this pointer with _tokens_.
+     *
      * @param tokens - JSON Pointer strings, possibly without leading slashes.
      * If a token or "part" does have a leading slash, the previous pointer is
      * ignored and a new `JSONPointer` is created, then processing of the
      * remaining tokens continues.
+     *
      * @returns A new JSON Pointer that is the concatenation of all tokens or
      * "parts".
      */
@@ -451,8 +498,111 @@ var json_p3 = (function (exports) {
       }
       return new JSONPointer(JSONPointer.encode(this.tokens.slice(0, this.tokens.length - 1)));
     }
+    to(rel) {
+      const relativePointer = isString(rel) ? new RelativeJSONPointer(rel) : rel;
+      return relativePointer.to(this);
+    }
+  }
+  const RE_RELATIVE_POINTER = /(?<ORIGIN>\d+)(?<INDEX_G>(?<SIGN>[+-])(?<INDEX>\d))?(?<POINTER>.*)/s;
+  const RE_INT = /(0|[1-9][0-9]*)/;
+
+  /**
+   * A relative JSON Pointer.
+   *
+   * See https://www.ietf.org/id/draft-hha-relative-json-pointer-00.html
+   */
+  class RelativeJSONPointer {
+    /**
+     *
+     * @param rel -
+     */
+    constructor(rel) {
+      [this.origin, this.index, this.pointer] = this.parse(rel);
+    }
+
+    /**
+     *
+     * @returns
+     */
+    toString() {
+      const sign = this.index > 0 ? "+" : "";
+      const index = this.index === 0 ? "" : `${sign}${this.index}`;
+      return `${this.origin}${index}${this.pointer}`;
+    }
+
+    /**
+     *
+     * @param pointer -
+     */
+    to(pointer) {
+      const p = isString(pointer) ? new JSONPointer(pointer) : pointer;
+
+      // move to origin
+      if (this.origin > p.tokens.length) {
+        throw new JSONPointerIndexError(`origin (${this.origin}) exceeds root (${p.tokens.length})`);
+      }
+      const tokens = this.origin < 1 ? p.tokens.slice() : p.tokens.slice(0, -this.origin);
+
+      // array index offset
+      if (this.index && tokens.length && this.isIntLike(tokens.at(-1))) {
+        const newIndex = Number(tokens.at(-1)) + this.index;
+        if (newIndex < 0) {
+          throw new JSONPointerIndexError(`index offset out of range (${newIndex})`);
+        }
+        tokens[tokens.length - 1] = String(newIndex);
+      }
+
+      // pointer or index/property
+      if (this.pointer instanceof JSONPointer) {
+        tokens.push(...this.pointer.tokens);
+      } else {
+        tokens[tokens.length - 1] = `#${tokens[tokens.length - 1]}`;
+      }
+      return new JSONPointer(JSONPointer.encode(tokens));
+    }
+    parse(rel) {
+      const match = RE_RELATIVE_POINTER.exec(rel);
+      if (!match || !match.groups) {
+        throw new JSONPointerSyntaxError("failed to parse relative pointer");
+      }
 
-    // TODO: to (relative pointer)
+      // steps to move
+      const origin = this.parseInt(match.groups.ORIGIN);
+
+      // optional index manipulation
+      let index = 0;
+      if (match.groups["INDEX_G"]) {
+        index = this.parseInt(match.groups.INDEX);
+        if (index === 0) {
+          throw new JSONPointerSyntaxError("index offset can't be zero");
+        }
+        if (match.groups.SIGN === "-") {
+          index = -index;
+        }
+      }
+
+      // pointer or '#'. an empty string is OK.
+      if (match.groups.POINTER === "#") {
+        return [origin, index, "#"];
+      }
+      return [origin, index, new JSONPointer(match.groups.POINTER)];
+    }
+    parseInt(s) {
+      if (s.startsWith("0") && s.length > 1) {
+        throw new JSONPointerSyntaxError("unexpected leading zero");
+      }
+      if (RE_INT.test(s)) {
+        return Number(s);
+      }
+      throw new JSONPointerSyntaxError(`expected an integer, found '${s}'`);
+    }
+    isIntLike(value) {
+      if (value === undefined || isNumber(value)) {
+        return true;
+      } else {
+        return RE_INT.test(value);
+      }
+    }
   }
 
   /**
@@ -487,6 +637,7 @@ var json_p3 = (function (exports) {
     JSONPointerResolutionError: JSONPointerResolutionError,
     JSONPointerSyntaxError: JSONPointerSyntaxError,
     JSONPointerTypeError: JSONPointerTypeError,
+    RelativeJSONPointer: RelativeJSONPointer,
     UNDEFINED: UNDEFINED,
     resolve: resolve
   });
@@ -784,7 +935,7 @@ var json_p3 = (function (exports) {
       this.args = args;
     }
     evaluate(context) {
-      const func = context.environment.filterRegister.get(this.name);
+      const func = context.environment.functionRegister.get(this.name);
       if (!func) {
         throw new UndefinedFilterFunctionError(`filter function '${this.name}' is undefined`, this.token);
       }
@@ -804,13 +955,6 @@ var json_p3 = (function (exports) {
     if (value instanceof JSONPathNodeList && value.empty()) return false;
     return !(typeof value === "boolean" && value === false);
   }
-
-  /**
-   *
-   * @param left -
-   * @param operator -
-   * @param right -
-   */
   function compare(left, operator, right) {
     switch (operator) {
       case "==":
@@ -864,7 +1008,8 @@ var json_p3 = (function (exports) {
     PrefixExpression: PrefixExpression,
     RelativeQuery: RelativeQuery,
     RootQuery: RootQuery,
-    StringLiteral: StringLiteral
+    StringLiteral: StringLiteral,
+    compare: compare
   });
 
   class Count {
@@ -1095,7 +1240,7 @@ var json_p3 = (function (exports) {
 
   // These regular expressions are to be used with Lexer.acceptMatchRun(),
   // which expects the sticky flag to be set.
-  const exponentPattern = /e[+-]\d+/y;
+  const exponentPattern = /e[+-]?\d+/y;
   const functionNamePattern = /[a-z][a-z_0-9]*/y;
   const indexPattern = /-?\d+/y;
   const intPattern = /-?[0-9]+/y;
@@ -1388,6 +1533,10 @@ var json_p3 = (function (exports) {
         case "":
         case "]":
           l.filterLevel -= 1;
+          if (l.parenStack.length === 1) {
+            l.error("unbalanced parentheses");
+            return null;
+          }
           l.backup();
           return lexInsideBracketedSelection;
         case ",":
@@ -1617,7 +1766,7 @@ var json_p3 = (function (exports) {
       this.environment = environment;
       this.token = token;
       this.index = index;
-      if (index < this.environment.options.minIntIndex || index > this.environment.options.maxIntIndex) {
+      if (index < this.environment.minIntIndex || index > this.environment.maxIntIndex) {
         throw new JSONPathIndexError("index out of range", this.token);
       }
     }
@@ -1672,15 +1821,11 @@ var json_p3 = (function (exports) {
         indices[_key] = arguments[_key];
       }
       for (const index of indices) {
-        if (index !== undefined && (index < this.environment.options.minIntIndex || index > this.environment.options.maxIntIndex)) {
+        if (index !== undefined && (index < this.environment.minIntIndex || index > this.environment.maxIntIndex)) {
           throw new JSONPathIndexError("index out of range", this.token);
         }
       }
     }
-    normalizedIndex(length, index) {
-      if (index < 0 && length >= Math.abs(index)) return Math.min(length + index, length - 1);
-      return Math.min(index, length - 1);
-    }
 
     // eslint-disable-next-line sonarjs/cognitive-complexity
     slice(arr, start, stop, step) {
@@ -1764,17 +1909,21 @@ var json_p3 = (function (exports) {
       return "..";
     }
     visit(node) {
+      let depth = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 1;
+      if (depth >= this.environment.maxRecursionDepth) {
+        throw new JSONPathRecursionLimitError("recursion limit reached", this.token);
+      }
       const rv = [];
       if (node.value instanceof String) return new JSONPathNodeList(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));
+          rv.push(_node, ...this.visit(_node, depth + 1));
         }
       } 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));
+          rv.push(_node, ...this.visit(_node, depth + 1));
         }
       }
       return new JSONPathNodeList(rv);
@@ -1884,6 +2033,18 @@ var json_p3 = (function (exports) {
       return nodes;
     }
 
+    /**
+     * Return a {@link JSONPathNode} instance for the first object found in
+     * _value_ matching this query.
+     *
+     * @param value - JSON-like data to which this query will be applied.
+     * @returns The first node in _value_ matching this query, or `undefined` if
+     * there are no matches.
+     */
+    match(value) {
+      return this.query(value).nodes.at(0);
+    }
+
     /**
      *
      */
@@ -2045,7 +2206,7 @@ var json_p3 = (function (exports) {
       const tok = stream.next();
       const expr = this.parseFilterExpression(stream);
       if (expr instanceof FunctionExtension) {
-        const func = this.environment.filterRegister.get(expr.name);
+        const func = this.environment.functionRegister.get(expr.name);
         if (func && func.returnType === FunctionExpressionType.ValueType) {
           throw new JSONPathTypeError(`result of ${expr.name}()  must be compared`, expr.token);
         }
@@ -2115,7 +2276,16 @@ var json_p3 = (function (exports) {
         if (!func) {
           throw new JSONPathSyntaxError(`unexpected '${stream.current.value}'`, stream.current);
         }
-        args.push(func.bind(this)(stream));
+        let expr = func.bind(this)(stream);
+
+        // Could be a comparison/logical expression
+        let peekKind = stream.peek.kind;
+        while (BINARY_OPERATORS.has(peekKind)) {
+          stream.next();
+          expr = this.parseInfixExpression(stream, expr);
+          peekKind = stream.peek.kind;
+        }
+        args.push(expr);
         if (stream.peek.kind !== TokenKind.RPAREN) {
           if (stream.peek.kind === TokenKind.RBRACKET) break;
           stream.expectPeek(TokenKind.COMMA);
@@ -2123,6 +2293,7 @@ var json_p3 = (function (exports) {
         }
         stream.next();
       }
+      stream.expect(TokenKind.RPAREN);
       return new FunctionExtension(tok, tok.value, this.environment.checkWellTypedness(tok, args));
     }
     parseFilterExpression(stream) {
@@ -2167,7 +2338,7 @@ var json_p3 = (function (exports) {
     }
     throwForNonComparableFunction(expr) {
       if (!(expr instanceof FunctionExtension)) return;
-      const func = this.environment.filterRegister.get(expr.name);
+      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);
       }
@@ -2175,30 +2346,53 @@ var json_p3 = (function (exports) {
   }
 
   /**
-   *
+   * JSONPath environment options. The defaults are in compliance with JSONPath
+   * standards.
    */
 
-  const defaultOptions = {
-    strict: true,
-    maxIntIndex: Math.pow(2, 53) - 1,
-    minIntIndex: -Math.pow(2, 53) - 1
-  };
-
   /**
    *
    */
   class JSONPathEnvironment {
     /**
+     * Indicates if the environment should to be strict about its compliance with
+     * JSONPath standards.
      *
+     * Defaults to `true`. Setting `strict` to `false` currently has no effect.
+     * If/when we add non-standard features, the environment's strictness will
+     * control their availability.
+     */
+
+    /**
+     * The maximum number allowed when indexing or slicing an array. Defaults to
+     * 2**53 -1.
+     */
+
+    /**
+     * The minimum number allowed when indexing or slicing an array. Defaults to
+     * -(2**53) -1.
+     */
+
+    /**
+     * The maximum number of objects and/or arrays the recursive descent selector
+     * can visit before a `JSONPathRecursionLimitError` is thrown.
+     */
+
+    /**
+     * A map of function names to objects implementing the {@link FilterFunction}
+     * interface. You are free to set or delete custom filter functions directly.
      */
-    filterRegister = new Map();
+    functionRegister = new Map();
     /**
      *
      * @param options -
      */
     constructor() {
-      let options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : defaultOptions;
-      this.options = options;
+      let options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+      this.strict = options.strict ?? true;
+      this.maxIntIndex = options.maxIntIndex ?? Math.pow(2, 53) - 1;
+      this.minIntIndex = options.maxIntIndex ?? -Math.pow(2, 53) - 1;
+      this.maxRecursionDepth = options.maxRecursionDepth ?? 50;
       this.parser = new Parser(this);
       this.setupFilterFunctions();
     }
@@ -2221,12 +2415,25 @@ var json_p3 = (function (exports) {
     query(path, value) {
       return this.compile(path).query(value);
     }
+
+    /**
+     * Return a {@link JSONPathNode} instance for the first object found in
+     * _value_ matching _path_.
+     *
+     * @param path - A JSONPath query.
+     * @param value - JSON-like data to which the query _path_ will be applied.
+     * @returns The first node in _value_ matching  _path_, or `undefined` if
+     * there are no matches.
+     */
+    match(path, value) {
+      return this.compile(path).match(value);
+    }
     setupFilterFunctions() {
-      this.filterRegister.set("count", new Count());
-      this.filterRegister.set("length", new Length());
-      this.filterRegister.set("search", new Search());
-      this.filterRegister.set("match", new Match());
-      this.filterRegister.set("value", new Value());
+      this.functionRegister.set("count", new Count());
+      this.functionRegister.set("length", new Length());
+      this.functionRegister.set("search", new Search());
+      this.functionRegister.set("match", new Match());
+      this.functionRegister.set("value", new Value());
     }
 
     /**
@@ -2236,7 +2443,7 @@ var json_p3 = (function (exports) {
      */
     // eslint-disable-next-line sonarjs/cognitive-complexity
     checkWellTypedness(token, args) {
-      const func = this.filterRegister.get(token.value);
+      const func = this.functionRegister.get(token.value);
       if (!func) {
         throw new UndefinedFilterFunctionError(`no such function '${token.value}'`, token);
       }
@@ -2250,17 +2457,17 @@ var json_p3 = (function (exports) {
       for (const [typ, arg, idx] of func.argTypes.map((t, i) => [t, args[i], i])) {
         switch (typ) {
           case FunctionExpressionType.ValueType:
-            if (!(arg instanceof FilterExpressionLiteral || arg instanceof JSONPathQuery && arg.path.singularQuery())) {
+            if (!(arg instanceof FilterExpressionLiteral || arg instanceof JSONPathQuery && arg.path.singularQuery() || arg instanceof FunctionExtension && this.functionRegister.get(arg.name)?.returnType === FunctionExpressionType.ValueType)) {
               throw new JSONPathTypeError(`${token.value}() argument ${idx} must be of ValueType`, arg.token);
             }
             break;
           case FunctionExpressionType.LogicalType:
-            if (!(arg instanceof BooleanLiteral)) {
+            if (!(arg instanceof JSONPathQuery || arg instanceof InfixExpression)) {
               throw new JSONPathTypeError(`${token.value}() argument ${idx} must be of LogicalType`, arg.token);
             }
             break;
           case FunctionExpressionType.NodesType:
-            if (!(arg instanceof JSONPathQuery)) {
+            if (!(arg instanceof JSONPathQuery || arg instanceof FunctionExtension && this.functionRegister.get(arg.name)?.returnType === FunctionExpressionType.NodesType)) {
               throw new JSONPathTypeError(`${token.value}() argument ${idx} must be of NodesType`, arg.token);
             }
         }
@@ -2315,6 +2522,19 @@ var json_p3 = (function (exports) {
     return DEFAULT_ENVIRONMENT.compile(path);
   }
 
+  /**
+   * Return a {@link JSONPathNode} instance for the first object found in
+   * _value_ matching _path_.
+   *
+   * @param path - A JSONPath query.
+   * @param value - JSON-like data to which the query _path_ will be applied.
+   * @returns The first node in _value_ matching  _path_, or `undefined` if
+   * there are no matches.
+   */
+  function match(path, value) {
+    return DEFAULT_ENVIRONMENT.match(path, value);
+  }
+
   var index$1 = /*#__PURE__*/Object.freeze({
     __proto__: null,
     DEFAULT_ENVIRONMENT: DEFAULT_ENVIRONMENT,
@@ -2326,6 +2546,7 @@ var json_p3 = (function (exports) {
     JSONPathLexerError: JSONPathLexerError,
     JSONPathNode: JSONPathNode,
     JSONPathNodeList: JSONPathNodeList,
+    JSONPathRecursionLimitError: JSONPathRecursionLimitError,
     JSONPathSyntaxError: JSONPathSyntaxError,
     JSONPathTypeError: JSONPathTypeError,
     Nothing: Nothing,
@@ -2334,6 +2555,7 @@ var json_p3 = (function (exports) {
     compile: compile,
     expressions: expression,
     functions: index$2,
+    match: match,
     query: query,
     selectors: selectors
   });
@@ -2634,6 +2856,15 @@ var json_p3 = (function (exports) {
       }
     }
 
+    /**
+     * @returns an iterator over ops in this patch.
+     */
+    *[Symbol.iterator]() {
+      for (const op of this.ops) {
+        yield op.toObject();
+      }
+    }
+
     /**
      *
      * @param path -
@@ -2809,8 +3040,9 @@ var json_p3 = (function (exports) {
     apply: apply
   });
 
-  const version = "0.1.0";
+  const version = "0.2.0";
 
+  exports.DEFAULT_ENVIRONMENT = DEFAULT_ENVIRONMENT;
   exports.FunctionExpressionType = FunctionExpressionType;
   exports.JSONPatch = JSONPatch;
   exports.JSONPatchError = JSONPatchError;
@@ -2822,10 +3054,12 @@ var json_p3 = (function (exports) {
   exports.JSONPathLexerError = JSONPathLexerError;
   exports.JSONPathNode = JSONPathNode;
   exports.JSONPathNodeList = JSONPathNodeList;
+  exports.JSONPathRecursionLimitError = JSONPathRecursionLimitError;
   exports.JSONPathSyntaxError = JSONPathSyntaxError;
   exports.JSONPathTypeError = JSONPathTypeError;
   exports.JSONPointer = JSONPointer;
   exports.Nothing = Nothing;
+  exports.RelativeJSONPointer = RelativeJSONPointer;
   exports.Token = Token;
   exports.TokenKind = TokenKind;
   exports.UNDEFINED = UNDEFINED;