json-p3 0.1.0

package/dist/patch/patch.d.ts

@@ -0,0 +1,157 @@
+import { JSONPointer } from "../pointer";
+import { JSONValue } from "../types";
+export type OpObject = {
+    op: string;
+    path: string;
+    value?: JSONValue;
+    from?: string;
+};
+/**
+ * A JSON Patch operation.
+ */
+export interface Op {
+    /**
+     * The patch operation name.
+     */
+    name: string;
+    /**
+     * Apply the patch operation to _value_.
+     * @param value - The target JSON value.
+     */
+    apply: (value: JSONValue, index: number) => JSONValue;
+    /**
+     * A plain object representation of the patch operation.
+     */
+    toObject: () => OpObject;
+}
+/**
+ * The JSON Patch _add_ operation.
+ */
+export declare class OpAdd implements Op {
+    readonly path: JSONPointer;
+    readonly value: JSONValue;
+    name: string;
+    constructor(path: JSONPointer, value: JSONValue);
+    apply(value: JSONValue, index: number): JSONValue;
+    toObject(): OpObject;
+}
+/**
+ * The JSON Patch _remove_ operation.
+ */
+export declare class OpRemove implements Op {
+    readonly path: JSONPointer;
+    name: string;
+    constructor(path: JSONPointer);
+    apply(value: JSONValue, index: number): JSONValue;
+    toObject(): OpObject;
+}
+/**
+ * The JSON Patch _replace_ operation.
+ */
+export declare class OpReplace implements Op {
+    readonly path: JSONPointer;
+    readonly value: JSONValue;
+    name: string;
+    constructor(path: JSONPointer, value: JSONValue);
+    apply(value: JSONValue, index: number): JSONValue;
+    toObject(): OpObject;
+}
+/**
+ * The JSON Patch _move_ operation.
+ */
+export declare class OpMove implements Op {
+    readonly from: JSONPointer;
+    readonly path: JSONPointer;
+    name: string;
+    constructor(from: JSONPointer, path: JSONPointer);
+    apply(value: JSONValue, index: number): JSONValue;
+    toObject(): OpObject;
+}
+/**
+ * The JSON Patch _copy_ operation.
+ */
+export declare class OpCopy implements Op {
+    readonly from: JSONPointer;
+    readonly path: JSONPointer;
+    name: string;
+    constructor(from: JSONPointer, path: JSONPointer);
+    apply(value: JSONValue, index: number): JSONValue;
+    toObject(): OpObject;
+    protected deepCopy(value: JSONValue): JSONValue;
+}
+/**
+ * The JSON Patch _test_ operation.
+ */
+export declare class OpTest implements Op {
+    readonly path: JSONPointer;
+    readonly value: JSONValue;
+    name: string;
+    constructor(path: JSONPointer, value: JSONValue);
+    apply(value: JSONValue, index: number): JSONValue;
+    toObject(): OpObject;
+}
+/**
+ *
+ */
+export declare class JSONPatch {
+    private ops;
+    /**
+     *
+     * @param ops -
+     */
+    constructor(ops?: OpObject[]);
+    /**
+     *
+     * @param path -
+     * @param value -
+     * @returns
+     */
+    add(path: string | JSONPointer, value: JSONValue): this;
+    /**
+     *
+     * @param path -
+     */
+    remove(path: string | JSONPointer): this;
+    /**
+     *
+     * @param path -
+     * @param value -
+     * @returns
+     */
+    replace(path: string | JSONPointer, value: JSONValue): this;
+    /**
+     *
+     * @param from -
+     * @param path -
+     * @returns
+     */
+    move(from: string | JSONPointer, path: string | JSONPointer): this;
+    /**
+     *
+     * @param from -
+     * @param path -
+     * @returns
+     */
+    copy(from: string | JSONPointer, path: string | JSONPointer): this;
+    /**
+     *
+     * @param path -
+     * @param value -
+     * @returns
+     */
+    test(path: string | JSONPointer, value: JSONValue): this;
+    /**
+     *
+     * @param value -
+     */
+    apply(value: JSONValue): JSONValue;
+    /**
+     *
+     * @returns
+     */
+    toArray(): OpObject[];
+    protected build(ops: OpObject[]): void;
+    protected opPointer(opObj: OpObject, key: keyof OpObject, op: string, index: number): JSONPointer;
+    protected opValue(opObj: OpObject, key: keyof OpObject, op: string, index: number): JSONValue;
+    protected ensurePointer(p: JSONPointer | string, op: string, index: number): JSONPointer;
+}

