json-p3 2.0.0 → 2.1.0

package/dist/json-p3.iife.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
@@ -654,6 +654,30 @@ var json_p3 = (function (exports) {
     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");
 
   /**
@@ -661,7 +685,7 @@ var json_p3 = (function (exports) {
    */
 
   /**
-   * Object passed to FilterExpression.evaluate().
+   * Object passed to `FilterExpression.evaluate()`.
    */
 
   /**
@@ -672,6 +696,14 @@ var json_p3 = (function (exports) {
   }
   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.
    */
@@ -686,10 +718,31 @@ var json_p3 = (function (exports) {
       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("")
       );
     }
 
@@ -702,8 +755,16 @@ var json_p3 = (function (exports) {
       }
       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}`;
     }
   }
 
@@ -764,8 +825,8 @@ var json_p3 = (function (exports) {
      * 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));
     }
 
     /**
@@ -837,7 +898,7 @@ var json_p3 = (function (exports) {
       return this.value;
     }
     toString() {
-      return JSON.stringify(this.value);
+      return toCanonical(this.value);
     }
   }
   class NumberLiteral extends FilterExpressionLiteral {
@@ -868,10 +929,13 @@ var json_p3 = (function (exports) {
       }
       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);
@@ -894,11 +958,12 @@ var json_p3 = (function (exports) {
       }
       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 {
@@ -912,8 +977,38 @@ var json_p3 = (function (exports) {
       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);
     }
   }
 
@@ -931,16 +1026,16 @@ var json_p3 = (function (exports) {
     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 {
@@ -958,8 +1053,8 @@ var json_p3 = (function (exports) {
       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) {
@@ -3166,8 +3261,17 @@ var json_p3 = (function (exports) {
         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);
     }
   }
 
@@ -3436,8 +3540,8 @@ var json_p3 = (function (exports) {
         }
       }
     }
-    toString() {
-      return `?${this.expression.toString()}`;
+    toString(options) {
+      return `?${this.expression.toString(options)}`;
     }
   }
 
@@ -3468,7 +3572,7 @@ var json_p3 = (function (exports) {
      */
 
     /**
-     * Return a canonical string representation of this segment.
+     * Return a string representation of this segment.
      */
   }
 
@@ -3490,8 +3594,18 @@ var json_p3 = (function (exports) {
         }
       }
     }
-    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(", ")}]`;
     }
   }
 
@@ -3518,8 +3632,8 @@ var json_p3 = (function (exports) {
         }
       }
     }
-    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;
@@ -3619,23 +3733,18 @@ var json_p3 = (function (exports) {
   }
 
   /**
-   *
+   * 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)];
@@ -3646,9 +3755,9 @@ var json_p3 = (function (exports) {
     }
 
     /**
-     *
-     * @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]();
@@ -3674,11 +3783,15 @@ var json_p3 = (function (exports) {
     }
 
     /**
-     *
+     * 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;
@@ -3720,8 +3833,15 @@ var json_p3 = (function (exports) {
         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)}`;
     }
   }
 
@@ -3797,8 +3917,8 @@ var json_p3 = (function (exports) {
         }
       }
     }
-    toString() {
-      return `~?${this.expression.toString()}`;
+    toString(options) {
+      return `~?${this.expression.toString(options)}`;
     }
   }
 
@@ -5088,7 +5208,7 @@ var json_p3 = (function (exports) {
     apply: apply
   });
 
-  const version = "2.0.0";
+  const version = "2.1.0";
 
   exports.DEFAULT_ENVIRONMENT = DEFAULT_ENVIRONMENT;
   exports.FunctionExpressionType = FunctionExpressionType;