json-p3 2.0.0 → 2.1.0

package/dist/json-p3.esm.js

@@ -1,5 +1,5 @@
 /*
- * json-p3 version 2.0.0
+ * json-p3 version 2.1.0
  * https://github.com/jg-rp/json-p3
  * 
  * MIT License
@@ -651,6 +651,30 @@ var index$3 = /*#__PURE__*/Object.freeze({
   resolve: resolve
 });
 
+/**
+ * An identifier that is allowed in both JS and JSONPath.
+ * JSONPath identifiers are generally much more permissive than JS ones, but
+ * they don't allow the character "$", so we take the intersection of the two
+ * when deciding whether to use dot shorthand for canonical serialization of
+ * simple names.
+ */
+const SHORTHAND_COMPATIBLE_IDENTIFIER = /^[\p{ID_Start}_]\p{ID_Continue}*$/u;
+
+/** Usable in a quoted path. */
+function toQuoted(name) {
+  return name.includes("'") && !name.includes('"') ? JSON.stringify(name) : toCanonical(name);
+}
+
+/** Usable in a normalized path. */
+function toCanonical(name) {
+  return `'${JSON.stringify(name).slice(1, -1).replaceAll('\\"', '"').replaceAll("'", "\\'")}'`;
+}
+
+/** Usable in a shorthand path. */
+function toShorthand(name) {
+  return SHORTHAND_COMPATIBLE_IDENTIFIER.test(name) ? name : null;
+}
+
 const Nothing = Symbol.for("jsonpath.nothing");
 
 /**
@@ -658,7 +682,7 @@ const Nothing = Symbol.for("jsonpath.nothing");
  */
 
 /**
- * Object passed to FilterExpression.evaluate().
+ * Object passed to `FilterExpression.evaluate()`.
  */
 
 /**
@@ -669,6 +693,14 @@ function hasStringKey(value, key) {
 }
 const KEY_MARK = "\x02";
 
+/**
+ * Options for serializing paths.
+ */
+
+const defaultSerializationOptions = {
+  form: "pretty"
+};
+
 /**
  * The pair of a JSON value and its location found in the target JSON value.
  */
@@ -683,10 +715,31 @@ class JSONPathNode {
     this.location = location;
     this.root = root;
   }
+
+  /**
+   * @deprecated Use {@link getPath} with `options.form` set to `canonical` instead.
+   */
   get path() {
+    return this.getPath({
+      form: "canonical"
+    });
+  }
+
+  /**
+   * Get the path to this node in the target JSON value.
+   *
+   * Given that the path refers to the singular current node, the returned path
+   * will always be a normalized path if `options.form` is set to `canonical`,
+   * following section 2.7 of RFC 9535.
+   */
+  getPath(options) {
+    const opts = {
+      ...defaultSerializationOptions,
+      ...options
+    };
     return (
       // eslint-disable-next-line prefer-template
-      "$" + this.location.map(s => isString(s) ? this.decode_name_location(s) : `[${s}]`).join("")
+      "$" + this.location.map(s => isString(s) ? this.decodeNameLocation(s, opts) : `[${s}]`).join("")
     );
   }
 
@@ -699,8 +752,16 @@ class JSONPathNode {
     }
     return new JSONPointer(JSONPointer.encode(this.location.map(String)));
   }
-  decode_name_location(name) {
-    return name.startsWith(KEY_MARK) ? `[~'${name.slice(1).replaceAll("'", "\\'")}']` : `['${name.replaceAll("'", "\\'")}']`;
+  decodeNameLocation(name, options) {
+    const normalized = options.form === "canonical";
+    const serialize = normalized ? toCanonical : toQuoted;
+    const hasKeyMark = name.startsWith(KEY_MARK);
+    if (hasKeyMark) name = name.slice(1);
+    const shorthand = toShorthand(name);
+    if (hasKeyMark) {
+      return normalized || shorthand == null ? `[~${serialize(name)}]` : `.~${shorthand}`;
+    }
+    return normalized || shorthand == null ? `[${serialize(name)}]` : `.${shorthand}`;
   }
 }
 