package/dist/path/environment.d.ts

@@ -0,0 +1,60 @@
+import { FilterExpression } from "./expression";
+import { FilterFunction } from "./functions/function";
+import { JSONPathNodeList } from "./node";
+import { JSONPath } from "./path";
+import { Token } from "./token";
+import { JSONValue } from "../types";
+/**
+ *
+ */
+export type JSONPathEnvironmentOptions = {
+    /**
+     *
+     */
+    strict: boolean;
+    /**
+     *
+     */
+    maxIntIndex: number;
+    /**
+     *
+     */
+    minIntIndex: number;
+};
+export declare const defaultOptions: JSONPathEnvironmentOptions;
+/**
+ *
+ */
+export declare class JSONPathEnvironment {
+    readonly options: JSONPathEnvironmentOptions;
+    /**
+     *
+     */
+    filterRegister: Map<string, FilterFunction>;
+    private parser;
+    /**
+     *
+     * @param options -
+     */
+    constructor(options?: JSONPathEnvironmentOptions);
+    /**
+     *
+     * @param path -
+     * @returns
+     */
+    compile(path: string): JSONPath;
+    /**
+     *
+     * @param path -
+     * @param value -
+     * @returns
+     */
+    query(path: string, value: JSONValue): JSONPathNodeList;
+    protected setupFilterFunctions(): void;
+    /**
+     *
+     * @param token -
+     * @param args -
+     */
+    checkWellTypedness(token: Token, args: FilterExpression[]): FilterExpression[];
+}

package/dist/path/errors.d.ts

@@ -0,0 +1,50 @@
+import { Token } from "./token";
+/**
+ * Base class for all JSONPath errors.
+ */
+export declare class JSONPathError extends Error {
+    readonly message: string;
+    readonly token: Token;
+    constructor(message: string, token: Token);
+}
+/**
+ * Error thrown due to unexpected, internal path tokenization problems.
+ */
+export declare class JSONPathLexerError extends JSONPathError {
+    readonly message: string;
+    readonly token: Token;
+    constructor(message: string, token: Token);
+}
+/**
+ * Error thrown due to type errors when evaluating filter expressions.
+ */
+export declare class JSONPathTypeError extends JSONPathError {
+    readonly message: string;
+    readonly token: Token;
+    constructor(message: string, token: Token);
+}
+/**
+ * Error thrown due to out of range indices.
+ */
+export declare class JSONPathIndexError extends JSONPathError {
+    readonly message: string;
+    readonly token: Token;
+    constructor(message: string, token: Token);
+}
+/**
+ * Error thrown when attempting to retrieve a filter function that has not
+ * been registered.
+ */
+export declare class UndefinedFilterFunctionError extends JSONPathError {
+    readonly message: string;
+    readonly token: Token;
+    constructor(message: string, token: Token);
+}
+/**
+ * Error thrown due to syntax errors found during parsing a JSONPath query.
+ */
+export declare class JSONPathSyntaxError extends JSONPathError {
+    readonly message: string;
+    readonly token: Token;
+    constructor(message: string, token: Token);
+}

package/dist/path/expression.d.ts

