@codehz/json-expr 0.4.0 → 0.5.1

package/dist/index.d.mts

@@ -11,14 +11,85 @@ type ProxyExpression<T = unknown> = {
  * 参数可以是原始值或对应的 Proxy
  */
 type ProxifyArgs<T extends unknown[]> = { [K in keyof T]: T[K] | Proxify<T[K]> };
+/**
+ * 需要特殊处理的数组方法名（有泛型参数，需要显式定义以保留类型推导）
+ */
+type ProxifiedArrayMethods = "map" | "flatMap" | "filter" | "reduce" | "reduceRight" | "find" | "findIndex" | "findLast" | "findLastIndex" | "every" | "some" | "forEach" | "toSorted" | "sort";
+/**
+ * 字符串类型的 Proxify 版本
+ * 将所有字符串方法返回值包装为 Proxify
+ * 参数允许为 Proxy 或原始值
+ */
+type ProxifiedString = {
+  charAt(pos: number | Proxify<number>): Proxify<string>;
+  charCodeAt(index: number | Proxify<number>): Proxify<number>;
+  concat(...strings: (string | Proxify<string>)[]): Proxify<string>;
+  indexOf(searchString: string | Proxify<string>, position?: number | Proxify<number>): Proxify<number>;
+  lastIndexOf(searchString: string | Proxify<string>, position?: number | Proxify<number>): Proxify<number>;
+  localeCompare(that: string | Proxify<string>): Proxify<number>;
+  match(regexp: string | RegExp | Proxify<string> | Proxify<RegExp>): Proxify<RegExpMatchArray | null>;
+  replace(searchValue: string | RegExp | Proxify<string> | Proxify<RegExp>, replaceValue: string | Proxify<string> | Proxify<(substring: string, ...args: unknown[]) => string>): Proxify<string>;
+  replaceAll(searchValue: string | RegExp | Proxify<string> | Proxify<RegExp>, replaceValue: string | Proxify<string> | Proxify<(substring: string, ...args: unknown[]) => string>): Proxify<string>;
+  search(regexp: string | RegExp | Proxify<string> | Proxify<RegExp>): Proxify<number>;
+  slice(start?: number | Proxify<number>, end?: number | Proxify<number>): Proxify<string>;
+  split(separator: string | RegExp | Proxify<string> | Proxify<RegExp>, limit?: number | Proxify<number>): Proxify<string[]>;
+  substring(start: number | Proxify<number>, end?: number | Proxify<number>): Proxify<string>;
+  toLowerCase(): Proxify<string>;
+  toLocaleLowerCase(): Proxify<string>;
+  toUpperCase(): Proxify<string>;
+  toLocaleUpperCase(): Proxify<string>;
+  trim(): Proxify<string>;
+  trimStart(): Proxify<string>;
+  trimEnd(): Proxify<string>;
+  padStart(maxLength: number | Proxify<number>, fillString?: string | Proxify<string>): Proxify<string>;
+  padEnd(maxLength: number | Proxify<number>, fillString?: string | Proxify<string>): Proxify<string>;
+  repeat(count: number | Proxify<number>): Proxify<string>;
+  startsWith(searchString: string | Proxify<string>, position?: number | Proxify<number>): Proxify<boolean>;
+  endsWith(searchString: string | Proxify<string>, endPosition?: number | Proxify<number>): Proxify<boolean>;
+  includes(searchString: string | Proxify<string>, position?: number | Proxify<number>): Proxify<boolean>;
+  at(index: number | Proxify<number>): Proxify<string | undefined>;
+  codePointAt(pos: number | Proxify<number>): Proxify<number | undefined>;
+  normalize(form?: string | Proxify<string>): Proxify<string>;
+  matchAll(regexp: RegExp | Proxify<RegExp>): Proxify<IterableIterator<RegExpMatchArray>>;
+  readonly length: Proxify<number>;
+  [key: string]: unknown;
+};
+/**
+ * 数组类型的 Proxify 版本
+ * 特殊处理泛型方法（map, filter 等），确保返回值类型正确
+ */
+type ProxifiedArray<T> = {
+  map<U>(callbackfn: Proxify<(value: T, index: number, array: T[]) => U>): Proxify<U[]>;
+  flatMap<U>(callbackfn: Proxify<(value: T, index: number, array: T[]) => U | readonly U[]>): Proxify<U[]>;
+  filter<S extends T>(predicate: Proxify<(value: T, index: number, array: T[]) => value is S>): Proxify<S[]>;
+  filter(predicate: Proxify<(value: T, index: number, array: T[]) => unknown>): Proxify<T[]>;
+  reduce<U>(callbackfn: Proxify<(previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U>, initialValue: U | Proxify<U>): Proxify<U>;
+  reduce(callbackfn: Proxify<(previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T>): Proxify<T>;
+  reduceRight<U>(callbackfn: Proxify<(previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U>, initialValue: U | Proxify<U>): Proxify<U>;
+  reduceRight(callbackfn: Proxify<(previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T>): Proxify<T>;
+  find<S extends T>(predicate: Proxify<(value: T, index: number, obj: T[]) => value is S>): Proxify<S | undefined>;
+  find(predicate: Proxify<(value: T, index: number, obj: T[]) => unknown>): Proxify<T | undefined>;
+  findIndex(predicate: Proxify<(value: T, index: number, obj: T[]) => unknown>): Proxify<number>;
+  findLast<S extends T>(predicate: Proxify<(value: T, index: number, array: T[]) => value is S>): Proxify<S | undefined>;
+  findLast(predicate: Proxify<(value: T, index: number, array: T[]) => unknown>): Proxify<T | undefined>;
+  findLastIndex(predicate: Proxify<(value: T, index: number, array: T[]) => unknown>): Proxify<number>;
+  every<S extends T>(predicate: Proxify<(value: T, index: number, array: T[]) => value is S>): Proxify<boolean>;
+  every(predicate: Proxify<(value: T, index: number, array: T[]) => unknown>): Proxify<boolean>;
+  some(predicate: Proxify<(value: T, index: number, array: T[]) => unknown>): Proxify<boolean>;
+  forEach(callbackfn: Proxify<(value: T, index: number, array: T[]) => void>): Proxify<void>;
+  toSorted(compareFn?: Proxify<(a: T, b: T) => number>): Proxify<T[]>;
+  sort(compareFn?: Proxify<(a: T, b: T) => number>): Proxify<T[]>;
+} & { [K in Exclude<keyof T[], ProxifiedArrayMethods>]: Proxify<T[][K]> };
 /**
  * 将类型 T 转换为 Proxy 包装类型
  * - 始终包含 ProxyExpression<T> 标记，用于 compile 函数类型检查
  * - 函数类型：保持函数签名，但参数允许 Proxy 或原始值，返回值递归应用 Proxify
+ * - 字符串类型：使用 ProxifiedString 特殊处理字符串方法
+ * - 数组类型：使用 ProxifiedArray 特殊处理泛型方法
  * - 对象类型：映射所有属性为 Proxify
  * - 原始类型：保持不变（返回 ProxyExpression 包装）
  */
-type Proxify<T> = ProxyExpression<T> & (T extends ((...args: infer Args) => infer R) ? (...args: ProxifyArgs<Args>) => Proxify<R> : T extends object ? { [K in keyof T]: Proxify<T[K]> } : unknown);
+type Proxify<T> = ProxyExpression<T> & (T extends string ? ProxifiedString : T extends ((...args: infer Args) => infer R) ? (...args: ProxifyArgs<Args>) => Proxify<R> : T extends readonly (infer E)[] ? ProxifiedArray<E> : T extends object ? { [K in keyof T]: Proxify<T[K]> } : unknown);
 /**
  * Variable 类型定义
  * 总是返回 Proxy 包装后的类型
@@ -100,6 +171,55 @@ type InferContextType<C> = { [K in keyof C]: C[K] extends Variable<infer T> ? T
  * @template E - Expression 类型
  */
 type InferExpressionType<E> = E extends Expression<unknown, infer R> ? R : never;
+/**
+ * Lambda 参数代理类型
+ * 与普通 Proxify<T> 相同，但标记为 lambda 参数
+ */
+type LambdaParam<T> = Proxify<T>;
+/**
+ * 原始类型
+ */
+type Primitive = string | number | boolean | null | undefined | symbol | bigint;
+/**
+ * 深度允许 Proxy 或原始值的类型
+ * 用于 lambda 返回值，允许对象/数组中混合 Proxy 和原始值
+ */
+type DeepPartialProxy<T> = T extends Primitive ? T : T extends readonly (infer E)[] ? readonly (Proxify<E> | DeepPartialProxy<E>)[] : T extends object ? { [K in keyof T]: Proxify<T[K]> | DeepPartialProxy<T[K]> } : T;
+/**
+ * Lambda 函数体返回值类型
+ * 支持返回：
+ * - Proxify<R>: 完整的代理表达式
+ * - 原始值: 字符串、数字等
+ * - 对象/数组: 可以混合 Proxy 值和原始值
+ */
+type LambdaBodyResult<T> = Proxify<T> | DeepPartialProxy<T>;
+/**
+ * Lambda 构建函数签名
+ * @template Args - 参数类型元组
+ * @template R - 返回值类型
+ */
+type LambdaBuilder<Args extends unknown[], R> = (...params: { [K in keyof Args]: LambdaParam<Args[K]> }) => LambdaBodyResult<R>;
+/**
+ * Lambda 表达式类型
+ * 表示一个可序列化的函数
+ */
+type Lambda<Args extends unknown[], R> = Proxify<(...args: Args) => R>;
+/**
+ * 从 Lambda 类型提取参数类型
+ */
+type InferLambdaArgs<L> = L extends Lambda<infer Args, unknown> ? Args : never;
+/**
+ * 从 Lambda 类型提取返回类型
+ */
+type InferLambdaReturn<L> = L extends Lambda<unknown[], infer R> ? R : never;
+/**
+ * 常用 Lambda 类型别名
+ */
+type MapCallback<T, R> = Lambda<[T, number, T[]], R>;
+type FilterCallback<T> = Lambda<[T, number, T[]], boolean>;
+type ReduceCallback<T, R> = Lambda<[R, T, number, T[]], R>;
+type FindCallback<T> = Lambda<[T, number, T[]], boolean>;
+type SortCallback<T> = Lambda<[T, T], number>;
 //#endregion
 //#region src/compile.d.ts
 /**
@@ -117,7 +237,7 @@ interface CompileOptions {
  * 将 Proxy Expression 编译为可序列化的 JSON 结构
  *
  * @template TResult - 表达式结果类型
- * @param expression - Proxy Expression
+ * @param expression - Proxy Expression，或包含 Proxy 的对象/数组/原始值
  * @param variables - 所有使用的变量定义
  * @param options - 编译选项
  * @returns 编译后的数据结构 [变量名列表, 表达式1, 表达式2, ...]
@@ -134,7 +254,7 @@ interface CompileOptions {
  * // => [["x", "y"], "($0+$1)*$0"]
  * ```
  */
-declare function compile<TResult>(expression: ProxyExpression<TResult>, variables: Record<string, unknown>, options?: CompileOptions): CompiledData;
+declare function compile<TResult>(expression: LambdaBodyResult<TResult>, variables: Record<string, unknown>, options?: CompileOptions): CompiledData;
 //#endregion
 //#region src/evaluate.d.ts
 /**
@@ -154,7 +274,7 @@ declare function compile<TResult>(expression: ProxyExpression<TResult>, variable
  * // => 6  (3 * 2)
  * ```
  */
-declare function evaluate<TResult>(data: CompiledData, values: Record<string, unknown>): TResult;
+declare function evaluate<TResult = unknown>(data: CompiledData, values: Record<string, unknown>): TResult;
 //#endregion
 //#region src/type-parser.d.ts
 /** 去除字符串两端空白 */
@@ -359,6 +479,27 @@ type ExpressionType<Source extends string, TContext> = ValidateExpression<Source
  */
 declare function expr<TContext extends Record<string, unknown>>(context: TContext): <TSource extends string>(source: ValidateExpression<TSource, TContext> extends never ? never : TSource) => Proxify<InferExpressionResult<TSource, TContext>>;
 //#endregion
+//#region src/lambda.d.ts
+/**
+ * 创建类型安全的 lambda 表达式
+ *
+ * @template Args - 参数类型元组
+ * @template R - 返回值类型
+ * @param builder - Lambda 构建函数，接收参数代理，返回函数体表达式
+ * @returns Lambda 表达式代理
+ *
+ * @example
+ * ```ts
+ * const add = lambda<[number, number], number>(
+ *   (a, b) => expr({ a, b })("a + b")
+ * );
+ *
+ * const numbers = variable<number[]>();
+ * const sum = numbers.reduce(add, 0);
+ * ```
+ */
+declare function lambda<Args extends unknown[], R>(builder: LambdaBuilder<Args, R>): Lambda<Args, R>;
+//#endregion
 //#region src/proxy-metadata.d.ts
 /**
  * 检查对象是否是 Proxy variable
@@ -409,5 +550,32 @@ declare function variable<T>(): Variable<T>;
  */
 declare function getVariableId(variable: unknown): symbol | undefined;
 //#endregion
-export { type BranchNode, type CompileContext, type CompileOptions, type CompiledData, type CompiledExpression, type ContextTypeMap, type ControlFlowNode, type ExprNode, type Expression, type ExpressionType, type ExtractType, type InferContextType, type InferExpressionResult, type InferExpressionType, type InferVariableType, type JumpNode, type ParseExpression, type PhiNode, type Proxify, type ProxyExpression, type ValidateExpression, type Variable, compile, evaluate, expr, getVariableId, isProxy, isProxyExpression, isProxyVariable, t, variable };
+//#region src/wrap.d.ts
+/**
+ * 将静态值包装为 Proxy Expression
+ * 返回的 Proxy 可以像 Variable 一样调用方法和访问属性
+ *
+ * @template T - 值的类型
+ * @param value - 要包装的静态值（支持原始值、对象、数组、Date、RegExp 等）
+ * @returns Proxy Expression，可以继续链式调用
+ *
+ * @example
+ * ```ts
+ * // 包装 RegExp
+ * const pattern = wrap(/^[a-z]+$/i);
+ * const input = variable<string>();
+ * const result = pattern.match(input);
+ *
+ * // 包装 Date
+ * const now = wrap(new Date());
+ * const year = now.getFullYear();
+ *
+ * // 包装数组
+ * const numbers = wrap([1, 2, 3, 4, 5]);
+ * const doubled = numbers.map((x) => x * 2);
+ * ```
+ */
+declare function wrap<T>(value: T): Proxify<T>;
+//#endregion
+export { type BranchNode, type CompileContext, type CompileOptions, type CompiledData, type CompiledExpression, type ContextTypeMap, type ControlFlowNode, type ExprNode, type Expression, type ExpressionType, type ExtractType, type FilterCallback, type FindCallback, type InferContextType, type InferExpressionResult, type InferExpressionType, type InferLambdaArgs, type InferLambdaReturn, type InferVariableType, type JumpNode, type Lambda, type LambdaBuilder, type LambdaParam, type MapCallback, type ParseExpression, type PhiNode, type Proxify, type ProxyExpression, type ReduceCallback, type SortCallback, type ValidateExpression, type Variable, compile, evaluate, expr, getVariableId, isProxy, isProxyExpression, isProxyVariable, lambda, t, variable, wrap };
 //# sourceMappingURL=index.d.mts.map