json-p3 1.3.5 → 2.1.0

package/dist/path/environment.d.ts

@@ -1,7 +1,7 @@
 import { FilterExpression } from "./expression";
 import { FilterFunction } from "./functions/function";
 import { JSONPathNode, JSONPathNodeList } from "./node";
-import { JSONPath } from "./path";
+import { JSONPathQuery } from "./path";
 import { Token } from "./token";
 import { JSONValue } from "../types";
 /**
@@ -99,9 +99,9 @@ export declare class JSONPathEnvironment {
     constructor(options?: JSONPathEnvironmentOptions);
     /**
      * @param path - A JSONPath query to parse.
-     * @returns A new {@link JSONPath} object, bound to this environment.
+     * @returns A new {@link JSONPathQuery} object, bound to this environment.
      */
-    compile(path: string): JSONPath;
+    compile(path: string): JSONPathQuery;
     /**
      *
      * @param path - A JSONPath query to parse and evaluate against _value_.
@@ -138,7 +138,7 @@ export declare class JSONPathEnvironment {
     /**
      * Check the well-typedness of a function's arguments at compile-time.
      *
-     * This method is called by the {@link Parser} when parsing function calls.
+     * This method is called by the parser when parsing function calls.
      * It is expected to throw a {@link JSONPathTypeError} if the function's
      * parameters are not well-typed.
      *

package/dist/path/expression.d.ts

@@ -1,7 +1,7 @@
 import { JSONPathNodeList } from "./node";
-import { JSONPath } from "./path";
+import { JSONPathQuery } from "./path";
 import { Token } from "./token";
-import { FilterContext } from "./types";
+import { FilterContext, SerializationOptions } from "./types";
 /**
  * Base class for all filter expressions.
  */
@@ -16,7 +16,7 @@ export declare abstract class FilterExpression {
     /**
      * Return a string representation of the expression.
      */
-    abstract toString(): string;
+    abstract toString(options?: SerializationOptions): string;
 }
 /**
  * Base class for JSONPath ValueType literals.
@@ -54,7 +54,7 @@ export declare class PrefixExpression extends FilterExpression {
     readonly right: FilterExpression;
     constructor(token: Token, operator: string, right: FilterExpression);
     evaluate(context: FilterContext): boolean;
-    toString(): string;
+    toString(options?: SerializationOptions): string;
 }
 export declare class InfixExpression extends FilterExpression {
     readonly token: Token;
@@ -64,30 +64,30 @@ export declare class InfixExpression extends FilterExpression {
     readonly logical: boolean;
     constructor(token: Token, left: FilterExpression, operator: string, right: FilterExpression);
     evaluate(context: FilterContext): boolean;
-    toString(): string;
+    toString(options?: SerializationOptions): string;
 }
 export declare class LogicalExpression extends FilterExpression {
     readonly token: Token;
     readonly expression: FilterExpression;
     constructor(token: Token, expression: FilterExpression);
     evaluate(context: FilterContext): boolean;
-    toString(): string;
+    toString(options?: SerializationOptions): string;
 }
 /**
  * Base class for relative and absolute JSONPath query expressions.
  */