@@ -0,0 +1,98 @@
+import { JSONPathNodeList } from "./node";
+import { JSONPath } from "./path";
+import { Token } from "./token";
+import { FilterContext } from "./types";
+/**
+ * Base class for all filter expressions.
+ */
+export declare abstract class FilterExpression {
+    readonly token: Token;
+    constructor(token: Token);
+    /**
+     * Evaluate the filter expression in the given context.
+     * @param context - Evaluation context.
+     */
+    abstract evaluate(context: FilterContext): unknown;
+    /**
+     * Return a string representation of the expression.
+     */
+    abstract toString(): string;
+}
+/**
+ * Base class for JSONPath ValueType literals.
+ */
+export declare abstract class FilterExpressionLiteral extends FilterExpression {
+}
+export declare class NullLiteral extends FilterExpressionLiteral {
+    evaluate(): null;
+    toString(): string;
+}
+export declare class BooleanLiteral extends FilterExpressionLiteral {
+    readonly token: Token;
+    readonly value: boolean;
+    constructor(token: Token, value: boolean);
+    evaluate(): boolean;
+    toString(): string;
+}
+export declare class StringLiteral extends FilterExpressionLiteral {
+    readonly token: Token;
+    readonly value: string;
+    constructor(token: Token, value: string);
+    evaluate(): string;
+    toString(): string;
+}
+export declare class NumberLiteral extends FilterExpressionLiteral {
+    readonly token: Token;
+    readonly value: number;
+    constructor(token: Token, value: number);
+    evaluate(): number;
+    toString(): string;
+}
+export declare class PrefixExpression extends FilterExpression {
+    readonly token: Token;
+    readonly operator: string;
+    readonly right: FilterExpression;
+    constructor(token: Token, operator: string, right: FilterExpression);
+    evaluate(context: FilterContext): boolean;
+    toString(): string;
+}
+export declare class InfixExpression extends FilterExpression {
+    readonly token: Token;
+    readonly left: FilterExpression;
+    readonly operator: string;
+    readonly right: FilterExpression;
+    constructor(token: Token, left: FilterExpression, operator: string, right: FilterExpression);
+    evaluate(context: FilterContext): boolean;
+    toString(): string;
+}
+export declare class LogicalExpression extends FilterExpression {
+    readonly token: Token;
+    readonly expression: FilterExpression;
+    constructor(token: Token, expression: FilterExpression);
+    evaluate(context: FilterContext): boolean;
+    toString(): string;
+}
+/**
+ * Base class for relative and absolute JSONPath query expressions.
+ */
+export declare abstract class JSONPathQuery extends FilterExpression {
+    readonly token: Token;
+    readonly path: JSONPath;
+    constructor(token: Token, path: JSONPath);
+}
+export declare class RelativeQuery extends JSONPathQuery {
+    evaluate(context: FilterContext): JSONPathNodeList;
+    toString(): string;
+}
+export declare class RootQuery extends JSONPathQuery {
+    evaluate(context: FilterContext): JSONPathNodeList;
+    toString(): string;
+}
+export declare class FunctionExtension extends FilterExpression {
+    readonly token: Token;
+    readonly name: string;
+    readonly args: FilterExpression[];
+    constructor(token: Token, name: string, args: FilterExpression[]);
+    evaluate(context: FilterContext): unknown;
+    toString(): string;
+}

package/dist/path/functions/count.d.ts

@@ -0,0 +1,7 @@
+import { JSONPathNodeList } from "../node";
+import { FilterFunction, FunctionExpressionType } from "./function";
+export declare class Count implements FilterFunction {
+    readonly argTypes: FunctionExpressionType[];
+    readonly returnType = FunctionExpressionType.ValueType;
+    call(nodes: JSONPathNodeList): number;
+}

package/dist/path/functions/function.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The type of a JSONPath filter function parameter or return value, as
+ * described in See section 2.4.1 of draft-ietf-jsonpath-base-20.
+ */
+export declare enum FunctionExpressionType {
+    ValueType = "ValueType",
+    LogicalType = "LogicalType",
+    NodesType = "NodesType"
+}
+/**
+ * A JSONPath filter function definition.
+ */
+export interface FilterFunction {
+    /**
+     * Argument types expected by the filter function.
+     */
+    argTypes: FunctionExpressionType[];
+    /**
+     * The type of the value returned by the filter function.
+     */
+    returnType: FunctionExpressionType;
+    /**
+     * A function with unknown number and type of arguments.
+     */
+    call(...args: unknown[]): unknown;
+}

package/dist/path/functions/index.d.ts

@@ -0,0 +1,7 @@
+export { Count } from "./count";
+export { Length } from "./length";
+export { Match } from "./match";
+export { Search } from "./search";
+export { Value } from "./value";
+export { FunctionExpressionType } from "./function";
+export type { FilterFunction } from "./function";

package/dist/path/functions/length.d.ts

@@ -0,0 +1,7 @@
+import { FilterFunction, FunctionExpressionType } from "./function";
+import { Nothing } from "../types";
+export declare class Length implements FilterFunction {
+    readonly argTypes: FunctionExpressionType[];
+    readonly returnType = FunctionExpressionType.ValueType;
+    call(value: unknown): number | typeof Nothing;
+}

package/dist/path/functions/match.d.ts

@@ -0,0 +1,24 @@
+import { FilterFunction, FunctionExpressionType } from "./function";
+export type MatchFilterFunctionOptions = {
+    /**
+     * The maximum number of regular expressions to cache.
+     */
+    cacheSize?: number;
+    /**
+     * If _true_, throw errors from regex construction and matching.
+     * The standard and default behavior is to ignore these errors
+     * and return _false_.
+     */
+    throwErrors?: boolean;
+};
+export declare class Match implements FilterFunction {
+    #private;
+    readonly options: MatchFilterFunctionOptions;
+    readonly argTypes: FunctionExpressionType[];
+    readonly returnType = FunctionExpressionType.LogicalType;
+    readonly cacheSize: number;
+    readonly throwErrors: boolean;
+    constructor(options?: MatchFilterFunctionOptions);
+    call(s: string, pattern: string): boolean;
+    protected fullMatch(pattern: string): string;
+}

