json-p3 0.1.1 → 0.2.0

package/dist/json-p3.cjs.js

@@ -1,5 +1,5 @@
 /*
- * json-p3 version 0.1.1
+ * json-p3 version 0.2.0
  * https://github.com/jg-rp/json-p3
  * 
  * MIT License
@@ -124,6 +124,20 @@ class JSONPathSyntaxError extends JSONPathError {
   }
 }
 
+/**
+ * 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.
  */
@@ -232,6 +246,10 @@ class JSONPointerError extends Error {
     this.name = "JSONPointerError";
   }
 }
+
+/**
+ * Base class for JSON Pointer resolution errors.
+ */
 class JSONPointerResolutionError extends JSONPointerError {
   constructor(message) {
     super(message);
@@ -240,6 +258,10 @@ class JSONPointerResolutionError extends JSONPointerError {
     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);
@@ -248,6 +270,10 @@ class JSONPointerIndexError extends JSONPointerResolutionError {
     this.name = "JSONPointerIndexError";
   }
 }
+
+/**
+ * Error thrown due to a missing property when resolving a JSON Pointer.
+ */
 class JSONPointerKeyError extends JSONPointerResolutionError {
   constructor(message) {
     super(message);
@@ -256,6 +282,10 @@ class JSONPointerKeyError extends JSONPointerResolutionError {
     this.name = "JSONPointerKeyError";
   }
 }
+
+/**
+ * Error thrown due to invalid JSON Pointer syntax.
+ */
 class JSONPointerSyntaxError extends JSONPointerError {
   constructor(message) {
     super(message);
@@ -264,6 +294,10 @@ class JSONPointerSyntaxError extends JSONPointerError {
     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);
@@ -323,8 +357,6 @@ class JSONPointer {
     }
   }
 
-  // TODO: add `resolveWithFallback` to handle explicit `undefined`
-
   /**
    *
    * @param value -
@@ -363,6 +395,8 @@ class JSONPointer {
     }
     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`.
@@ -372,12 +406,23 @@ class JSONPointer {
     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))}'`);
       }
@@ -452,8 +497,111 @@ class JSONPointer {
     }
     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");
+    }
+
+    // steps to move
+    const origin = this.parseInt(match.groups.ORIGIN);
 
-  // TODO: to (relative pointer)
+    // 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);
+    }
+  }
 }
 
 /**
@@ -488,6 +636,7 @@ var index$3 = /*#__PURE__*/Object.freeze({
   JSONPointerResolutionError: JSONPointerResolutionError,
   JSONPointerSyntaxError: JSONPointerSyntaxError,
   JSONPointerTypeError: JSONPointerTypeError,
+  RelativeJSONPointer: RelativeJSONPointer,
   UNDEFINED: UNDEFINED,
   resolve: resolve
 });
@@ -785,7 +934,7 @@ class FunctionExtension extends FilterExpression {
     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);
     }
@@ -805,13 +954,6 @@ function isTruthy(value) {
   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 "==":
@@ -865,7 +1007,8 @@ var expression = /*#__PURE__*/Object.freeze({
   PrefixExpression: PrefixExpression,
   RelativeQuery: RelativeQuery,
   RootQuery: RootQuery,
-  StringLiteral: StringLiteral
+  StringLiteral: StringLiteral,
+  compare: compare
 });
 
 class Count {
@@ -1389,6 +1532,10 @@ function lexInsideFilter(l) {
       case "":
       case "]":
         l.filterLevel -= 1;
+        if (l.parenStack.length === 1) {
+          l.error("unbalanced parentheses");
+          return null;
+        }
         l.backup();
         return lexInsideBracketedSelection;
       case ",":
@@ -1618,7 +1765,7 @@ class IndexSelector extends JSONPathSelector {
     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);
     }
   }
@@ -1673,15 +1820,11 @@ class SliceSelector extends JSONPathSelector {
       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) {
@@ -1765,17 +1908,21 @@ class RecursiveDescentSegment extends JSONPathSelector {
     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);
@@ -1885,6 +2032,18 @@ class JSONPath {
     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);
+  }
+
   /**
    *
    */
@@ -2046,7 +2205,7 @@ class Parser {
     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);
       }
@@ -2116,7 +2275,16 @@ class Parser {
       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);
@@ -2124,6 +2292,7 @@ class Parser {
       }
       stream.next();
     }
+    stream.expect(TokenKind.RPAREN);
     return new FunctionExtension(tok, tok.value, this.environment.checkWellTypedness(tok, args));
   }
   parseFilterExpression(stream) {
@@ -2168,7 +2337,7 @@ class Parser {
   }
   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);
     }
@@ -2176,30 +2345,53 @@ class Parser {
 }
 
 /**
- *
+ * 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.
    */
-  filterRegister = new Map();
+
+  /**
+   * 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.
+   */
+  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();
   }
@@ -2222,12 +2414,25 @@ class JSONPathEnvironment {
   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());
   }
 
   /**
@@ -2237,7 +2442,7 @@ class JSONPathEnvironment {
    */
   // 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);
     }
@@ -2251,17 +2456,17 @@ class JSONPathEnvironment {
     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);
           }
       }
@@ -2316,6 +2521,19 @@ function compile(path) {
   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,
@@ -2327,6 +2545,7 @@ var index$1 = /*#__PURE__*/Object.freeze({
   JSONPathLexerError: JSONPathLexerError,
   JSONPathNode: JSONPathNode,
   JSONPathNodeList: JSONPathNodeList,
+  JSONPathRecursionLimitError: JSONPathRecursionLimitError,
   JSONPathSyntaxError: JSONPathSyntaxError,
   JSONPathTypeError: JSONPathTypeError,
   Nothing: Nothing,
@@ -2335,6 +2554,7 @@ var index$1 = /*#__PURE__*/Object.freeze({
   compile: compile,
   expressions: expression,
   functions: index$2,
+  match: match,
   query: query,
   selectors: selectors
 });
@@ -2635,6 +2855,15 @@ class JSONPatch {
     }
   }
 
+  /**
+   * @returns an iterator over ops in this patch.
+   */
+  *[Symbol.iterator]() {
+    for (const op of this.ops) {
+      yield op.toObject();
+    }
+  }
+
   /**
    *
    * @param path -
@@ -2810,8 +3039,9 @@ var index = /*#__PURE__*/Object.freeze({
   apply: apply
 });
 
-const version = "0.1.1";
+const version = "0.2.0";
 
+exports.DEFAULT_ENVIRONMENT = DEFAULT_ENVIRONMENT;
 exports.FunctionExpressionType = FunctionExpressionType;
 exports.JSONPatch = JSONPatch;
 exports.JSONPatchError = JSONPatchError;
@@ -2823,10 +3053,12 @@ exports.JSONPathIndexError = JSONPathIndexError;
 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;