@codehz/json-expr 0.3.0 → 0.4.0

package/README.md

@@ -6,12 +6,13 @@
 
 ## 特性
 
-- 🎯 **类型安全** - 使用 TypeScript 和 Zod 进行完整的类型推导和验证
+- 🎯 **类型安全** - 使用 TypeScript 泛型进行完整的编译时类型推导
 - 📦 **可序列化** - 编译后的表达式为纯 JSON 格式，易于传输和存储
 - 🔧 **灵活的表达式** - 支持任意 JavaScript 表达式，包括函数调用和对象属性访问
-- ⚡ **高性能** - 使用 `new Function()` 进行优化执行
+- ⚡ **高性能** - 优化的表达式编译和执行
 - 🧩 **可组合** - 表达式可以相互组合，形成复杂的计算树
-- 🔐 **类型验证** - 运行时通过 Zod schema 进行数据验证
+- 🔄 **短路求值** - 支持 `&&`、`||`、`??` 和三元表达式的控制流优化
+- 📝 **内联优化** - 自动内联只被引用一次的子表达式
 
 ## 快速开始
 
@@ -24,12 +25,11 @@ bun install @codehz/json-expr
 ### 基本用法
 
 ```typescript
-import { z } from "zod";
-import { variable, expr, compile, evaluate, constant } from "@codehz/json-expr";
+import { variable, expr, compile, evaluate } from "@codehz/json-expr";
 
-// 定义类型化变量
-const x = variable(z.number());
-const y = variable(z.number());
+// 定义类型化变量（使用 TypeScript 泛型）
+const x = variable<number>();
+const y = variable<number>();
 
 // 构建表达式
 const sum = expr({ x, y })("x + y");
@@ -49,17 +49,15 @@ const value = evaluate(compiled, { x: 2, y: 3 });
 
 ### Variable（变量）
 
-变量是表达式中的占位符，通过 Zod schema 定义其类型和验证规则。
+变量是表达式中的占位符，使用 TypeScript 泛型定义其类型。
 
 ```typescript
-const age = variable(z.number().int().min(0).max(150));
-const name = variable(z.string().min(1));
-const config = variable(
-  z.object({
-    debug: z.boolean(),
-    timeout: z.number(),
-  })
-);
+const age = variable<number>();
+const name = variable<string>();
+const config = variable<{
+  debug: boolean;
+  timeout: number;
+}>();
 ```
 
 ### Expression（表达式）
@@ -67,8 +65,8 @@ const config = variable(
 表达式对变量或其他表达式进行运算，使用字符串形式描述。
 
 ```typescript
-const x = variable(z.number());
-const y = variable(z.number());
+const x = variable<number>();
+const y = variable<number>();
 
 // 简单表达式
 const sum = expr({ x, y })("x + y");
@@ -93,51 +91,23 @@ const compiled = compile(result, { x, y });
 
 ## API 参考
 
-### `constant<T>(value: T): Expression<{}, T>`
-
-创建一个编译期常量表达式。这是 `expr({})(JSON.stringify(value))` 的快速路径，用于在表达式中嵌入静态值，避免在运行时传入或在多处重复编写。
-
-**参数：**
-
-- `value` - 要嵌入的常量值（必须是 JSON 可序列化的：string、number、boolean、null、数组或对象）
-
-**返回值：** Expression 对象
-
-**示例：**
-
-```typescript
-import { constant, expr, variable, compile, evaluate } from "@codehz/json-expr";
-import { z } from "zod";
-
-// 创建常量
-const PI = constant(3.14159);
-const config = constant({ maxRetries: 3, timeout: 5000 });
-
-// 在表达式中使用常量
-const radius = variable(z.number());
-const area = expr({ PI, radius })("PI * radius * radius");
-
-const compiled = compile(area, { radius });
-const result = evaluate(compiled, { radius: 2 });
-// => 12.56636
-```
-
-### `variable<T>(schema: T): Variable<T>`
+### `variable<T>(): Variable<T>`
 
 创建一个类型化变量。
 
-**参数：**
+**参数：** 无（类型通过泛型参数 `T` 指定）
 