-export declare abstract class JSONPathQuery extends FilterExpression {
+export declare abstract class FilterQuery extends FilterExpression {
     readonly token: Token;
-    readonly path: JSONPath;
-    constructor(token: Token, path: JSONPath);
+    readonly path: JSONPathQuery;
+    constructor(token: Token, path: JSONPathQuery);
 }
-export declare class RelativeQuery extends JSONPathQuery {
+export declare class RelativeQuery extends FilterQuery {
     evaluate(context: FilterContext): JSONPathNodeList;
-    toString(): string;
+    toString(options?: SerializationOptions): string;
 }
-export declare class RootQuery extends JSONPathQuery {
+export declare class RootQuery extends FilterQuery {
     evaluate(context: FilterContext): JSONPathNodeList;
-    toString(): string;
+    toString(options?: SerializationOptions): string;
 }
 export declare class FunctionExtension extends FilterExpression {
     readonly token: Token;
@@ -95,7 +95,7 @@ export declare class FunctionExtension extends FilterExpression {
     readonly args: FilterExpression[];
     constructor(token: Token, name: string, args: FilterExpression[]);
     evaluate(context: FilterContext): unknown;
-    toString(): string;
+    toString(options?: SerializationOptions): string;
     private unpack_node_list;
 }
 export declare function compare(left: unknown, operator: string, right: unknown): boolean;

package/dist/path/extra/selectors.d.ts

@@ -3,15 +3,15 @@ import { LogicalExpression } from "../expression";
 import { JSONPathNode } from "../node";
 import { JSONPathSelector } from "../selectors";
 import { Token } from "../token";
+import { type SerializationOptions } from "../types";
 export declare class KeySelector extends JSONPathSelector {
     readonly environment: JSONPathEnvironment;
     readonly token: Token;
     readonly key: string;
-    readonly shorthand: boolean;
-    constructor(environment: JSONPathEnvironment, token: Token, key: string, shorthand?: boolean);
-    resolve(nodes: JSONPathNode[]): JSONPathNode[];
-    lazyResolve(nodes: Iterable<JSONPathNode>): Generator<JSONPathNode>;
-    toString(): string;
+    constructor(environment: JSONPathEnvironment, token: Token, key: string);
+    resolve(node: JSONPathNode): JSONPathNode[];
+    lazyResolve(node: JSONPathNode): Generator<JSONPathNode>;
+    toString(options?: SerializationOptions): string;
 }
 /**
  * Object property name selector or array index selector.
@@ -19,10 +19,9 @@ export declare class KeySelector extends JSONPathSelector {
 export declare class KeysSelector extends JSONPathSelector {
     readonly environment: JSONPathEnvironment;
     readonly token: Token;
-    readonly shorthand: boolean;
-    constructor(environment: JSONPathEnvironment, token: Token, shorthand?: boolean);
-    resolve(nodes: JSONPathNode[]): JSONPathNode[];
-    lazyResolve(nodes: Iterable<JSONPathNode>): Generator<JSONPathNode>;
+    constructor(environment: JSONPathEnvironment, token: Token);
+    resolve(node: JSONPathNode): JSONPathNode[];
+    lazyResolve(node: JSONPathNode): Generator<JSONPathNode>;
     toString(): string;
 }
 export declare class KeysFilterSelector extends JSONPathSelector {
@@ -30,7 +29,7 @@ export declare class KeysFilterSelector extends JSONPathSelector {
     readonly token: Token;
     readonly expression: LogicalExpression;
     constructor(environment: JSONPathEnvironment, token: Token, expression: LogicalExpression);
-    resolve(nodes: JSONPathNode[]): JSONPathNode[];
-    lazyResolve(nodes: Iterable<JSONPathNode>): Generator<JSONPathNode>;
-    toString(): string;
+    resolve(node: JSONPathNode): JSONPathNode[];
+    lazyResolve(node: JSONPathNode): Generator<JSONPathNode>;
+    toString(options?: SerializationOptions): string;
 }

package/dist/path/index.d.ts

@@ -1,10 +1,12 @@
 import { JSONValue } from "../types";
 import { JSONPathEnvironment } from "./environment";
 import { JSONPathNode, JSONPathNodeList } from "./node";
-import { JSONPath } from "./path";
+import { JSONPathQuery } from "./path";
 export { JSONPathEnvironment } from "./environment";
 export type { JSONPathEnvironmentOptions } from "./environment";
-export { JSONPath } from "./path";
+export { JSONPathSegment } from "./segments";
+export { JSONPathSelector } from "./selectors";
+export { JSONPathQuery } from "./path";
 export { JSONPathNodeList, JSONPathNode } from "./node";
 export { Token, TokenKind } from "./token";
 export * as selectors from "./selectors";
@@ -14,7 +16,7 @@ export { FunctionExpressionType } from "./functions";
 export type { FilterFunction } from "./functions";
 export { JSONPathError, JSONPathIndexError, JSONPathLexerError, JSONPathSyntaxError, JSONPathTypeError, JSONPathRecursionLimitError, } from "./errors";
 export { Nothing, KEY_MARK } from "./types";
-export type { JSONPathValue, FilterContext } from "./types";
+export type { JSONPathValue, FilterContext, SerializationOptions, } from "./types";
 export declare const DEFAULT_ENVIRONMENT: JSONPathEnvironment;
 /**
  * Query JSON value _value_ with JSONPath expression _path_.
@@ -61,7 +63,7 @@ export declare function lazyQuery(path: string, value: JSONValue): IterableItera
  * If filter function arguments are invalid, or filter expression are
  * used in an invalid way.
  */
-export declare function compile(path: string): JSONPath;
+export declare function compile(path: string): JSONPathQuery;
 /**
  * Return a {@link JSONPathNode} instance for the first object found in
  * _value_ matching _path_.

package/dist/path/node.d.ts

@@ -1,5 +1,6 @@
 import { JSONPointer } from "../pointer";
 import { JSONValue } from "../types";
+import { type SerializationOptions } from "./types";
 /**
  * The pair of a JSON value and its location found in the target JSON value.
  */
@@ -13,12 +14,23 @@ export declare class JSONPathNode {
      * @param root - The target value at the top of the JSON node tree.
      */
     constructor(value: JSONValue, location: Array<string | number>, root: JSONValue);
+    /**
+     * @deprecated Use {@link getPath} with `options.form` set to `canonical` instead.
+     */
     get path(): string;
+    /**
+     * 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?: SerializationOptions): string;
     /**
      * Return this node's location as a {@link JSONPointer}.
      */
     toPointer(): JSONPointer;
-    private decode_name_location;
+    private decodeNameLocation;
 }
 /**
  *
@@ -59,7 +71,7 @@ export declare class JSONPathNodeList {
      * A normalized path contains only property name and index selectors, and
      * always uses bracketed segments, never shorthand selectors.
      */
-    paths(): string[];
+    paths(options?: SerializationOptions): string[];
     /**
      * @returns An array of {@link JSONPointer} instances, one for each node
      * in the list.

package/dist/path/parse.d.ts

@@ -1,6 +1,7 @@
 import { JSONPathEnvironment } from "./environment";
 import { BooleanLiteral, FilterExpression, FunctionExtension, InfixExpression, NullLiteral, NumberLiteral, PrefixExpression, RelativeQuery, RootQuery, StringLiteral } from "./expression";
-import { BracketedSelection, FilterSelector, IndexSelector, JSONPathSelector, SliceSelector } from "./selectors";
+import { FilterSelector, IndexSelector, JSONPathSelector, SliceSelector } from "./selectors";
+import { JSONPathSegment } from "./segments";
 import { Token, TokenStream } from "./token";
 import { CurrentKey } from "./extra/expression";
 /**
@@ -10,12 +11,12 @@ export declare class Parser {
     readonly environment: JSONPathEnvironment;
     protected tokenMap: Map<string, (stream: TokenStream) => FilterExpression>;
     constructor(environment: JSONPathEnvironment);
-    parse(stream: TokenStream): JSONPathSelector[];
-    protected parsePath(stream: TokenStream, inFilter?: boolean): JSONPathSelector[];
-    protected parseSegment(stream: TokenStream): JSONPathSelector | null;
+    parse(stream: TokenStream): JSONPathSegment[];
+    protected parseQuery(stream: TokenStream, inFilter?: boolean): JSONPathSegment[];
+    protected parseSelectors(stream: TokenStream): JSONPathSelector[];
     protected parseIndex(stream: TokenStream): IndexSelector;
     protected parseSlice(stream: TokenStream): SliceSelector;
-    protected parseBracketedSelection(stream: TokenStream): BracketedSelection;
+    protected parseBracketedSelection(stream: TokenStream): JSONPathSelector[];
     protected parseFilter(stream: TokenStream, keys?: boolean): FilterSelector;
     protected parseBoolean(stream: TokenStream): BooleanLiteral;
     protected parseNull(stream: TokenStream): NullLiteral;

package/dist/path/path.d.ts

@@ -1,29 +1,25 @@
 import { JSONPathEnvironment } from "./environment";
 import { JSONPathNode, JSONPathNodeList } from "./node";
-import { JSONPathSelector } from "./selectors";
 import { JSONValue } from "../types";
+import { JSONPathSegment } from "./segments";
+import { SerializationOptions } from "./types";
 /**
- *
+ * A compiled JSONPath query ready to be applied to different data repeatedly.
  */
-export declare class JSONPath {
+export declare class JSONPathQuery {
     readonly environment: JSONPathEnvironment;
-    readonly selectors: JSONPathSelector[];
+    readonly segments: JSONPathSegment[];
+    constructor(environment: JSONPathEnvironment, segments: JSONPathSegment[]);
     /**
-     *
-     * @param environment -
-     * @param selectors -
-     */
-    constructor(environment: JSONPathEnvironment, selectors: JSONPathSelector[]);
-    /**
-     *
-     * @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: JSONValue): JSONPathNodeList;
     /**
-     *
-     * @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: JSONValue): IterableIterator<JSONPathNode>;
     /**
@@ -36,8 +32,11 @@ export declare class JSONPath {
      */
     match(value: JSONValue): JSONPathNode | undefined;
     /**
-     *
+     * Return a string representation of this query.
+     */
+    toString(options?: SerializationOptions): string;
+    /**
+     * Return `true` if this query is a _singular query_, or `false` otherwise.
      */
-    toString(): string;
     singularQuery(): boolean;
 }

package/dist/path/segments.d.ts

@@ -0,0 +1,39 @@
+import { JSONPathEnvironment } from "./environment";
+import { JSONPathNode } from "./node";
+import { JSONPathSelector } from "./selectors";
+import { Token } from "./token";
+import { type SerializationOptions } from "./types";
+/** Base class for all JSONPath segments. Both shorthand and bracketed. */
+export declare abstract class JSONPathSegment {
+    readonly environment: JSONPathEnvironment;
+    readonly token: Token;
+    readonly selectors: JSONPathSelector[];
+    constructor(environment: JSONPathEnvironment, token: Token, selectors: JSONPathSelector[]);
+    /**
+     * @param nodes - Nodes matched by preceding segments.
+     */
+    abstract resolve(nodes: JSONPathNode[]): JSONPathNode[];
+    /**
+     * @param nodes - Nodes matched by preceding segments.
+     */
+    abstract lazyResolve(nodes: Iterable<JSONPathNode>): Generator<JSONPathNode>;
+    /**
+     * Return a string representation of this segment.
+     */
+    abstract toString(options?: SerializationOptions): string;
+}
+/** The child selection segment. */
+export declare class ChildSegment extends JSONPathSegment {
+    resolve(nodes: JSONPathNode[]): JSONPathNode[];
+    lazyResolve(nodes: Iterable<JSONPathNode>): Generator<JSONPathNode>;
+    toString(options?: SerializationOptions): string;
+}
+/** The recursive descent segment. */
+export declare class DescendantSegment extends JSONPathSegment {
+    resolve(nodes: JSONPathNode[]): JSONPathNode[];
+    lazyResolve(nodes: Iterable<JSONPathNode>): Generator<JSONPathNode>;
+    toString(options?: SerializationOptions): string;
+    private visit;
+    private nondeterministicVisit;
+    private nondeterministicChildren;
+}

package/dist/path/selectors.d.ts

@@ -2,6 +2,7 @@ import { JSONPathEnvironment } from "./environment";
 import { LogicalExpression } from "./expression";
 import { JSONPathNode } from "./node";
 import { Token } from "./token";
+import { type SerializationOptions } from "./types";
 /**
  * Base class for all JSONPath segments and selectors.
  */
@@ -13,17 +14,17 @@ export declare abstract class JSONPathSelector {
      */
     constructor(environment: JSONPathEnvironment, token: Token);
     /**
-     * @param nodes - Nodes matched by preceding selectors.
+     * @param node - Nodes matched by preceding selectors.
      */
-    abstract resolve(nodes: JSONPathNode[]): JSONPathNode[];
+    abstract resolve(node: JSONPathNode): JSONPathNode[];
     /**
-     * @param nodes - Nodes matched by preceding selectors.
+     * @param node - Nodes matched by preceding selectors.
      */
-    abstract lazyResolve(nodes: Iterable<JSONPathNode>): Generator<JSONPathNode>;
+    abstract lazyResolve(node: JSONPathNode): Generator<JSONPathNode>;
     /**
      * Return a canonical string representation of this selector.
      */
-    abstract toString(): string;
+    abstract toString(options?: SerializationOptions): string;
 }
 /**
  * Shorthand and quoted name selector.
@@ -32,11 +33,11 @@ export declare class NameSelector extends JSONPathSelector {
     readonly environment: JSONPathEnvironment;
     readonly token: Token;
     readonly name: string;
-    readonly shorthand: boolean;
-    constructor(environment: JSONPathEnvironment, token: Token, name: string, shorthand: boolean);
-    resolve(nodes: JSONPathNode[]): JSONPathNode[];
-    lazyResolve(nodes: Iterable<JSONPathNode>): Generator<JSONPathNode>;
-    toString(): string;
+    constructor(environment: JSONPathEnvironment, token: Token, name: string);
+    resolve(node: JSONPathNode): JSONPathNode[];
+    lazyResolve(node: JSONPathNode): Generator<JSONPathNode>;
+    toString(options?: SerializationOptions): string;
+    shorthand(): string | null;
 }
 /**
  * Array index selector.
@@ -46,8 +47,8 @@ export declare class IndexSelector extends JSONPathSelector {
     readonly token: Token;
     readonly index: number;
     constructor(environment: JSONPathEnvironment, token: Token, index: number);
-    resolve(nodes: JSONPathNode[]): JSONPathNode[];
-    lazyResolve(nodes: Iterable<JSONPathNode>): Generator<JSONPathNode>;
+    resolve(node: JSONPathNode): JSONPathNode[];
+    lazyResolve(node: JSONPathNode): Generator<JSONPathNode>;
     toString(): string;
     private normalizedIndex;
 }
@@ -58,8 +59,8 @@ export declare class SliceSelector extends JSONPathSelector {
     readonly stop?: number | undefined;
     readonly step?: number | undefined;
     constructor(environment: JSONPathEnvironment, token: Token, start?: number | undefined, stop?: number | undefined, step?: number | undefined);
-    resolve(nodes: JSONPathNode[]): JSONPathNode[];
-    lazyResolve(nodes: Iterable<JSONPathNode>): Generator<JSONPathNode>;
+    resolve(node: JSONPathNode): JSONPathNode[];
+    lazyResolve(node: JSONPathNode): Generator<JSONPathNode>;
     toString(): string;
     private checkRange;
     private slice;
@@ -68,41 +69,17 @@ export declare class SliceSelector extends JSONPathSelector {
 export declare class WildcardSelector extends JSONPathSelector {
     readonly environment: JSONPathEnvironment;
     readonly token: Token;
-    readonly shorthand: boolean;
-    constructor(environment: JSONPathEnvironment, token: Token, shorthand?: boolean);
-    resolve(nodes: JSONPathNode[]): JSONPathNode[];
-    lazyResolve(nodes: Iterable<JSONPathNode>): Generator<JSONPathNode>;
-    toString(): string;
-}
-export declare class RecursiveDescentSegment extends JSONPathSelector {
-    readonly environment: JSONPathEnvironment;
-    readonly token: Token;
-    readonly selector: JSONPathSelector;
-    constructor(environment: JSONPathEnvironment, token: Token, selector: JSONPathSelector);
-    resolve(nodes: JSONPathNode[]): JSONPathNode[];
-    lazyResolve(nodes: Iterable<JSONPathNode>): Generator<JSONPathNode>;
-    protected _lazyResolve(nodes: Iterable<JSONPathNode>): Generator<JSONPathNode>;
+    constructor(environment: JSONPathEnvironment, token: Token);
+    resolve(node: JSONPathNode): JSONPathNode[];
+    lazyResolve(node: JSONPathNode): Generator<JSONPathNode>;
     toString(): string;
-    private visitor;
-    protected nondeterministicVisitor(root: JSONPathNode, depth?: number): JSONPathNode[];
-    protected nondeterministicChildren(node: JSONPathNode): JSONPathNode[];
 }
 export declare class FilterSelector extends JSONPathSelector {
     readonly environment: JSONPathEnvironment;
     readonly token: Token;
     readonly expression: LogicalExpression;
     constructor(environment: JSONPathEnvironment, token: Token, expression: LogicalExpression);
-    resolve(nodes: JSONPathNode[]): JSONPathNode[];
-    lazyResolve(nodes: Iterable<JSONPathNode>): Generator<JSONPathNode>;
-    toString(): string;
-}
-export type BracketedSegment = FilterSelector | IndexSelector | NameSelector | SliceSelector | WildcardSelector;
-export declare class BracketedSelection extends JSONPathSelector {
-    readonly environment: JSONPathEnvironment;
-    readonly token: Token;
-    readonly items: BracketedSegment[];
-    constructor(environment: JSONPathEnvironment, token: Token, items: BracketedSegment[]);
-    resolve(nodes: JSONPathNode[]): JSONPathNode[];
-    lazyResolve(nodes: Iterable<JSONPathNode>): Generator<JSONPathNode>;
-    toString(): string;
+    resolve(node: JSONPathNode): JSONPathNode[];
+    lazyResolve(node: JSONPathNode): Generator<JSONPathNode>;
+    toString(options?: SerializationOptions): string;
 }

package/dist/path/serialize.d.ts

@@ -0,0 +1,6 @@
+/** Usable in a quoted path. */
+export declare function toQuoted(name: string): string;
+/** Usable in a normalized path. */
+export declare function toCanonical(name: string): string;
+/** Usable in a shorthand path. */
+export declare function toShorthand(name: string): string | null;

package/dist/path/types.d.ts

@@ -6,7 +6,7 @@ export declare const Nothing: unique symbol;
  */
 export type JSONPathValue = JSONValue | typeof Nothing;
 /**
- * Object passed to FilterExpression.evaluate().
+ * Object passed to `FilterExpression.evaluate()`.
  */
 export type FilterContext = {
     environment: JSONPathEnvironment;
@@ -22,3 +22,25 @@ export declare function hasStringKey(value: unknown, key: string): value is {
     [key: string]: unknown;
 };
 export declare const KEY_MARK = "\u0002";
+/**
+ * Options for serializing paths.
+ */
+export type SerializationOptions = {
+    /**
+     * `pretty` paths always use:
+     *  - shorthand notation rather than dot notation where possible
+     *  - double quotes rather than single quotes for string literals and where shorthand
+     *    notation is not possible
+     *  - short escape sequences for common non-printing characters such as `\n` and `\t`
+     *
+     * `canonical` paths always use:
+     *  - bracket notation for name and wildcard selectors
+     *  - single quotes for name selectors and string literals
+     *  - short escape sequences for common non-printing characters such as `\n` and `\t`
+     *
+     * `canonical` paths will produce a normalized path where available, but cannot be
+     * considered normalized paths if the query does not represent a singular, absolute node.
+     */
+    form: "pretty" | "canonical";
+};
+export declare const defaultSerializationOptions: SerializationOptions;