package/dist/path/functions/search.d.ts

@@ -0,0 +1,24 @@
+import { FilterFunction, FunctionExpressionType } from "./function";
+export type SearchFilterFunctionOptions = {
+    /**
+     * The maximum number of regular expressions to cache. Defaults
+     * to 10.
+     */
+    cacheSize?: number;
+    /**
+     * If _true_, throw errors from regex construction and matching.
+     * The standard and default behavior is to ignore these errors
+     * and return _false_.
+     */
+    throwErrors?: boolean;
+};
+export declare class Search implements FilterFunction {
+    #private;
+    readonly options: SearchFilterFunctionOptions;
+    readonly argTypes: FunctionExpressionType[];
+    readonly returnType = FunctionExpressionType.LogicalType;
+    readonly cacheSize: number;
+    readonly throwErrors: boolean;
+    constructor(options?: SearchFilterFunctionOptions);
+    call(s: string, pattern: string): boolean;
+}

package/dist/path/functions/value.d.ts

@@ -0,0 +1,7 @@
+import { JSONPathNodeList } from "../node";
+import { FilterFunction, FunctionExpressionType } from "./function";
+export declare class Value implements FilterFunction {
+    readonly argTypes: FunctionExpressionType[];
+    readonly returnType = FunctionExpressionType.ValueType;
+    call(nodes: JSONPathNodeList): unknown;
+}

package/dist/path/index.d.ts

@@ -0,0 +1,46 @@
+import { JSONValue } from "../types";
+import { JSONPathEnvironment } from "./environment";
+import { JSONPathNodeList } from "./node";
+import { JSONPath } from "./path";
+export { JSONPathEnvironment } from "./environment";
+export type { JSONPathEnvironmentOptions } from "./environment";
+export { JSONPath } from "./path";
+export { JSONPathNodeList, JSONPathNode } from "./node";
+export { Token, TokenKind } from "./token";
+export * as selectors from "./selectors";
+export * as expressions from "./expression";
+export * as functions from "./functions";
+export { FunctionExpressionType } from "./functions";
+export type { FilterFunction } from "./functions";
+export { JSONPathError, JSONPathIndexError, JSONPathLexerError, JSONPathSyntaxError, JSONPathTypeError, } from "./errors";
+export { Nothing } from "./types";
+export type { JSONPathValue, FilterContext } from "./types";
+export declare const DEFAULT_ENVIRONMENT: JSONPathEnvironment;
+/**
+ * Query JSON value _value_ with JSONPath expression _path_.
+ * @param path - A JSONPath expression/query.
+ * @param value - The JSON-like value the JSONPath query is applied to.
+ * @returns A list of JSONPathNode objects, one for each value matched
+ *  by _path_ in _value_.
+ *
+ * @throws {@link JSONPathSyntaxError}
+ * If the path does not conform to standard syntax.
+ *
+ * @throws {@link JSONPathTypeError}
+ * If filter function arguments are invalid, or filter expression are
+ * used in an invalid way.
+ */
+export declare function query(path: string, value: JSONValue): JSONPathNodeList;
+/**
+ * Compile JSONPath _path_ for later use.
+ * @param path - A JSONPath expression/query.
+ * @returns A path object with a `query()` method.
+ *
+ * @throws {@link JSONPathSyntaxError}
+ * If the path does not conform to standard syntax.
+ *
+ * @throws {@link JSONPathTypeError}
+ * If filter function arguments are invalid, or filter expression are
+ * used in an invalid way.
+ */
+export declare function compile(path: string): JSONPath;

package/dist/path/lex.d.ts