@@ -761,8 +822,8 @@ class JSONPathNodeList {
    * A normalized path contains only property name and index selectors, and
    * always uses bracketed segments, never shorthand selectors.
    */
-  paths() {
-    return this.nodes.map(node => node.path);
+  paths(options) {
+    return this.nodes.map(node => node.getPath(options));
   }
 
   /**
@@ -834,7 +895,7 @@ class StringLiteral extends FilterExpressionLiteral {
     return this.value;
   }
   toString() {
-    return JSON.stringify(this.value);
+    return toCanonical(this.value);
   }
 }
 class NumberLiteral extends FilterExpressionLiteral {
@@ -865,10 +926,13 @@ class PrefixExpression extends FilterExpression {
     }
     throw new JSONPathTypeError(`unknown operator '${this.operator}'`, this.token);
   }
-  toString() {
-    return `${this.operator}${this.right.toString()}`;
+  toString(options) {
+    return `${this.operator}${this.right.toString(options)}`;
   }
 }
+const PRECEDENCE_LOGICAL_OR$1 = 4;
+const PRECEDENCE_LOGICAL_AND$1 = 5;
+const PRECEDENCE_PREFIX$1 = 7;
 class InfixExpression extends FilterExpression {
   constructor(token, left, operator, right) {
     super(token);
@@ -891,11 +955,12 @@ class InfixExpression extends FilterExpression {
     }
     return compare(left, this.operator, right);
   }
-  toString() {
+  toString(options) {
+    // Note that `LogicalExpression.toString()` does not call this.
     if (this.logical) {
-      return `(${this.left.toString()} ${this.operator} ${this.right.toString()})`;
+      return `(${this.left.toString(options)} ${this.operator} ${this.right.toString(options)})`;
     }
-    return `${this.left.toString()} ${this.operator} ${this.right.toString()}`;
+    return `${this.left.toString(options)} ${this.operator} ${this.right.toString(options)}`;
   }
 }
 class LogicalExpression extends FilterExpression {
@@ -909,8 +974,38 @@ class LogicalExpression extends FilterExpression {
     if (value instanceof JSONPathNodeList) return value.nodes.length > 0; // existence
     return isTruthy(value);
   }
-  toString() {
-    return this.expression.toString();
+  toString(options) {
+    // Minimize parentheses in logical expressions.
+    function _toString(expression, parentPrecedence) {
+      if (expression instanceof InfixExpression) {
+        let precedence;
+        let op;
+        let left;
+        let right;
+        if (expression.operator === "&&") {
+          precedence = PRECEDENCE_LOGICAL_AND$1;
+          op = "&&";
+          left = _toString(expression.left, precedence);
+          right = _toString(expression.right, precedence);
+        } else if (expression.operator === "||") {
+          precedence = PRECEDENCE_LOGICAL_OR$1;
+          op = "||";
+          left = _toString(expression.left, precedence);
+          right = _toString(expression.right, precedence);
+        } else {
+          return expression.toString(options);
+        }
+        const expr = `${left} ${op} ${right}`;
+        return precedence < parentPrecedence ? `(${expr})` : expr;
+      }
+      if (expression instanceof PrefixExpression) {
+        const operand = _toString(expression.right, PRECEDENCE_PREFIX$1);
+        const expr = `!${operand}`;
+        return parentPrecedence > PRECEDENCE_PREFIX$1 ? `(${expr})` : expr;
+      }
+      return expression.toString(options);
+    }
+    return _toString(this.expression, 0);
   }
 }
 
@@ -928,16 +1023,16 @@ class RelativeQuery extends FilterQuery {
   evaluate(context) {
     return context.lazy ? new JSONPathNodeList(Array.from(this.path.lazyQuery(context.currentValue))) : this.path.query(context.currentValue);
   }
-  toString() {
-    return `@${this.path.toString().slice(1)}`;
+  toString(options) {
+    return `@${this.path.toString(options).slice(1)}`;
   }
 }
 class RootQuery extends FilterQuery {
   evaluate(context) {
     return context.lazy ? new JSONPathNodeList(Array.from(this.path.lazyQuery(context.rootValue))) : this.path.query(context.rootValue);
   }
-  toString() {
-    return this.path.toString();
+  toString(options) {
+    return this.path.toString(options);
   }
 }
 class FunctionExtension extends FilterExpression {
@@ -955,8 +1050,8 @@ class FunctionExtension extends FilterExpression {
     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(", ")})`;
+  toString(options) {
+    return `${this.name}(${this.args.map(e => e.toString(options)).join(", ")})`;
   }
   unpack_node_list(arg) {
     switch (arg.length) {
@@ -3163,8 +3258,17 @@ class NameSelector extends JSONPathSelector {
       yield new JSONPathNode(node.value[this.name], node.location.concat(this.name), node.root);
     }
   }
-  toString() {
-    return `'${this.name}'`;
+  toString(options) {
+    const {
+      form
+    } = {
+      ...defaultSerializationOptions,
+      ...options
+    };
+    return form === "canonical" ? toCanonical(this.name) : toQuoted(this.name);
+  }
+  shorthand() {
+    return toShorthand(this.name);
   }
 }
 
@@ -3433,8 +3537,8 @@ class FilterSelector extends JSONPathSelector {
       }
     }
   }
-  toString() {
-    return `?${this.expression.toString()}`;
+  toString(options) {
+    return `?${this.expression.toString(options)}`;
   }
 }
 
@@ -3465,7 +3569,7 @@ class JSONPathSegment {
    */
 
   /**
-   * Return a canonical string representation of this segment.
+   * Return a string representation of this segment.
    */
 }
 
@@ -3487,8 +3591,18 @@ class ChildSegment extends JSONPathSegment {
       }
     }
   }
