@codehz/json-expr 0.5.0 → 0.5.2

package/README.md

@@ -28,7 +28,7 @@ bun install @codehz/json-expr
 ### 基本用法
 
 ```typescript
-import { variable, expr, compile, evaluate, t, lambda } from "@codehz/json-expr";
+import { variable, expr, compile, evaluate, t, lambda, wrap } from "@codehz/json-expr";
 
 // 定义类型化变量（使用 TypeScript 泛型）
 const x = variable<number>();
@@ -54,6 +54,11 @@ const greeting = t`Hello, ${name}!`;
 // 使用 lambda 表达式
 const numbers = variable<number[]>();
 const doubled = numbers.map(lambda<[number], number>((n) => expr({ n })("n * 2")));
+
+// 使用 wrap 包装静态值
+const pattern = wrap(/^[a-z]+$/i);
+const input = variable<string>();
+const isValid = pattern.test(input);
 ```
 
 ## 核心概念
@@ -260,8 +265,152 @@ const multiplier = variable<number>();
 const scaled = numbers.map(lambda<[number], number>((n) => expr({ n, multiplier })("n * multiplier")));
 ```
 
+### `wrap<T>(value: T): Proxify<T>`
+
+将静态值包装为 Proxy Expression，使其可以像 Variable 一样调用方法和访问属性。
+
+**参数：**
+
+- `value` - 要包装的静态值（支持原始值、对象、数组、Date、RegExp、BigInt、URL、Map、Set、TypedArray 等）
+
+**返回值：** Proxy Expression，可以继续链式调用
+
+**示例：**
+
+```typescript
+// 包装 RegExp
+const pattern = wrap(/^[a-z]+$/i);
+const input = variable<string>();
+const isValid = pattern.test(input);
+
+const compiled = compile(isValid, { input });
+evaluate(compiled, { input: "hello" }); // => true
+evaluate(compiled, { input: "hello123" }); // => false
+
+// 包装 Date
+const now = wrap(new Date("2024-01-01"));
+const year = now.getFullYear();
+
+// 包装数组
+const staticNumbers = wrap([1, 2, 3, 4, 5]);
+const x = variable<number>();
+const doubled = staticNumbers.map(lambda((n: number) => expr({ n, x })("n * x")));
+
+// 包装对象
+const config = wrap({ port: 8080, host: "localhost" });
+const port = config.port; // 直接访问属性
+
+// 包装 Map
+const map = wrap(
+  new Map([
+    ["a", 1],
+    ["b", 2],
+  ])
+);
+const key = variable<string>();
+const value = map.get(key);
+
+// 链式调用
+const text = wrap("  hello world  ");
+const result = text.trim().toUpperCase().replace("HELLO", "HI");
+// => "HI WORLD"
+```
+
 ## 高级用法
 
+### 包装静态值（wrap）
+
+`wrap()` 函数可以将任意静态值转换为 Proxy Expression，使其可以像 Variable 一样调用方法和访问属性。这在需要对常量值执行操作时非常有用。
+
+**基本用法：**
+
+```typescript
+// 不使用 wrap（传统方式）
+interface Validator {
+  match(text: string, pattern: RegExp): boolean;
+}
+const validator = variable<Validator>();
+const result = validator.match("hello", /^[a-z]+$/i);
+
+// 使用 wrap（推荐方式）
+const pattern = wrap(/^[a-z]+$/i);
+const input = variable<string>();
+const result = pattern.test(input);
+```
+
+**支持的类型：**
+
+```typescript
+// 原始值
+const num = wrap(42);
+const str = wrap("hello");
+const bool = wrap(true);
+
+// Date 和 RegExp
+const date = wrap(new Date("2024-01-01"));
+const year = date.getFullYear();
+
+const regex = wrap(/\d+/g);
+const text = variable<string>();
+const matches = text.match(regex);
+
+// BigInt
+const bigNum = wrap(123456789n);
+const x = variable<bigint>();
+const sum = expr({ bigNum, x })("bigNum + x");
+
+// URL
+const url = wrap(new URL("https://example.com/path"));
+const host = url.hostname;
+const port = url.port;
+
+// Map 和 Set
+const map = wrap(
+  new Map([
+    ["key1", 100],
+    ["key2", 200],
+  ])
+);
+const key = variable<string>();
+const value = map.get(key);
+
+const set = wrap(new Set([1, 2, 3]));
+const num = variable<number>();
+const has = set.has(num);
+
+// TypedArray
+const arr = wrap(new Uint8Array([10, 20, 30]));
+const index = variable<number>();
+const value = expr({ arr, index })("arr[index]");
+
+// 数组和对象
+const numbers = wrap([1, 2, 3, 4, 5]);
+const multiplier = variable<number>();
+const scaled = numbers.map(lambda((n: number) => expr({ n, multiplier })("n * multiplier")));
+
+const config = wrap({ port: 8080, host: "localhost" });
+const port = config.port;
+```
+
+**链式调用：**
+
+```typescript
+const text = wrap("  Hello, World!  ");
+const result = text.trim().toLowerCase().replace("world", "universe");
+// => "hello, universe!"
+```
+
+**与 variable 结合：**
+
+```typescript
+const staticData = wrap({ users: ["alice", "bob", "charlie"] });
+const index = variable<number>();
+const username = expr({ staticData, index })("staticData.users[index]");
+
+const compiled = compile(username, { index });
+evaluate(compiled, { index: 1 }); // => "bob"
+```
+
 ### Proxy 变量系统
 
 `variable()` 创建的变量是 Proxy 对象，支持链式属性访问和方法调用，所有操作都会自动转换为表达式。

package/dist/index.d.mts

@@ -15,6 +15,45 @@ 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 等），确保返回值类型正确
@@ -45,11 +84,12 @@ type ProxifiedArray<T> = {
  * 将类型 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 readonly (infer E)[] ? ProxifiedArray<E> : 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 包装后的类型
@@ -234,7 +274,7 @@ declare function compile<TResult>(expression: LambdaBodyResult<TResult>, variabl
  * // => 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
 /** 去除字符串两端空白 */
@@ -510,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 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 };
+//#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