json-p3 0.1.0 → 0.2.0

package/dist/json-p3.esm.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
@@ -122,6 +122,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.
  */
@@ -230,6 +244,10 @@ class JSONPointerError extends Error {
     this.name = "JSONPointerError";
   }
 }
+
+/**
+ * Base class for JSON Pointer resolution errors.
+ */
 class JSONPointerResolutionError extends JSONPointerError {
   constructor(message) {
     super(message);
@@ -238,6 +256,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);
@@ -246,6 +268,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);
@@ -254,6 +280,10 @@ class JSONPointerKeyError extends JSONPointerResolutionError {
     this.name = "JSONPointerKeyError";
   }
 }
+
+/**
+ * Error thrown due to invalid JSON Pointer syntax.
+ */
 class JSONPointerSyntaxError extends JSONPointerError {
   constructor(message) {
     super(message);
@@ -262,6 +292,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);
@@ -321,8 +355,6 @@ class JSONPointer {
     }
   }
 
-  // TODO: add `resolveWithFallback` to handle explicit `undefined`
-
   /**
    *
    * @param value -
@@ -361,6 +393,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`.
@@ -370,12 +404,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))}'`);
       }
@@ -395,10 +440,12 @@ class JSONPointer {
 
   /**
    * 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".
    */
@@ -448,8 +495,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");
+    }
 
-  // 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);
+    }
+  }
 }
 
 /**
@@ -484,6 +634,7 @@ var index$3 = /*#__PURE__*/Object.freeze({
   JSONPointerResolutionError: JSONPointerResolutionError,
   JSONPointerSyntaxError: JSONPointerSyntaxError,
   JSONPointerTypeError: JSONPointerTypeError,
+  RelativeJSONPointer: RelativeJSONPointer,
   UNDEFINED: UNDEFINED,
   resolve: resolve
 });
@@ -781,7 +932,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);
     }
@@ -801,13 +952,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 "==":
@@ -861,7 +1005,8 @@ var expression = /*#__PURE__*/Object.freeze({
   PrefixExpression: PrefixExpression,
   RelativeQuery: RelativeQuery,
   RootQuery: RootQuery,
-  StringLiteral: StringLiteral
+  StringLiteral: StringLiteral,
+  compare: compare
 });
 
 class Count {
@@ -1092,7 +1237,7 @@ class TokenStream {
 
 // 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;
@@ -1385,6 +1530,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 ",":
@@ -1614,7 +1763,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);
     }
   }
@@ -1669,15 +1818,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) {
@@ -1761,17 +1906,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);
@@ -1881,6 +2030,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);
+  }
+
   /**
    *
    */
@@ -2042,7 +2203,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);
       }
@@ -2112,7 +2273,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);
@@ -2120,6 +2290,7 @@ class Parser {
       }
       stream.next();
     }
+    stream.expect(TokenKind.RPAREN);
     return new FunctionExtension(tok, tok.value, this.environment.checkWellTypedness(tok, args));
   }
   parseFilterExpression(stream) {
@@ -2164,7 +2335,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);
     }
@@ -2172,30 +2343,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.
+   */
+
+  /**
+   * 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();
   }
@@ -2218,12 +2412,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());
   }
 
   /**
@@ -2233,7 +2440,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);
     }
@@ -2247,17 +2454,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);
           }
       }
@@ -2312,6 +2519,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,
@@ -2323,6 +2543,7 @@ var index$1 = /*#__PURE__*/Object.freeze({
   JSONPathLexerError: JSONPathLexerError,
   JSONPathNode: JSONPathNode,
   JSONPathNodeList: JSONPathNodeList,
+  JSONPathRecursionLimitError: JSONPathRecursionLimitError,
   JSONPathSyntaxError: JSONPathSyntaxError,
   JSONPathTypeError: JSONPathTypeError,
   Nothing: Nothing,
@@ -2331,6 +2552,7 @@ var index$1 = /*#__PURE__*/Object.freeze({
   compile: compile,
   expressions: expression,
   functions: index$2,
+  match: match,
   query: query,
   selectors: selectors
 });
@@ -2631,6 +2853,15 @@ class JSONPatch {
     }
   }
 
+  /**
+   * @returns an iterator over ops in this patch.
+   */
+  *[Symbol.iterator]() {
+    for (const op of this.ops) {
+      yield op.toObject();
+    }
+  }
+
   /**
    *
    * @param path -
@@ -2806,6 +3037,6 @@ var index = /*#__PURE__*/Object.freeze({
   apply: apply
 });
 
-const version = "0.1.0";
+const version = "0.2.0";
 
-export { FunctionExpressionType, JSONPatch, JSONPatchError, JSONPatchTestFailure, JSONPath, JSONPathEnvironment, JSONPathError, JSONPathIndexError, JSONPathLexerError, JSONPathNode, JSONPathNodeList, JSONPathSyntaxError, JSONPathTypeError, JSONPointer, Nothing, 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, query, resolve, version };