-  toString() {
-    return `[${this.selectors.map(s => s.toString()).join(", ")}]`;
+  toString(options) {
+    const {
+      form
+    } = {
+      ...defaultSerializationOptions,
+      ...options
+    };
+    if (form === "pretty" && this.selectors.length === 1 && this.selectors[0] instanceof NameSelector) {
+      const shorthand = this.selectors[0].shorthand();
+      if (shorthand != null) return `.${shorthand}`;
+    }
+    return `[${this.selectors.map(s => s.toString(options)).join(", ")}]`;
   }
 }
 
@@ -3515,8 +3629,8 @@ class DescendantSegment extends JSONPathSegment {
       }
     }
   }
-  toString() {
-    return `..[${this.selectors.map(s => s.toString()).join(", ")}]`;
+  toString(options) {
+    return `..[${this.selectors.map(s => s.toString(options)).join(", ")}]`;
   }
   visit(node) {
     var _this = this;
@@ -3616,23 +3730,18 @@ function shuffle(entries) {
 }
 
 /**
- *
+ * A compiled JSONPath query ready to be applied to different data repeatedly.
  */
 class JSONPathQuery {
-  /**
-   *
-   * @param environment -
-   * @param segments -
-   */
   constructor(environment, segments) {
     this.environment = environment;
     this.segments = segments;
   }
 
   /**
-   *
-   * @param value -
-   * @returns
+   * Apply this JSONPath query to _value_.
+   * @param value - A JSON-like object to apply this query to.
+   * @returns Nodes matched by applying this query to _value_.
    */
   query(value) {
     let nodes = [new JSONPathNode(value, [], value)];
@@ -3643,9 +3752,9 @@ class JSONPathQuery {
   }
 
   /**
-   *
-   * @param value -
-   * @returns
+   * Apply this JSONPath query to _value_.
+   * @param value - A JSON-like object to apply this query to.
+   * @returns An iterator over nodes matched by applying this query to _value_.
    */
   lazyQuery(value) {
     let nodes = [new JSONPathNode(value, [], value)][Symbol.iterator]();
@@ -3671,11 +3780,15 @@ class JSONPathQuery {
   }
 
   /**
-   *
+   * Return a string representation of this query.
    */
-  toString() {
-    return `$${this.segments.map(s => s.toString()).join("")}`;
+  toString(options) {
+    return `$${this.segments.map(s => s.toString(options)).join("")}`;
   }
+
+  /**
+   * Return `true` if this query is a _singular query_, or `false` otherwise.
+   */
   singularQuery() {
     for (const segment of this.segments) {
       if (segment instanceof DescendantSegment) return false;
@@ -3717,8 +3830,15 @@ class KeySelector extends JSONPathSelector {
       yield new JSONPathNode(this.key, node.location.concat(`${KEY_MARK}${this.key}`), node.root);
     }
   }
-  toString() {
-    return `~'${this.key.replaceAll("'", "\\'")}'`;
+  toString(options) {
+    const {
+      form
+    } = {
+      ...defaultSerializationOptions,
+      ...options
+    };
+    const serialize = form === "canonical" ? toCanonical : toQuoted;
+    return `~${serialize(this.key)}`;
   }
 }
 
@@ -3794,8 +3914,8 @@ class KeysFilterSelector extends JSONPathSelector {
       }
     }
   }
-  toString() {
-    return `~?${this.expression.toString()}`;
+  toString(options) {
+    return `~?${this.expression.toString(options)}`;
   }
 }
 
@@ -5085,6 +5205,6 @@ var index = /*#__PURE__*/Object.freeze({
   apply: apply
 });
 
-const version = "2.0.0";
+const version = "2.1.0";
 
 export { DEFAULT_ENVIRONMENT, FunctionExpressionType, JSONPatch, JSONPatchError, JSONPatchTestFailure, JSONPathEnvironment, JSONPathError, JSONPathIndexError, JSONPathLexerError, JSONPathNode, JSONPathNodeList, JSONPathQuery, JSONPathRecursionLimitError, JSONPathSyntaxError, JSONPathTypeError, JSONPointer, Nothing, RelativeJSONPointer, Token, TokenKind, UNDEFINED, apply, compile, index as jsonpatch, index$1 as jsonpath, index$3 as jsonpointer, lazyQuery, query, resolve, version };