Support pretty and canonical paths for JSONPathQuery and JSONPathNode

Author: lionel-rowe

src/path/expression.ts

@@ -4,7 +4,7 @@ import { FunctionExpressionType } from "./functions/function";
 import { JSONPathNodeList } from "./node";
 import { JSONPathQuery } from "./path";
 import { Token } from "./token";
-import { FilterContext, Nothing } from "./types";
+import { FilterContext, Nothing, SerializationOptions } from "./types";
 import { isNumber, isString } from "../types";
 
 /**
@@ -22,7 +22,7 @@ export abstract class FilterExpression {
   /**
    * Return a string representation of the expression.
    */
-  public abstract toString(): string;
+  public abstract toString(options?: SerializationOptions): string;
 }
 
 /**
@@ -112,8 +112,8 @@ export class PrefixExpression extends FilterExpression {
     );
   }
 
-  public toString(): string {
-    return `${this.operator}${this.right.toString()}`;
+  public toString(options?: SerializationOptions): string {
+    return `${this.operator}${this.right.toString(options)}`;
   }
 }
 
@@ -158,13 +158,13 @@ export class InfixExpression extends FilterExpression {
     return compare(left, this.operator, right);
   }
 
-  public toString(): string {
+  public toString(options?: SerializationOptions): string {
     if (this.logical) {
-      return `(${this.left.toString()} ${
+      return `(${this.left.toString(options)} ${
         this.operator
-      } ${this.right.toString()})`;
+      } ${this.right.toString(options)})`;
     }
-    return `${this.left.toString()} ${this.operator} ${this.right.toString()}`;
+    return `${this.left.toString(options)} ${this.operator} ${this.right.toString(options)}`;
   }
 }
 
@@ -182,8 +182,8 @@ export class LogicalExpression extends FilterExpression {
     return isTruthy(value);
   }
 
-  public toString(): string {
-    return this.expression.toString();
+  public toString(options?: SerializationOptions): string {
+    return this.expression.toString(options);
   }
 }
 
@@ -208,8 +208,8 @@ export class RelativeQuery extends FilterQuery {
       : this.path.query(context.currentValue);
   }
 
-  public toString(): string {
-    return `@${this.path.toString().slice(1)}`;
+  public toString(options?: SerializationOptions): string {
+    return `@${this.path.toString(options).slice(1)}`;
   }
 }
 
@@ -220,8 +220,8 @@ export class RootQuery extends FilterQuery {
       : this.path.query(context.rootValue);
   }
 
-  public toString(): string {
-    return this.path.toString();
+  public toString(options?: SerializationOptions): string {
+    return this.path.toString(options);
   }
 }
 
@@ -254,8 +254,8 @@ export class FunctionExtension extends FilterExpression {
     return func.call(...args);
   }
 
-  public toString(): string {
-    return `${this.name}(${this.args.map((e) => e.toString()).join(", ")})`;
+  public toString(options?: SerializationOptions): string {
+    return `${this.name}(${this.args.map((e) => e.toString(options)).join(", ")})`;
   }
 
   private unpack_node_list(arg: JSONPathNodeList): unknown {

src/path/extra/selectors.ts

@@ -3,8 +3,15 @@ import { JSONPathEnvironment } from "../environment";
 import { LogicalExpression } from "../expression";
 import { JSONPathNode } from "../node";
 import { JSONPathSelector } from "../selectors";
+import { toCanonical, toQuoted } from "../serialize";
 import { Token } from "../token";
-import { FilterContext, KEY_MARK, hasStringKey } from "../types";
+import {
+  type FilterContext,
+  type SerializationOptions,
+  KEY_MARK,
+  defaultSerializationOptions,
+  hasStringKey,
+} from "../types";
 
 export class KeySelector extends JSONPathSelector {
   constructor(
@@ -44,8 +51,10 @@ export class KeySelector extends JSONPathSelector {
     }
   }
 
-  public toString(): string {
-    return `~'${this.key.replaceAll("'", "\\'")}'`;
+  public toString(options?: SerializationOptions): string {
+    const { form } = { ...defaultSerializationOptions, ...options };
+    const serialize = form === "canonical" ? toCanonical : toQuoted;
+    return `~${serialize(this.key)}`;
   }
 }
 
@@ -150,7 +159,7 @@ export class KeysFilterSelector extends JSONPathSelector {
     }
   }
 
-  public toString(): string {
-    return `~?${this.expression.toString()}`;
+  public toString(options?: SerializationOptions): string {
+    return `~?${this.expression.toString(options)}`;
   }
 }

src/path/node.ts

@@ -1,6 +1,11 @@
 import { JSONPointer } from "../pointer";
 import { JSONValue, isString } from "../types";
-import { KEY_MARK } from "./types";
+import { toCanonical, toQuoted, toShorthand } from "./serialize";
+import {
+  type SerializationOptions,
+  defaultSerializationOptions,
+  KEY_MARK,
+} from "./types";
 
 /**
  * The pair of a JSON value and its location found in the target JSON value.
@@ -17,12 +22,28 @@ export class JSONPathNode {
     readonly root: JSONValue,
   ) {}
 
+  /**
+   * @deprecated Use {@link getPath} with `options.form` set to `canonical` instead.
+   */
   public get path(): string {
+    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.
+   */
+  public getPath(options?: SerializationOptions): string {
+    const opts = { ...defaultSerializationOptions, ...options };
+
     return (
       // eslint-disable-next-line prefer-template
       "$" +
       this.location
-        .map((s) => (isString(s) ? this.decode_name_location(s) : `[${s}]`))
+        .map((s) => (isString(s) ? this.decodeNameLocation(s, opts) : `[${s}]`))
         .join("")
     );
   }
@@ -37,10 +58,20 @@ export class JSONPathNode {
     return new JSONPointer(JSONPointer.encode(this.location.map(String)));
   }
 
-  private decode_name_location(name: string): string {
-    return name.startsWith(KEY_MARK)
-      ? `[~'${name.slice(1).replaceAll("'", "\\'")}']`
-      : `['${name.replaceAll("'", "\\'")}']`;
+  private decodeNameLocation(
+    name: string,
+    options: SerializationOptions,
+  ): string {
+    const serialize = options.form === "canonical" ? toCanonical : toQuoted;
+    const hasKeyMark = name.startsWith(KEY_MARK);
+    if (hasKeyMark) name = name.slice(1);
+    const shorthand = toShorthand(name);
+
+    if (hasKeyMark) {
+      return shorthand == null ? `[~${serialize(name)}]` : `.~${shorthand}`;
+    }
+
+    return shorthand == null ? `[${serialize(name)}]` : `.${shorthand}`;
   }
 }
 
@@ -99,8 +130,8 @@ export class JSONPathNodeList {
    * A normalized path contains only property name and index selectors, and
    * always uses bracketed segments, never shorthand selectors.
    */
-  public paths(): string[] {
-    return this.nodes.map((node) => node.path);
+  public paths(options?: SerializationOptions): string[] {
+    return this.nodes.map((node) => node.getPath(options));
   }
 
   /**

src/path/path.ts

@@ -3,6 +3,7 @@ import { JSONPathNode, JSONPathNodeList } from "./node";
 import { IndexSelector, NameSelector } from "./selectors";
 import { JSONValue } from "../types";
 import { JSONPathSegment, DescendantSegment } from "./segments";
+import { SerializationOptions } from "./types";
 
 /**
  *
@@ -62,10 +63,11 @@ export class JSONPathQuery {
   }
 
   /**
-   *
+   * Return a string representation of this query.
    */
-  public toString(): string {
-    return `$${this.segments.map((s) => s.toString()).join("")}`;
+  public toString(options?: SerializationOptions): string {
+    // return this.prettyPath();
+    return `$${this.segments.map((s) => s.toString(options)).join("")}`;
   }
 
   public singularQuery(): boolean {

src/path/segments.ts

@@ -4,15 +4,10 @@ import { JSONPathRecursionLimitError } from "./errors";
 import { JSONPathNode } from "./node";
 import { JSONPathSelector, NameSelector } from "./selectors";
 import { Token } from "./token";
-
-/**
- * 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;
+import {
+  type SerializationOptions,
+  defaultSerializationOptions,
+} from "./types";
 
 /** Base class for all JSONPath segments. Both shorthand and bracketed. */
 export abstract class JSONPathSegment {
@@ -35,9 +30,9 @@ export abstract class JSONPathSegment {
   ): Generator<JSONPathNode>;
 
   /**
-   * Return a canonical string representation of this segment.
+   * Return a string representation of this segment.
    */
-  public abstract toString(): string;
+  public abstract toString(options?: SerializationOptions): string;
 }
 
 /** The child selection segment. */
@@ -60,21 +55,19 @@ export class ChildSegment extends JSONPathSegment {
     }
   }
 
-  public toString(): string {
-    const { selectors } = this;
-    const [selector] = selectors;
-
-    if (selectors.length === 1 && selector instanceof NameSelector) {
-      const inner = selector.toString().slice(1, -1);
-
-      if (SHORTHAND_COMPATIBLE_IDENTIFIER.test(inner)) {
-        return `.${inner}`;
-      }
+  public toString(options?: SerializationOptions): string {
+    const { form } = { ...defaultSerializationOptions, ...options };
 
-      return `[${selector}]`;
+    if (
+      form === "pretty" &&
+      this.selectors.length === 1 &&
+      this.selectors[0] instanceof NameSelector
+    ) {
+      const shorthand = this.selectors[0].shorthand();
+      if (shorthand != null) return `.${shorthand}`;
     }
 
-    return `[${selectors.map((s) => s.toString()).join(", ")}]`;
+    return `[${this.selectors.map((s) => s.toString(options)).join(", ")}]`;
   }
 }
 
@@ -110,8 +103,8 @@ export class DescendantSegment extends JSONPathSegment {
     }
   }
 
-  public toString(): string {
-    return `..[${this.selectors.map((s) => s.toString()).join(", ")}]`;
+  public toString(options?: SerializationOptions): string {
+    return `..[${this.selectors.map((s) => s.toString(options)).join(", ")}]`;
   }
 
   private *visit(

src/path/selectors.ts

@@ -3,8 +3,14 @@ import { JSONPathIndexError } from "./errors";
 import { LogicalExpression } from "./expression";
 import { JSONPathNode } from "./node";
 import { Token } from "./token";
-import { FilterContext, hasStringKey } from "./types";
+import {
+  type FilterContext,
+  type SerializationOptions,
+  defaultSerializationOptions,
+  hasStringKey,
+} from "./types";
 import { isArray, isObject, isString, JSONValue } from "../types";
+import { toCanonical, toQuoted, toShorthand } from "./serialize";
 
 /**
  * Base class for all JSONPath segments and selectors.
@@ -31,7 +37,7 @@ export abstract class JSONPathSelector {
   /**
    * Return a canonical string representation of this selector.
    */
-  public abstract toString(): string;
+  public abstract toString(options?: SerializationOptions): string;
 }
 
 /**
@@ -70,16 +76,13 @@ export class NameSelector extends JSONPathSelector {
     }
   }
 
-  public toString(): string {
-    const jsonified = JSON.stringify(this.name);
-
-    const inner = jsonified.slice(1, -1);
-
-    if (inner.includes("'") && !inner.includes('"')) {
-      return jsonified;
-    }
+  public toString(options?: SerializationOptions): string {
+    const { form } = { ...defaultSerializationOptions, ...options };
+    return form === "canonical" ? toCanonical(this.name) : toQuoted(this.name);
+  }
 
-    return `'${inner.replaceAll('\\"', '"').replaceAll("'", "\\'")}'`;
+  public shorthand(): string | null {
+    return toShorthand(this.name);
   }
 }
 
@@ -416,7 +419,7 @@ export class FilterSelector extends JSONPathSelector {
     }
   }
 
-  public toString(): string {
-    return `?${this.expression.toString()}`;
+  public toString(options?: SerializationOptions): string {
+    return `?${this.expression.toString(options)}`;
   }
 }

src/path/serialize.ts

@@ -0,0 +1,25 @@
+/**
+ * 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. */
+export function toQuoted(name: string): string {
+  return name.includes("'") && !name.includes('"')
+    ? JSON.stringify(name)
+    : toCanonical(name);
+}
+
+/** Usable in a normalized path. */
+export function toCanonical(name: string): string {
+  return `'${JSON.stringify(name).slice(1, -1).replaceAll('\\"', '"').replaceAll("'", "\\'")}'`;
+}
+
+/** Usable in a shorthand path. */
+export function toShorthand(name: string): string | null {
+  return SHORTHAND_COMPATIBLE_IDENTIFIER.test(name) ? name : null;
+}