-- `schema` - Zod schema，定义变量的类型和验证规则
-
-**返回值：** Variable 对象
+**返回值：** Variable 对象，支持属性访问和方法调用
 
 **示例：**
 
 ```typescript
-const num = variable(z.number());
-const str = variable(z.string());
-const date = variable(z.date());
+const num = variable<number>();
+const str = variable<string>();
+const config = variable<{ timeout: number }>();
+
+// 支持链式属性访问
+const timeout = config.timeout; // 自动转换为表达式
 ```
 
 ### `expr<TContext>(context: TContext): (source: string) => Expression<TContext, TResult>`
@@ -153,21 +123,21 @@ const date = variable(z.date());
 **示例：**
 
 ```typescript
-const x = variable(z.number());
-const y = variable(z.number());
+const x = variable<number>();
+const y = variable<number>();
 
 const sum = expr({ x, y })("x + y");
 const result = expr({ sum, x })("sum * x");
 ```
 
-### `compile<TResult>(expression: Expression<any, TResult>, variables: Record<string, Variable<any>>, options?: CompileOptions): CompiledData`
+### `compile<TResult>(expression: Expression<any, TResult>, variables: Record<string, Variable<any>> | Variable<any>[], options?: CompileOptions): CompiledData`
 
 将表达式树编译为可序列化的 JSON 结构。
 
 **参数：**
 
 - `expression` - 要编译的表达式
-- `variables` - 表达式中使用的所有变量映射
+- `variables` - 表达式中使用的所有变量映射或数组
 - `options` - 编译选项（可选）
   - `inline?: boolean` - 是否启用内联优化，将只被引用一次的子表达式内联到使用位置（默认：true）
   - `shortCircuit?: boolean` - 是否启用短路求值，为 &&, ||, ??, 和三元表达式生成控制流节点（默认：true）
@@ -177,14 +147,14 @@ const result = expr({ sum, x })("sum * x");
 **示例：**
 
 ```typescript
-const x = variable(z.number());
-const y = variable(z.number());
+const x = variable<number>();
+const y = variable<number>();
 const sum = expr({ x, y })("x + y");
 const product = expr({ x, y })("x * y");
 const result = expr({ sum, product })("sum + product");
 
 const compiled = compile(result, { x, y });
-// [["x", "y"], "($0+$1)", "($0*$1)", "$2+$3"]
+// [["x", "y"], "$0+$1", "$0*$1", "$2+$3"]
 
 // 禁用内联优化
 const noInline = compile(result, { x, y }, { inline: false });
@@ -209,30 +179,66 @@ const noShortCircuit = compile(result, { x, y }, { shortCircuit: false });
 **示例：**
 
 ```typescript
+const x = variable<number>();
+const y = variable<number>();
+const sum = expr({ x, y })("x + y");
+const product = expr({ x, y })("x * y");
+const result = expr({ sum, product })("sum + product");
+
 const compiled = compile(result, { x, y });
 const value = evaluate(compiled, { x: 5, y: 3 });
 // => 23  ((5+3) + (5*3) = 8 + 15 = 23)
 ```
 
+### `t(strings: TemplateStringsArray, ...values: unknown[]): Proxify<string>`
+
+使用标签模板函数创建包含变量的字符串表达式。
+
+**参数：**
+
+- `strings` - 模板字符串的静态部分
+- `values` - 模板中插值的变量和表达式
+
+**返回值：** 字符串类型的 Proxy Expression
+
+**示例：**
+
+```typescript
+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!"
+```
+
 ## 高级用法
 
-### 传入对象和内置对象
+### 内置全局对象
 
-支持在上下文中传入对象（如 Math）以在表达式中访问其属性和方法：
+表达式中可以直接使用以下内置对象（无需在上下文中定义）：
+
+- `Math`, `JSON`, `Date`, `RegExp`
+- `Number`, `String`, `Boolean`, `Array`, `Object`
+- `undefined`, `NaN`, `Infinity`
+- `isNaN`, `isFinite`, `parseInt`, `parseFloat`
 
 ```typescript
-const x = variable(z.number());
+const x = variable<number>();
 
-const sqrtExpr = expr({ x, Math: variable(z.any()) })("Math.sqrt(x)");
-const compiled = compile(sqrtExpr, { x, Math: variable(z.any()) });
-const result = evaluate(compiled, { x: 16, Math });
+const sqrtExpr = expr({ x })("Math.sqrt(x)");
+const compiled = compile(sqrtExpr, { x });
+const result = evaluate(compiled, { x: 16 });
 // => 4
 ```
 
 ### 条件表达式
 
 ```typescript
