@jmespath-community/jmespath 1.2.0 → 1.4.0

package/dist/index.d.cts

@@ -0,0 +1,464 @@
+type JSONPrimitive = string | number | boolean | null;
+type JSONValue = JSONPrimitive | JSONObject | JSONArray;
+type JSONObject = Readonly<{
+    [member: string]: JSONValue;
+}>;
+type JSONArray = ReadonlyArray<JSONValue>;
+
+declare enum Token {
+    TOK_EOF = "EOF",
+    TOK_VARIABLE = "Variable",
+    TOK_ASSIGN = "Assign",
+    TOK_UNQUOTEDIDENTIFIER = "UnquotedIdentifier",
+    TOK_QUOTEDIDENTIFIER = "QuotedIdentifier",
+    TOK_RBRACKET = "Rbracket",
+    TOK_RPAREN = "Rparen",
+    TOK_COMMA = "Comma",
+    TOK_COLON = "Colon",
+    TOK_RBRACE = "Rbrace",
+    TOK_NUMBER = "Number",
+    TOK_CURRENT = "Current",
+    TOK_ROOT = "Root",
+    TOK_EXPREF = "Expref",
+    TOK_PIPE = "Pipe",
+    TOK_OR = "Or",
+    TOK_AND = "And",
+    TOK_EQ = "EQ",
+    TOK_GT = "GT",
+    TOK_LT = "LT",
+    TOK_GTE = "GTE",
+    TOK_LTE = "LTE",
+    TOK_NE = "NE",
+    TOK_PLUS = "Plus",
+    TOK_MINUS = "Minus",
+    TOK_MULTIPLY = "Multiply",
+    TOK_DIVIDE = "Divide",
+    TOK_MODULO = "Modulo",
+    TOK_DIV = "Div",
+    TOK_FLATTEN = "Flatten",
+    TOK_STAR = "Star",
+    TOK_FILTER = "Filter",
+    TOK_DOT = "Dot",
+    TOK_NOT = "Not",
+    TOK_LBRACE = "Lbrace",
+    TOK_LBRACKET = "Lbracket",
+    TOK_LPAREN = "Lparen",
+    TOK_LITERAL = "Literal",
+    TOK_QUESTION = "Question"
+}
+type LexerTokenValue = JSONValue;
+interface LexerToken {
+    type: Token;
+    value: LexerTokenValue;
+    start: number;
+}
+interface LexerOptions {
+    enable_legacy_literals?: boolean;
+}
+
+interface FieldNode {
+    readonly type: 'Field';
+    readonly name: string;
+}
+interface LiteralNode {
+    readonly type: 'Literal';
+    readonly value: JSONValue;
+}
+interface IndexNode {
+    readonly type: 'Index';
+    readonly value: number;
+}
+interface FilterProjectionNode {
+    readonly type: 'FilterProjection';
+    readonly left: ExpressionNode;
+    readonly right: ExpressionNode;
+    readonly condition: ExpressionNode;
+}
+interface SliceNode {
+    readonly type: 'Slice';
+    readonly start: number | null;
+    readonly stop: number | null;
+    readonly step: number | null;
+}
+type ComparatorType = 'GT' | 'LT' | 'GTE' | 'LTE' | 'NE' | 'EQ';
+interface ComparatorNode {
+    readonly type: 'Comparator';
+    readonly name: ComparatorType;
+    readonly left: ExpressionNode;
+    readonly right: ExpressionNode;
+}
+interface KeyValuePairNode {
+    readonly type: 'KeyValuePair';
+    readonly name: string;
+    readonly value: ExpressionNode;
+}
+interface MultiSelectHashNode {
+    type: 'MultiSelectHash';
+    children: KeyValuePairNode[];
+}
+interface MultiSelectListNode {
+    type: 'MultiSelectList';
+    children: ExpressionNode[];
+}
+interface FunctionNode {
+    readonly type: 'Function';
+    readonly name: string;
+    readonly children: ExpressionNode[];
+}
+interface LetExpressionNode {
+    readonly type: 'LetExpression';
+    readonly bindings: BindingNode[];
+    readonly expression: ExpressionNode;
+}
+interface BindingNode {
+    readonly type: 'Binding';
+    readonly variable: string;
+    readonly reference: ExpressionNode;
+}
+interface VariableNode {
+    readonly type: 'Variable';
+    readonly name: string;
+}
+interface TernaryNode {
+    readonly type: 'Ternary';
+    readonly condition: ExpressionNode;
+    readonly trueExpr: ExpressionNode;
+    readonly falseExpr: ExpressionNode;
+}
+type BinaryExpressionType = 'AndExpression' | 'IndexExpression' | 'OrExpression' | 'Pipe' | 'Projection' | 'Subexpression' | 'ValueProjection';
+type UnaryExpressionType = 'ExpressionReference' | 'Flatten' | 'NotExpression';
+type SimpleExpressionType = 'Identity' | 'Current' | 'Root';
+interface SimpleExpressionNode<T extends SimpleExpressionType = SimpleExpressionType> {
+    readonly type: T;
+}
+interface UnaryExpressionNode<T extends UnaryExpressionType = UnaryExpressionType> {
+    readonly type: T;
+    readonly child: ExpressionNode;
+}
+type UnaryOperatorType = 'Plus' | 'Minus';
+interface UnaryArithmeticNode {
+    readonly type: 'Unary';
+    readonly operator: UnaryOperatorType;
+    readonly operand: ExpressionNode;
+}
+interface BinaryExpressionNode<T extends BinaryExpressionType = BinaryExpressionType> {
+    readonly type: T;
+    readonly left: ExpressionNode;
+    readonly right: ExpressionNode;
+}
+type BinaryOperatorType = 'Plus' | 'Minus' | 'Multiply' | Token.TOK_STAR | 'Divide' | 'Modulo' | 'Div';
+interface BinaryArithmeticNode {
+    readonly type: 'Arithmetic';
+    readonly operator: BinaryOperatorType;
+    readonly left: ExpressionNode;
+    readonly right: ExpressionNode;
+}
+type ExpressionNode = SimpleExpressionNode | UnaryExpressionNode | UnaryArithmeticNode | BinaryExpressionNode | BinaryArithmeticNode | ComparatorNode | SliceNode | FilterProjectionNode | IndexNode | LiteralNode | FieldNode | MultiSelectHashNode | MultiSelectListNode | FunctionNode | LetExpressionNode | BindingNode | VariableNode | TernaryNode;
+type ExpressionReference = {
+    expref: true;
+} & ExpressionNode;
+
+type ScopeEntry = JSONObject;
+interface Options extends LexerOptions {
+    maxDepth?: number;
+    maxNodes?: number;
+    maxOutputSize?: number;
+    allowedFunctions?: string[];
+    disallowedFunctions?: string[];
+    timeoutMs?: number;
+}
+
+declare enum InputArgument {
+    TYPE_NUMBER = 0,
+    TYPE_ANY = 1,
+    TYPE_STRING = 2,
+    TYPE_ARRAY = 3,
+    TYPE_OBJECT = 4,
+    TYPE_BOOLEAN = 5,
+    TYPE_EXPREF = 6,
+    TYPE_NULL = 7,
+    TYPE_ARRAY_NUMBER = 8,
+    TYPE_ARRAY_STRING = 9,
+    TYPE_ARRAY_OBJECT = 10,
+    TYPE_ARRAY_ARRAY = 11
+}
+interface InputSignature {
+    types: InputArgument[];
+    variadic?: boolean;
+    optional?: boolean;
+}
+type RuntimeFunction<T extends ReadonlyArray<JSONValue | ExpressionNode>, U> = (resolvedArgs: T) => U;
+interface FunctionSignature {
+    _func: RuntimeFunction<any, JSONValue>;
+    _signature: InputSignature[];
+}
+interface FunctionTable {
+    [functionName: string]: FunctionSignature;
+}
+type BuiltInFunctionNames = 'abs' | 'avg' | 'ceil' | 'contains' | 'ends_with' | 'find_first' | 'find_last' | 'floor' | 'from_items' | 'group_by' | 'items' | 'join' | 'keys' | 'length' | 'lower' | 'map' | 'max' | 'max_by' | 'merge' | 'min' | 'min_by' | 'not_null' | 'pad_left' | 'pad_right' | 'replace' | 'reverse' | 'sort' | 'sort_by' | 'split' | 'starts_with' | 'sum' | 'to_array' | 'to_number' | 'to_string' | 'type' | 'upper' | 'values' | 'zip';
+interface RegisterOptions {
+    /**
+     * Allow overriding existing functions. Default: false
+     * When true, replaces existing function without error
+     * When false, throws error if function already exists (backward compatible)
+     */
+    override?: boolean;
+    /**
+     * Emit warning when overriding existing functions. Default: false
+     * Only applies when override is true
+     */
+    warn?: boolean;
+}
+type RegistrationResult = {
+    success: true;
+    message?: string;
+} | {
+    success: false;
+    reason: 'already-exists' | 'invalid-signature' | 'invalid-name';
+    message: string;
+};
+interface FunctionRegistry {
+    /**
+     * Register a new function with optional override behavior
+     */
+    register<T extends string>(name: T extends BuiltInFunctionNames ? never : T, func: RuntimeFunction<(JSONValue | ExpressionNode)[], JSONValue>, signature: InputSignature[], options?: RegisterOptions): RegistrationResult;
+    /**
+     * Unregister a custom function (built-in functions cannot be unregistered)
+     */
+    unregister<T extends string>(name: T extends BuiltInFunctionNames ? never : T): boolean;
+    /**
+     * Check if a function is registered
+     */
+    isRegistered(name: string): boolean;
+    /**
+     * Get list of all registered function names
+     */
+    getRegistered(): string[];
+    /**
+     * Get list of custom (non-built-in) function names
+     */
+    getCustomFunctions(): string[];
+    /**
+     * Clear all custom functions (built-in functions remain)
+     */
+    clearCustomFunctions(): void;
+}
+declare class Runtime implements FunctionRegistry {
+    _interpreter: TreeInterpreter;
+    _functionTable: FunctionTable;
+    private _customFunctions;
+    TYPE_NAME_TABLE: Readonly<{
+        readonly 0: "number";
+        readonly 1: "any";
+        readonly 2: "string";
+        readonly 3: "array";
+        readonly 4: "object";
+        readonly 5: "boolean";
+        readonly 6: "expression";
+        readonly 7: "null";
+        readonly 8: "Array<number>";
+        readonly 10: "Array<object>";
+        readonly 9: "Array<string>";
+        readonly 11: "Array<Array<any>>";
+    }>;
+    constructor(interpreter: TreeInterpreter);
+    private buildFunctionTable;
+    /**
+     * Enhanced registerFunction with backward compatibility and new options
+     * @deprecated Use register() method for enhanced functionality
+     */
+    registerFunction(name: string, customFunction: RuntimeFunction<(JSONValue | ExpressionNode)[], JSONValue>, signature: InputSignature[], options?: RegisterOptions): void;
+    /**
+     * Internal registration method that bypasses TypeScript type checking
+     */
+    private _registerInternal;
+    /**
+     * Register a new function with enhanced options and type safety
+     */
+    register<T extends string>(name: T extends BuiltInFunctionNames ? never : T, customFunction: RuntimeFunction<(JSONValue | ExpressionNode)[], JSONValue>, signature: InputSignature[], options?: RegisterOptions): RegistrationResult;
+    /**
+     * Unregister a custom function (built-in functions cannot be unregistered)
+     */
+    unregister<T extends string>(name: T extends BuiltInFunctionNames ? never : T): boolean;
+    /**
+     * Check if a function is registered
+     */
+    isRegistered(name: string): boolean;
+    /**
+     * Get list of all registered function names
+     */
+    getRegistered(): string[];
+    /**
+     * Get list of custom (non-built-in) function names
+     */
+    getCustomFunctions(): string[];
+    /**
+     * Clear all custom functions (built-in functions remain)
+     */
+    clearCustomFunctions(): void;
+    callFunction(name: string, resolvedArgs: (JSONValue | ExpressionNode)[]): JSONValue;
+    private validateInputSignatures;
+    private validateArgs;
+    private validateArity;
+    private validateTypes;
+    private typeMatches;
+    private getTypeName;
+    createKeyFunction(exprefNode: ExpressionNode, allowedTypes: InputArgument[]): (x: JSONValue) => JSONValue;
+    private functionAvg;
+    private functionContains;
+    private functionEndsWith;
+    private functionFindFirst;
+    private functionFindLast;
+    private createFindFunction;
+    private functionFromItems;
+    private functionGroupBy;
+    private functionItems;
+    private functionJoin;
+    private functionLength;
+    private functionMap;
+    private functionMax;
+    private functionMaxBy;
+    private functionMerge;
+    private functionMin;
+    private functionMinBy;
+    private functionNotNull;
+    private functionPadLeft;
+    private functionPadRight;
+    private createPadFunction;
+    private functionReplace;
+    private functionSplit;
+    private functionReverse;
+    private functionSort;
+    private functionSortBy;
+    private functionStartsWith;
+    private functionSum;
+    private functionToArray;
+    private functionToNumber;
+    private functionToString;
+    private functionTrim;
+    private functionTrimLeft;
+    private functionTrimRight;
+    private createTrimFunction;
+    private functionType;
+    private functionZip;
+}
+
+declare class TreeInterpreter {
+    runtime: Runtime;
+    private _rootValue;
+    private _scope;
+    private _options?;
+    private _depth;
+    private _deadline;
+    constructor(options?: Options);
+    withScope(scope: ScopeEntry): TreeInterpreter;
+    search(node: ExpressionNode, value: JSONValue, options?: Options): JSONValue;
+    private checkOutputSize;
+    private collect;
+    private evaluateProjectionItems;
+    visit(node: ExpressionNode, value: JSONValue | ExpressionNode): JSONValue | ExpressionNode | ExpressionReference;
+    private evaluateNode;
+    computeSliceParams(arrayLength: number, sliceNode: SliceNode): {
+        start: number;
+        stop: number;
+        step: number;
+    };
+    capSliceRange(arrayLength: number, actualValue: number, step: number): number;
+    slice(collection: JSONArray, start: number, end: number, step: number): JSONArray;
+}
+
+type NormalizePath<S extends string> = S extends `${infer Pre}[${infer Idx}]${infer Post}` ? NormalizePath<Pre extends '' ? `${Idx}${Post}` : `${Pre}.${Idx}${Post}`> : S;
+type Split<S extends string> = S extends `${infer Head}.${infer Tail}` ? [Unquote<Head>, ...Split<Tail>] : [Unquote<S>];
+type Unquote<S extends string> = S extends `"${infer Inner}"` ? Inner : S;
+type IsSpecialExpression<P extends string> = P extends `${string}${'|' | '?' | '{' | '(' | '@' | '&' | '+' | '-' | '/' | '%' | '!'}${string}` ? true : false;
+type ResolvePath<T, Segments extends string[]> = Segments extends [
+    infer Head extends string,
+    ...infer Tail extends string[]
+] ? Head extends '*' ? T extends (infer E)[] ? ResolvePath<E, Tail>[] : JSONValue : T extends (infer E)[] ? Head extends `${number}` ? ResolvePath<E, Tail> : JSONValue : T extends object ? Head extends keyof T ? undefined extends T[Head] ? ResolvePath<NonNullable<T[Head]>, Tail> | null : ResolvePath<NonNullable<T[Head]>, Tail> : JSONValue : JSONValue : T;
+type PathValue<T, P extends string> = string extends P ? JSONValue : IsSpecialExpression<P> extends true ? JSONValue : ResolvePath<T, Split<NormalizePath<P>>>;
+
+declare class ScopeChain {
+    private inner?;
+    private data;
+    get currentScopeData(): JSONObject;
+    withScope(data: JSONObject): ScopeChain;
+    getValue(identifier: string): JSONValue;
+}
+
+type StreamSource<T = unknown> = AsyncIterable<T> | Iterable<T> | ReadableStream<T> | NodeJS.ReadableStream;
+interface StreamOptions extends Options {
+    /**
+     * If true, splits string chunks by newline and parses each line as JSON.
+     * If 'auto', detects string lines that look like JSON objects/arrays.
+     * If false, does not parse string chunks.
+     * Defaults to 'auto'.
+     */
+    parseJson?: boolean | 'auto';
+    /**
+     * If true, array chunks emitted by the stream are flattened so their elements
+     * are yielded individually.
+     * Defaults to true.
+     */
+    flattenChunks?: boolean;
+    /**
+     * Maximum number of results to yield before ending stream evaluation early.
+     */
+    limit?: number;
+}
+/**
+ * Incremental Result Streaming evaluation.
+ * Evaluates a JMESPath expression incrementally over an AsyncIterable or ReadableStream source.
+ */
+declare function searchStream<T = JSONValue, D = unknown>(sourceOrExpression: StreamSource<D> | string | ExpressionNode, expressionOrSource: string | ExpressionNode | StreamSource<D>, options?: StreamOptions): AsyncGenerator<T, void, unknown>;
+
+interface ValidationResult {
+    valid: boolean;
+    error?: string;
+    ast?: ExpressionNode;
+}
+
+interface CompiledQuery<T = JSONValue, D = unknown> {
+    (data: D): T;
+    search: (data: D) => T;
+    searchStream: (source: StreamSource<D>, options?: StreamOptions) => AsyncGenerator<T, void, unknown>;
+    ast: ExpressionNode;
+}
+
+declare function compile(expression: string, options?: Options): ExpressionNode;
+declare function compileQuery<T = JSONValue, D = unknown>(expression: string, options?: Options): CompiledQuery<T, D>;
+declare function validate(expression: string, options?: Options): ValidationResult;
+declare function tokenize(expression: string, options?: LexerOptions): LexerToken[];
+declare function search<T, P extends string>(data: T, expression: P, options?: Options): PathValue<T, P>;
+declare function search<T = JSONValue, D = unknown>(data: D, expression: string, options?: Options): T;
+declare function Scope(): ScopeChain;
+declare const jmespath: {
+    compile: typeof compile;
+    compileQuery: typeof compileQuery;
+    searchStream: typeof searchStream;
+    validate: typeof validate;
+    registerFunction: (functionName: string, customFunction: RuntimeFunction<(JSONValue | ExpressionNode)[], JSONValue>, signature: InputSignature[], options?: RegisterOptions) => void;
+    register: <T extends string>(name: T extends BuiltInFunctionNames ? never : T, customFunction: RuntimeFunction<(JSONValue | ExpressionNode)[], JSONValue>, signature: InputSignature[], options?: RegisterOptions) => RegistrationResult;
+    unregisterFunction: <T extends string>(name: T extends BuiltInFunctionNames ? never : T) => boolean;
+    isRegistered: (name: string) => boolean;
+    getRegisteredFunctions: () => string[];
+    getCustomFunctions: () => string[];
+    clearCustomFunctions: () => void;
+    search: typeof search;
+    tokenize: typeof tokenize;
+    TreeInterpreter: TreeInterpreter;
+    TYPE_ANY: InputArgument;
+    TYPE_ARRAY_NUMBER: InputArgument;
+    TYPE_ARRAY_STRING: InputArgument;
+    TYPE_ARRAY: InputArgument;
+    TYPE_BOOLEAN: InputArgument;
+    TYPE_EXPREF: InputArgument;
+    TYPE_NULL: InputArgument;
+    TYPE_NUMBER: InputArgument;
+    TYPE_OBJECT: InputArgument;
+    TYPE_STRING: InputArgument;
+    TYPE_ARRAY_ARRAY: InputArgument;
+    TYPE_ARRAY_OBJECT: InputArgument;
+    Scope: typeof Scope;
+};
+
+export { type BuiltInFunctionNames, type CompiledQuery, type FunctionRegistry, type FunctionSignature, type InputSignature, type JSONArray, type JSONObject, type JSONPrimitive, type JSONValue, type Options, type PathValue, type RegisterOptions, type RegistrationResult, type RuntimeFunction, type StreamOptions, type StreamSource, type ValidationResult, jmespath as default };