@@ -0,0 +1,65 @@
+import { Token, TokenKind } from "./token";
+/**
+ * JSONPath lexical scanner.
+ *
+ * Lexer state is shared between this class and the current state function. A
+ * new _Lexer_ instance is automatically created every time a path is tokenized.
+ *
+ * Use {@link tokenize} to get an array of {@link Token}'s for a JSONPath query.
+ */
+declare class Lexer {
+    #private;
+    readonly path: string;
+    /**
+     * Filter nesting level.
+     */
+    filterLevel: number;
+    /**
+     * A running count of parentheses for each, possibly nested, function call.
+     *
+     * If the stack is empty, we are not in a function call. Remember that
+     * function arguments can use arbitrarily nested in parentheses.
+     */
+    parenStack: number[];
+    /** Tokens resulting from tokenizing a JSONPath query. */
+    tokens: Token[];
+    /**
+     * @param path - A JSONPath query.
+     */
+    constructor(path: string);
+    get pos(): number;
+    get start(): number;
+    run(): void;
+    emit(t: TokenKind): void;
+    next(): string;
+    ignore(): void;
+    backup(): void;
+    peek(): string;
+    accept(valid: Set<string>): boolean;
+    acceptMatch(pattern: RegExp): boolean;
+    acceptRun(valid: Set<string>): boolean;
+    acceptMatchRun(pattern: RegExp): boolean;
+    ignoreWhitespace(): boolean;
+    error(msg: string): void;
+}
+/**
+ * Return a lexer for _path_ and an array to be populated with Tokens.
+ *
+ * `lexer.run()` must be called to populate the returned tokens array.
+ *
+ * You probably want to use {@link tokenize} instead of _lex_. This function
+ * is mostly for internal use, where we want to test the state of the returned
+ * _lexer_ after tokens have been populated.
+ *
+ * @param path - A JSONPath query.
+ * @returns A two-tuple containing a lexer for _path_ and an array to populate
+ * with tokens.
+ */
+export declare function lex(path: string): [Lexer, Token[]];
+/**
+ * Scan _path_ and return an array of tokens to be parsed by the parser.
+ * @param path - A JSONPath query.
+ * @returns Tokens to be parsed by the parser.
+ */
+export declare function tokenize(path: string): Token[];
+export {};

package/dist/path/lru_cache.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A Least Recently Used cache, implemented as an extended Map.
+ */
+export declare class LRUCache<K, V> extends Map<K, V> {
+    readonly maxSize: number;
+    constructor(maxSize?: number, entries?: Iterable<[K, V]>);
+    get(key: K): V | undefined;
+    set(key: K, value: V): this;
+    first(): any;
+}

package/dist/path/node.d.ts

@@ -0,0 +1,74 @@
+import { JSONPointer } from "../pointer";
+import { JSONValue } from "../types";
+/**
+ * The pair of a JSON value and its location found in the target JSON value.
+ */
+export declare class JSONPathNode {
+    readonly value: JSONValue;
+    readonly location: Array<string | number>;
+    readonly root: JSONValue;
+    /**
+     * The normalized path to this node in the target JSON value.
+     */
+    readonly path: string;
+    /**
+     * @param value - The JSON value found at _location_.
+     * @param location - The parts of a normalized path to _value_.
+     * @param root - The target value at the top of the JSON node tree.
+     */
+    constructor(value: JSONValue, location: Array<string | number>, root: JSONValue);
+    /**
+     * Return this node's location as a {@link JSONPointer}.
+     */
+    toPointer(): JSONPointer;
+}
+/**
+ *
+ */
+export declare class JSONPathNodeList {
+    readonly nodes: JSONPathNode[];
+    constructor(nodes: JSONPathNode[]);
+    /**
+     * @returns an iterator over nodes in the list.
+     */
+    [Symbol.iterator](): Iterator<JSONPathNode>;
+    /**
+     * @returns `true` if the node list is empty.
+     */
+    empty(): boolean;
+    /**
+     * @returns An array containing the values at each node in the list.
+     *
+     * @see {@link valuesOrSingular} to unpack the array if there is only
+     * one node in the list.
+     */
+    values(): JSONValue[];
+    /**
+     * Like {@link values}, but returns the node's value is there is only one
+     * node in the list.
+     */
+    valuesOrSingular(): JSONValue;
+    /**
+     * @returns An array of locations for each node in the node list.
+     *
+     * A location is an array of property names and array indices that were
+     * required to reach the node's value in the target JSON value.
+     */
+    locations(): Array<Array<string | number>>;
+    /**
+     * @returns An array of normalized path strings for each node in the list.
+     *
+     * A normalized path contains only property name and index selectors, and
+     * always uses bracketed segments, never shorthand selectors.
+     */
+    paths(): string[];
+    /**
+     * @returns An array of {@link JSONPointer} instances, one for each node
+     * in the list.
+     */
+    pointers(): JSONPointer[];
+    /**
+     * @returns The number of nodes in the node list.
+     */
+    get length(): number;
+}