json-p3/dist/path/environment.d.ts

JSONPath, JSON Pointer and JSON Patch

import { FilterExpression } from "./expression";
import { FilterFunction } from "./functions/function";
import { JSONPathNode, JSONPathNodeList } from "./node";
import { JSONPathQuery } from "./path";
import { Token } from "./token";
import { JSONValue } from "../types";
/**
 * JSONPath environment options. The defaults are in compliance with JSONPath
 * standards.
 */
export type JSONPathEnvironmentOptions = {
    /**
     * Indicates if the environment should to be strict about its compliance with
     * RFC 9535.
     *
     * Defaults to `true`. Setting `strict` to `false` enables non-standard
     * features. Non-standard features are subject to change if conflicting
     * features are included in a future JSONPath standard or draft standard, or
     * an overwhelming consensus amongst the JSONPath community emerges that
     * differs from this implementation.
     */
    strict?: boolean;
    /**
     * The maximum number allowed when indexing or slicing an array. Defaults to
     * 2**53 -1.
     */
    maxIntIndex?: number;
    /**
     * The minimum number allowed when indexing or slicing an array. Defaults to
     * -(2**53) -1.
     */
    minIntIndex?: number;
    /**
     * The maximum number of objects and/or arrays the recursive descent selector
     * can visit before a `JSONPathRecursionLimitError` is thrown.
     */
    maxRecursionDepth?: number;
    /**
     * If `true`, enable nondeterministic ordering when iterating JSON object data.
     *
     * This is mainly useful for validating the JSONPath Compliance Test Suite.
     */
    nondeterministic?: boolean;
    /**
     * The pattern to use for the non-standard _keys selector_.
     *
     * The lexer expects the sticky bit to be set. Defaults to `/~/y`.
     */
    keysPattern?: RegExp;
};
/**
 * A configuration object from which JSONPath queries can be evaluated.
 *
 * An environment is where you'd register custom function extensions or set
 * the maximum recursion depth limit, for example.
 */
export declare class JSONPathEnvironment {
    /**
     * Indicates if the environment should to be strict about its compliance with
     * JSONPath standards.
     *
     * Defaults to `true`. Setting `strict` to `false` currently has no effect.
     * If/when we add non-standard features, the environment's strictness will
     * control their availability.
     */
    readonly strict: boolean;
    /**
     * The maximum number allowed when indexing or slicing an array. Defaults to
     * 2**53 -1.
     */
    readonly maxIntIndex: number;
    /**
     * The minimum number allowed when indexing or slicing an array. Defaults to
     * -(2**53) -1.
     */
    readonly minIntIndex: number;
    /**
     * The maximum number of objects and/or arrays the recursive descent selector
     * can visit before a `JSONPathRecursionLimitError` is thrown.
     */
    readonly maxRecursionDepth: number;
    /**
     * If `true`, enable nondeterministic ordering when iterating JSON object data.
     */
    readonly nondeterministic: boolean;
    /**
     * The pattern to use for the non-standard _keys selector_.
     */
    readonly keysPattern: RegExp;
    /**
     * A map of function names to objects implementing the {@link FilterFunction}
     * interface. You are free to set or delete custom filter functions directly.
     */
    functionRegister: Map<string, FilterFunction>;
    private parser;
    /**
     * @param options - Environment configuration options.
     */
    constructor(options?: JSONPathEnvironmentOptions);
    /**
     * @param path - A JSONPath query to parse.
     * @returns A new {@link JSONPathQuery} object, bound to this environment.
     */
    compile(path: string): JSONPathQuery;
    /**
     *
     * @param path - A JSONPath query to parse and evaluate against _value_.
     * @param value - Data to which _path_ will be applied.
     * @returns The {@link JSONPathNodeList} resulting from applying _path_
     * to _value_.
     */
    query(path: string, value: JSONValue): JSONPathNodeList;
    /**
     * A lazy version of {@link query} which is faster and more memory
     * efficient when querying some large datasets.
     *
     * @param path - A JSONPath query to parse and evaluate against _value_.
     * @param value - Data to which _path_ will be applied.
     * @returns A sequence of {@link JSONPathNode} objects resulting from
     * applying _path_ to _value_.
     */
    lazyQuery(path: string, value: JSONValue): IterableIterator<JSONPathNode>;
    /**
     * Return a {@link JSONPathNode} instance for the first object found in
     * _value_ matching _path_.
     *
     * @param path - A JSONPath query.
     * @param value - JSON-like data to which the query _path_ will be applied.
     * @returns The first node in _value_ matching  _path_, or `undefined` if
     * there are no matches.
     */
    match(path: string, value: JSONValue): JSONPathNode | undefined;
    /**
     * A hook for setting up the function register. You are encouraged to
     * override this method in classes extending `JSONPathEnvironment`.
     */
    protected setupFilterFunctions(): void;
    /**
     * Check the well-typedness of a function's arguments at compile-time.
     *
     * 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.
     *
     * Override this if you want to deviate from the JSONPath Spec's function
     * extension type system.
     *
     * @param token - The {@link Token} starting the function call. `Token.value`
     * will contain the name of the function.
     * @param args - One {@link FilterExpression} for each argument.
     */
    checkWellTypedness(token: Token, args: FilterExpression[]): FilterExpression[];
    /**
     * Return an array of key/values of the enumerable properties in _obj_.
     *
     * If you want to introduce some nondeterminism to iterating JSON-like
     * objects, do it here. The wildcard selector, descendent segment and
     * filter selector all use `this.environment.entries`.
     *
     * @param obj - A JSON-like object.
     */
    entries(obj: {
        [key: string]: JSONValue;
    }): Array<[string, JSONValue]>;
}