-const score = variable(z.number());
+const score = variable<number>();
 const gradeExpr = expr({ score })("score >= 90 ? 'A' : score >= 80 ? 'B' : score >= 70 ? 'C' : 'F'");
 
 const compiled = compile(gradeExpr, { score });
@@ -243,7 +249,7 @@ const grade = evaluate(compiled, { score: 85 });
 ### 数组和对象操作
 
 ```typescript
-const numbers = variable(z.array(z.number()));
+const numbers = variable<number[]>();
 
 const sumExpr = expr({ numbers })("numbers.reduce((a, b) => a + b, 0)");
 
@@ -255,8 +261,8 @@ const sum = evaluate(compiled, { numbers: [1, 2, 3, 4, 5] });
 ### 链式表达式组合
 
 ```typescript
-const a = variable(z.number());
-const b = variable(z.number());
+const a = variable<number>();
+const b = variable<number>();
 
 const sum = expr({ a, b })("a + b");
 const product = expr({ a, b })("a * b");
@@ -295,11 +301,12 @@ const value = evaluate(deserialized, { x: 5, y: 3 });
 项目充分利用 TypeScript 的类型系统进行编译时检查和类型推导：
 
 ```typescript
-const x = variable(z.number());
-const y = variable(z.string());
+const x = variable<number>();
+const y = variable<string>();
 
-// 提供完整的类型推导和自动补全
-const sum = expr({ x, y })("x + y");
+// 类型错误会在编译时捕获
+// const invalid = expr({ x, y })("z + y"); // Error: 'z' not in context
+const valid = expr({ x })("-x"); // 编译器推导为 number
 ```
 
 ## 性能考虑
@@ -313,12 +320,15 @@ const sum = expr({ x, y })("x + y");
 ```
 src/
 ├── index.ts              # 导出入口
-├── variable.ts           # variable 函数实现
-├── expr.ts               # expr 函数实现
-├── compile.ts            # compile 函数实现
-├── evaluate.ts           # evaluate 函数实现
-├── parser.ts             # 表达式解析器
-├── type-parser.ts        # 类型解析器
+├── variable.ts           # variable<T>() 函数
+├── expr.ts               # expr() 函数
+├── template.ts           # t() 标签模板函数
+├── compile.ts            # 编译器（内联优化、短路求值）
+├── evaluate.ts           # 运行时求值
+├── parser.ts             # 表达式 AST 解析器
+├── type-parser.ts        # TypeScript 类型级表达式解析
+├── proxy-variable.ts     # Proxy 变量实现
+├── proxy-metadata.ts     # Proxy 元数据管理
 ├── types.ts              # 类型定义
 └── *.test.ts             # 测试文件
 ```

package/dist/index.d.mts

@@ -1,16 +1,35 @@
 //#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]> };
+/**
+ * 将类型 T 转换为 Proxy 包装类型
+ * - 始终包含 ProxyExpression<T> 标记，用于 compile 函数类型检查
+ * - 函数类型：保持函数签名，但参数允许 Proxy 或原始值，返回值递归应用 Proxify
+ * - 对象类型：映射所有属性为 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);
+/**
+ * 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";
@@ -87,12 +106,6 @@ type InferExpressionType<E> = E extends Expression<unknown, infer R> ? R : never
  * 编译选项
  */
 interface CompileOptions {
-  /**
-   * 是否启用内联优化
-   * 将只被引用一次的子表达式内联到使用位置
-   * @default true
-   */
-  inline?: boolean;
   /**
    * 是否启用短路求值
    * 为 &&, ||, ??, 和三元表达式生成控制流节点
@@ -101,66 +114,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
  * @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"]  // 内联优化后
- * ```
- */
-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")
+ * // => [["x", "y"], "($0+$1)*$0"]
  * ```
  */
-declare function constant<const T extends JsonValue>(value: T): Expression<{}, T>;
+declare function compile<TResult>(expression: ProxyExpression<TResult>, variables: Record<string, unknown>, options?: CompileOptions): CompiledData;
 //#endregion
 //#region src/evaluate.d.ts
 /**
@@ -357,29 +331,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 +344,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 +357,57 @@ 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/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 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 };
 //# sourceMappingURL=index.d.mts.map