@codehz/json-expr 0.3.0 → 0.5.0

package/dist/index.d.mts

@@ -1,16 +1,66 @@
 //#region src/types.d.ts
 /**
- * 表示一个类型化变量
- * @template T - 变量的值类型
+ * Proxy Expression 类型标记（用于类型推导）
+ * 这是一个 phantom type，实际运行时是 Proxy 对象
  */
-type Variable<T = unknown> = {
-  _tag: "variable";
-  _type: T;
+type ProxyExpression<T = unknown> = {
+  readonly __proxyExpression: T;
 };
+/**
+ * 处理函数参数的 Proxy 转换
+ * 参数可以是原始值或对应的 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 版本
+ * 特殊处理泛型方法（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
+ * - 数组类型：使用 ProxifiedArray 特殊处理泛型方法
+ * - 对象类型：映射所有属性为 Proxify
+ * - 原始类型：保持不变（返回 ProxyExpression 包装）
+ */
+type Proxify<T> = ProxyExpression<T> & (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 包装后的类型
+ * @template T - 变量的值类型
+ */
+type Variable<T = unknown> = Proxify<T>;
 /**
  * 表示一个表达式
  * @template TContext - 表达式上下文类型
  * @template TResult - 表达式结果类型
+ * @deprecated 请使用新的 Proxy 类型系统
  */
 type Expression<TContext = Record<string, unknown>, TResult = unknown> = {
   _tag: "expression";
@@ -81,18 +131,61 @@ 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
 /**
  * 编译选项
  */
 interface CompileOptions {
-  /**
-   * 是否启用内联优化
-   * 将只被引用一次的子表达式内联到使用位置
-   * @default true
-   */
-  inline?: boolean;
   /**
    * 是否启用短路求值
    * 为 &&, ||, ??, 和三元表达式生成控制流节点
@@ -101,66 +194,27 @@ interface CompileOptions {
   shortCircuit?: boolean;
 }
 /**
- * 表达式上下文类型约束
- */
-type ExpressionContext = Record<string, Variable | Expression<Record<string, unknown>, unknown>>;
-/**
- * 将表达式树编译为可序列化的 JSON 结构
+ * 将 Proxy Expression 编译为可序列化的 JSON 结构
  *
  * @template TResult - 表达式结果类型
- * @param expression - 根表达式
+ * @param expression - Proxy Expression，或包含 Proxy 的对象/数组/原始值
  * @param variables - 所有使用的变量定义
  * @param options - 编译选项
  * @returns 编译后的数据结构 [变量名列表, 表达式1, 表达式2, ...]
  *
- * @throws 如果检测到循环依赖或未定义的变量引用
+ * @throws 如果传入无效的表达式或未定义的变量引用
  *
  * @example
  * ```ts
- * const x = variable(z.number())
- * const y = variable(z.number())
- * const sum = expr({ x, y })<number>("x + y")
- * const result = expr({ sum })<number>("sum * 2")
+ * const x = variable<number>()
+ * const y = variable<number>()
+ * const sum = expr({ x, y })("x + y")
+ * const result = expr({ sum, x })("sum * x")
  * const compiled = compile(result, { x, y })
- * // => [["x", "y"], "($0+$1)*2"]  // 内联优化后
+ * // => [["x", "y"], "($0+$1)*$0"]
  * ```
  */
-declare function compile<TResult>(expression: Expression<ExpressionContext, TResult>, variables: Record<string, Variable>, options?: CompileOptions): CompiledData;
-//#endregion
-//#region src/constant.d.ts
-/**
- * JSON 可序列化的值类型
- */
-type JsonValue = string | number | boolean | null | JsonValue[] | {
-  [key: string]: JsonValue;
-};
-/**
- * 创建一个编译期常量表达式
- *
- * 这是 `expr({})(JSON.stringify(value))` 的快速路径，
- * 用于在表达式中嵌入静态值，避免在运行时传入或在多处重复编写。
- *
- * @template T - 常量值类型（必须是 JSON 可序列化的）
- * @param value - 要嵌入的常量值
- * @returns 返回一个 Expression 对象，其结果类型为 T
- *
- * @example
- * ```ts
- * // 创建一个数字常量
- * const PI = constant(3.14159)
- *
- * // 创建一个字符串常量
- * const greeting = constant("Hello, World!")
- *
- * // 创建一个对象常量
- * const config = constant({ maxRetries: 3, timeout: 5000 })
- *
- * // 在表达式中使用常量
- * const radius = variable(z.number())
- * const area = expr({ PI, radius })("PI * radius * radius")
- * ```
- */
-declare function constant<const T extends JsonValue>(value: T): Expression<{}, T>;
+declare function compile<TResult>(expression: LambdaBodyResult<TResult>, variables: Record<string, unknown>, options?: CompileOptions): CompiledData;
 //#endregion
 //#region src/evaluate.d.ts
 /**
@@ -357,29 +411,12 @@ type ExpressionType<Source extends string, TContext> = ValidateExpression<Source
 //#endregion
 //#region src/expr.d.ts
 /**
- * 表达式上下文类型约束
- */
-type ExprContext = Record<string, Variable | Expression<Record<string, unknown>, unknown>>;
-/**
- * 表达式错误类型
- */
-type ExprError<Msg extends string, Details = unknown> = {
-  readonly __error: Msg;
-  readonly __details: Details;
-};
-/**
- * 验证结果处理：如果验证失败返回错误类型，否则返回推导的结果类型
- */
-type ExprResult<Source extends string, TContext extends ExprContext> = ValidateExpression<Source, TContext> extends true ? InferExpressionResult<Source, TContext> : ValidateExpression<Source, TContext> extends {
-  error: "undefined_identifiers";
-  identifiers: infer Ids;
-} ? ExprError<"Undefined identifiers in expression", Ids> : ExprError<"Expression validation failed", ValidateExpression<Source, TContext>>;
-/**
- * 创建一个表达式，支持编译时类型检查和返回类型自动推导
+ * 创建表达式
+ * 返回 Proxy Expression，可以继续链式调用
  *
- * @template TContext - 表达式上下文类型（Variable 或 Expression 的映射）
- * @param context - 包含 Variable 或 Expression 的上下文对象
- * @returns 返回一个函数，该函数接收表达式源码字符串并返回 Expression 对象
+ * @template TContext - 表达式上下文类型
+ * @param context - 包含 Variable 或 Proxy Expression 的上下文对象
+ * @returns 返回一个函数，该函数接收表达式源码字符串并返回 Proxy Expression
  *
  * 类型系统会：
  * 1. 验证表达式中使用的所有标识符都在 context 中定义
@@ -387,8 +424,8 @@ type ExprResult<Source extends string, TContext extends ExprContext> = ValidateE
  *
  * @example
  * ```ts
- * const x = variable(z.number())
- * const y = variable(z.number())
+ * const x = variable<number>();
+ * const y = variable<number>();
  *
  * // 自动推导返回类型为 number
  * const sum = expr({ x, y })("x + y")
@@ -400,26 +437,78 @@ type ExprResult<Source extends string, TContext extends ExprContext> = ValidateE
  * // const invalid = expr({ x, y })("x + z")
  * ```
  */
-declare function expr<TContext extends ExprContext>(context: TContext): <Source extends string>(source: Source) => Expression<TContext, ExprResult<Source, TContext>>;
+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
+ */
+declare function isProxyVariable(obj: unknown): obj is object;
+/**
+ * 检查对象是否是 Proxy expression
+ */
+declare function isProxyExpression(obj: unknown): obj is object;
+/**
+ * 检查对象是否是任意 Proxy (variable 或 expression)
+ */
+declare function isProxy(obj: unknown): obj is object;
+//#endregion
+//#region src/template.d.ts
+/**
+ * Tagged template 函数，用于创建包含变量的字符串表达式
+ *
+ * @example
+ * ```ts
+ * const name = variable<string>();
+ * const count = variable<number>();
+ *
+ * const greeting = t`Hello, ${name}!`;
+ * const message = t`You have ${count} items.`;
+ *
+ * const compiled = compile(greeting, { name });
+ * const result = evaluate(compiled, { name: "Alice" }); // => "Hello, Alice!"
+ * ```
+ */
+declare function t(strings: TemplateStringsArray, ...values: unknown[]): Proxify<string>;
 //#endregion
 //#region src/variable.d.ts
 /**
  * 创建一个类型化变量
- *
- * @template T - 变量的值类型
- * @returns 返回 Variable 对象，包含 _tag 标记
+ * 返回 Proxy 对象，支持链式属性访问和方法调用
  *
  * @example
  * ```ts
- * const x = variable<number>()
- * const name = variable<string>()
- * const config = variable<{
- *   count: number,
- *   enabled: boolean
- * }>()
+ * const x = variable<number>();
+ * const config = variable<{ timeout: number }>();
+ * const timeout = config.timeout; // Proxy expression
  * ```
  */
 declare function variable<T>(): Variable<T>;
+/**
+ * 获取 variable 的唯一 Symbol ID
+ */
+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 ValidateExpression, type Variable, compile, constant, evaluate, expr, variable };
+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 };
 //# sourceMappingURL=index.d.mts.map