@jmespath-community/jmespath 1.3.0 → 1.4.0

package/dist/index.d.cts

@@ -1,9 +1,9 @@
 type JSONPrimitive = string | number | boolean | null;
 type JSONValue = JSONPrimitive | JSONObject | JSONArray;
-type JSONObject = {
+type JSONObject = Readonly<{
     [member: string]: JSONValue;
-};
-type JSONArray = JSONValue[];
+}>;
+type JSONArray = ReadonlyArray<JSONValue>;
 
 declare enum Token {
     TOK_EOF = "EOF",
@@ -159,7 +159,14 @@ type ExpressionReference = {
 } & ExpressionNode;
 
 type ScopeEntry = JSONObject;
-type Options = LexerOptions;
+interface Options extends LexerOptions {
+    maxDepth?: number;
+    maxNodes?: number;
+    maxOutputSize?: number;
+    allowedFunctions?: string[];
+    disallowedFunctions?: string[];
+    timeoutMs?: number;
+}
 
 declare enum InputArgument {
     TYPE_NUMBER = 0,
@@ -180,7 +187,7 @@ interface InputSignature {
     variadic?: boolean;
     optional?: boolean;
 }
-type RuntimeFunction<T extends (JSONValue | ExpressionNode)[], U> = (resolvedArgs: T) => U;
+type RuntimeFunction<T extends ReadonlyArray<JSONValue | ExpressionNode>, U> = (resolvedArgs: T) => U;
 interface FunctionSignature {
     _func: RuntimeFunction<any, JSONValue>;
     _signature: InputSignature[];
@@ -237,7 +244,7 @@ interface FunctionRegistry {
     clearCustomFunctions(): void;
 }
 declare class Runtime implements FunctionRegistry {
-    _interpreter: TreeInterpreter$1;
+    _interpreter: TreeInterpreter;
     _functionTable: FunctionTable;
     private _customFunctions;
     TYPE_NAME_TABLE: Readonly<{
@@ -254,7 +261,7 @@ declare class Runtime implements FunctionRegistry {
         readonly 9: "Array<string>";
         readonly 11: "Array<Array<any>>";
     }>;
-    constructor(interpreter: TreeInterpreter$1);
+    constructor(interpreter: TreeInterpreter);
     private buildFunctionTable;
     /**
      * Enhanced registerFunction with backward compatibility and new options
@@ -336,14 +343,21 @@ declare class Runtime implements FunctionRegistry {
     private functionZip;
 }
 
-declare class TreeInterpreter$1 {
+declare class TreeInterpreter {
     runtime: Runtime;
     private _rootValue;
     private _scope;
-    constructor();
-    withScope(scope: ScopeEntry): TreeInterpreter$1;
-    search(node: ExpressionNode, value: JSONValue): JSONValue;
+    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;
@@ -353,6 +367,16 @@ declare class TreeInterpreter$1 {
     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;
@@ -361,32 +385,57 @@ declare class ScopeChain {
     getValue(identifier: string): JSONValue;
 }
 
-declare const TYPE_ANY = InputArgument.TYPE_ANY;
-declare const TYPE_ARRAY = InputArgument.TYPE_ARRAY;
-declare const TYPE_ARRAY_ARRAY = InputArgument.TYPE_ARRAY_ARRAY;
-declare const TYPE_ARRAY_NUMBER = InputArgument.TYPE_ARRAY_NUMBER;
-declare const TYPE_ARRAY_OBJECT = InputArgument.TYPE_ARRAY_OBJECT;
-declare const TYPE_ARRAY_STRING = InputArgument.TYPE_ARRAY_STRING;
-declare const TYPE_BOOLEAN = InputArgument.TYPE_BOOLEAN;
-declare const TYPE_EXPREF = InputArgument.TYPE_EXPREF;
-declare const TYPE_NULL = InputArgument.TYPE_NULL;
-declare const TYPE_NUMBER = InputArgument.TYPE_NUMBER;
-declare const TYPE_OBJECT = InputArgument.TYPE_OBJECT;
-declare const TYPE_STRING = InputArgument.TYPE_STRING;
+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 const registerFunction: (functionName: string, customFunction: RuntimeFunction<(JSONValue | ExpressionNode)[], JSONValue>, signature: InputSignature[], options?: RegisterOptions) => void;
-declare const register: <T extends string>(name: T extends BuiltInFunctionNames ? never : T, customFunction: RuntimeFunction<(JSONValue | ExpressionNode)[], JSONValue>, signature: InputSignature[], options?: RegisterOptions) => RegistrationResult;
-declare const unregisterFunction: <T extends string>(name: T extends BuiltInFunctionNames ? never : T) => boolean;
-declare const isRegistered: (name: string) => boolean;
-declare const getRegisteredFunctions: () => string[];
-declare const getCustomFunctions: () => string[];
-declare const clearCustomFunctions: () => void;
-declare function search(data: JSONValue, expression: string, options?: Options): JSONValue;
+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 TreeInterpreter: TreeInterpreter$1;
 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;
@@ -396,7 +445,7 @@ declare const jmespath: {
     clearCustomFunctions: () => void;
     search: typeof search;
     tokenize: typeof tokenize;
-    TreeInterpreter: TreeInterpreter$1;
+    TreeInterpreter: TreeInterpreter;
     TYPE_ANY: InputArgument;
     TYPE_ARRAY_NUMBER: InputArgument;
     TYPE_ARRAY_STRING: InputArgument;
@@ -407,6 +456,9 @@ declare const jmespath: {
     TYPE_NUMBER: InputArgument;
     TYPE_OBJECT: InputArgument;
     TYPE_STRING: InputArgument;
+    TYPE_ARRAY_ARRAY: InputArgument;
+    TYPE_ARRAY_OBJECT: InputArgument;
+    Scope: typeof Scope;
 };
 
-export { type BuiltInFunctionNames, type FunctionRegistry, type FunctionSignature, type InputSignature, type JSONArray, type JSONObject, type JSONPrimitive, type JSONValue, type Options, type RegisterOptions, type RegistrationResult, type RuntimeFunction, Scope, TYPE_ANY, TYPE_ARRAY, TYPE_ARRAY_ARRAY, TYPE_ARRAY_NUMBER, TYPE_ARRAY_OBJECT, TYPE_ARRAY_STRING, TYPE_BOOLEAN, TYPE_EXPREF, TYPE_NULL, TYPE_NUMBER, TYPE_OBJECT, TYPE_STRING, TreeInterpreter, clearCustomFunctions, compile, jmespath as default, getCustomFunctions, getRegisteredFunctions, isRegistered, jmespath, register, registerFunction, search, tokenize, unregisterFunction };
+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 };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 type JSONPrimitive = string | number | boolean | null;
 type JSONValue = JSONPrimitive | JSONObject | JSONArray;
-type JSONObject = {
+type JSONObject = Readonly<{
     [member: string]: JSONValue;
-};
-type JSONArray = JSONValue[];
+}>;
+type JSONArray = ReadonlyArray<JSONValue>;
 
 declare enum Token {
     TOK_EOF = "EOF",
@@ -159,7 +159,14 @@ type ExpressionReference = {
 } & ExpressionNode;
 
 type ScopeEntry = JSONObject;
-type Options = LexerOptions;
+interface Options extends LexerOptions {
+    maxDepth?: number;
+    maxNodes?: number;
+    maxOutputSize?: number;
+    allowedFunctions?: string[];
+    disallowedFunctions?: string[];
+    timeoutMs?: number;
+}
 
 declare enum InputArgument {
     TYPE_NUMBER = 0,
@@ -180,7 +187,7 @@ interface InputSignature {
     variadic?: boolean;
     optional?: boolean;
 }
-type RuntimeFunction<T extends (JSONValue | ExpressionNode)[], U> = (resolvedArgs: T) => U;
+type RuntimeFunction<T extends ReadonlyArray<JSONValue | ExpressionNode>, U> = (resolvedArgs: T) => U;
 interface FunctionSignature {
     _func: RuntimeFunction<any, JSONValue>;
     _signature: InputSignature[];
@@ -237,7 +244,7 @@ interface FunctionRegistry {
     clearCustomFunctions(): void;
 }
 declare class Runtime implements FunctionRegistry {
-    _interpreter: TreeInterpreter$1;
+    _interpreter: TreeInterpreter;
     _functionTable: FunctionTable;
     private _customFunctions;
     TYPE_NAME_TABLE: Readonly<{
@@ -254,7 +261,7 @@ declare class Runtime implements FunctionRegistry {
         readonly 9: "Array<string>";
         readonly 11: "Array<Array<any>>";
     }>;
-    constructor(interpreter: TreeInterpreter$1);
+    constructor(interpreter: TreeInterpreter);
     private buildFunctionTable;
     /**
      * Enhanced registerFunction with backward compatibility and new options
@@ -336,14 +343,21 @@ declare class Runtime implements FunctionRegistry {
     private functionZip;
 }
 
-declare class TreeInterpreter$1 {
+declare class TreeInterpreter {
     runtime: Runtime;
     private _rootValue;
     private _scope;
-    constructor();
-    withScope(scope: ScopeEntry): TreeInterpreter$1;
-    search(node: ExpressionNode, value: JSONValue): JSONValue;
+    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;
@@ -353,6 +367,16 @@ declare class TreeInterpreter$1 {
     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;
@@ -361,32 +385,57 @@ declare class ScopeChain {
     getValue(identifier: string): JSONValue;
 }
 
-declare const TYPE_ANY = InputArgument.TYPE_ANY;
-declare const TYPE_ARRAY = InputArgument.TYPE_ARRAY;
-declare const TYPE_ARRAY_ARRAY = InputArgument.TYPE_ARRAY_ARRAY;
-declare const TYPE_ARRAY_NUMBER = InputArgument.TYPE_ARRAY_NUMBER;
-declare const TYPE_ARRAY_OBJECT = InputArgument.TYPE_ARRAY_OBJECT;
-declare const TYPE_ARRAY_STRING = InputArgument.TYPE_ARRAY_STRING;
-declare const TYPE_BOOLEAN = InputArgument.TYPE_BOOLEAN;
-declare const TYPE_EXPREF = InputArgument.TYPE_EXPREF;
-declare const TYPE_NULL = InputArgument.TYPE_NULL;
-declare const TYPE_NUMBER = InputArgument.TYPE_NUMBER;
-declare const TYPE_OBJECT = InputArgument.TYPE_OBJECT;
-declare const TYPE_STRING = InputArgument.TYPE_STRING;
+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 const registerFunction: (functionName: string, customFunction: RuntimeFunction<(JSONValue | ExpressionNode)[], JSONValue>, signature: InputSignature[], options?: RegisterOptions) => void;
-declare const register: <T extends string>(name: T extends BuiltInFunctionNames ? never : T, customFunction: RuntimeFunction<(JSONValue | ExpressionNode)[], JSONValue>, signature: InputSignature[], options?: RegisterOptions) => RegistrationResult;
-declare const unregisterFunction: <T extends string>(name: T extends BuiltInFunctionNames ? never : T) => boolean;
-declare const isRegistered: (name: string) => boolean;
-declare const getRegisteredFunctions: () => string[];
-declare const getCustomFunctions: () => string[];
-declare const clearCustomFunctions: () => void;
-declare function search(data: JSONValue, expression: string, options?: Options): JSONValue;
+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 TreeInterpreter: TreeInterpreter$1;
 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;
@@ -396,7 +445,7 @@ declare const jmespath: {
     clearCustomFunctions: () => void;
     search: typeof search;
     tokenize: typeof tokenize;
-    TreeInterpreter: TreeInterpreter$1;
+    TreeInterpreter: TreeInterpreter;
     TYPE_ANY: InputArgument;
     TYPE_ARRAY_NUMBER: InputArgument;
     TYPE_ARRAY_STRING: InputArgument;
@@ -407,6 +456,9 @@ declare const jmespath: {
     TYPE_NUMBER: InputArgument;
     TYPE_OBJECT: InputArgument;
     TYPE_STRING: InputArgument;
+    TYPE_ARRAY_ARRAY: InputArgument;
+    TYPE_ARRAY_OBJECT: InputArgument;
+    Scope: typeof Scope;
 };
 
-export { type BuiltInFunctionNames, type FunctionRegistry, type FunctionSignature, type InputSignature, type JSONArray, type JSONObject, type JSONPrimitive, type JSONValue, type Options, type RegisterOptions, type RegistrationResult, type RuntimeFunction, Scope, TYPE_ANY, TYPE_ARRAY, TYPE_ARRAY_ARRAY, TYPE_ARRAY_NUMBER, TYPE_ARRAY_OBJECT, TYPE_ARRAY_STRING, TYPE_BOOLEAN, TYPE_EXPREF, TYPE_NULL, TYPE_NUMBER, TYPE_OBJECT, TYPE_STRING, TreeInterpreter, clearCustomFunctions, compile, jmespath as default, getCustomFunctions, getRegisteredFunctions, isRegistered, jmespath, register, registerFunction, search, tokenize, unregisterFunction };
+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 };