refactor(ast): replace string placeholders with Placeholder AST node

codehz · codehz · commit 74c2a3cfd9ce · 2026-01-25T13:08:15.000+08:00
Introduce a dedicated Placeholder AST node type to represent variable
references and lambda parameters instead of using special string patterns
like `$$VAR_...$$`. This provides type safety through symbol-based
identification and cleaner separation between variable placeholders
(resolved at compile time) and lambda parameter placeholders (resolved
at code generation time).

- Add Placeholder interface with symbol id to ast-types.ts
- Update ArrowFunctionExpr.params to accept Placeholder nodes
- Add transformPlaceholders function for compile-time placeholder resolution
- Update generate.ts to handle Placeholder nodes with symbol-based mapping
- Remove getVariablePlaceholder and parseVariablePlaceholder from variable.ts
diff --git a/src/ast-types.ts b/src/ast-types.ts
@@ -28,6 +28,16 @@ export interface Identifier {
   name: string;
 }
 
+/**
+ * 变量占位符节点
+ * 用于表示变量引用或 lambda 参数，在编译/代码生成时被替换
+ */
+export interface Placeholder {
+  type: "Placeholder";
+  /** 变量或 lambda 参数的唯一标识符 */
+  id: symbol;
+}
+
 export interface BinaryExpr {
   type: "BinaryExpr";
   operator: string;
@@ -83,7 +93,7 @@ export interface ObjectProperty {
 
 export interface ArrowFunctionExpr {
   type: "ArrowFunctionExpr";
-  params: Identifier[];
+  params: (Identifier | Placeholder)[];
   body: ASTNode;
 }
 
@@ -94,6 +104,7 @@ export type ASTNode =
   | BooleanLiteral
   | NullLiteral
   | Identifier
+  | Placeholder
   | BinaryExpr
   | UnaryExpr
   | ConditionalExpr
diff --git a/src/compile.ts b/src/compile.ts
@@ -1,5 +1,5 @@
 import type { ASTNode } from "./ast-types";
-import { generate, transformIdentifiers } from "./generate";
+import { generate, transformIdentifiers, transformPlaceholders } from "./generate";
 import { serializeArgumentToAST } from "./proxy-variable";
 import type { BranchNode, CompiledData, CompiledExpression, JumpNode, LambdaBodyResult, PhiNode } from "./types";
 import { getVariableId } from "./variable";
@@ -83,35 +83,43 @@ export function compile<TResult>(
 
   const ast = serializeArgumentToAST(expression);
 
-  // 建立变量名到索引的映射
+  // 建立变量名到索引的映射，以及 symbol -> 变量名的映射
   const variableOrder: string[] = [];
   const variableToIndex = new Map<string, number>();
-  const descToName = new Map<string, string>();
+  const symbolToName = new Map<symbol, string>();
 
   for (const [name, value] of Object.entries(variables)) {
     if (!variableToIndex.has(name)) {
       variableToIndex.set(name, variableOrder.length);
       variableOrder.push(name);
     }
     const id = getVariableId(value);
-    if (id?.description) {
-      descToName.set(id.description, name);
+    if (id) {
+      symbolToName.set(id, name);
     }
   }
 
-  // 转换 AST：将占位符替换为变量名，然后替换为 $N
-  const undefinedVars: string[] = [];
-  const transformed = transformIdentifiers(ast, (name) => {
-    const placeholderMatch = name.match(/^\$\$VAR_(.+)\$\$$/);
-    const resolvedName = placeholderMatch ? descToName.get(placeholderMatch[1]!) : name;
+  // 第一步：转换 Placeholder 节点为 $N 格式的 Identifier
+  // lambda 参数的 Placeholder 保留不转换（返回 null）
+  const placeholderTransformed = transformPlaceholders(ast, (id) => {
+    const name = symbolToName.get(id);
+    if (!name) return null; // 不是变量占位符（可能是 lambda 参数），保留
+    const index = variableToIndex.get(name);
+    if (index === undefined) return null;
+    return `$${index}`;
+  });
 
-    if (placeholderMatch && !resolvedName) throw new Error(`Unknown variable placeholder: ${name}`);
+  // 第二步：检查是否有未定义的 Identifier（非全局对象）
+  const undefinedVars: string[] = [];
+  const transformed = transformIdentifiers(placeholderTransformed, (name) => {
+    // 已经转换为 $N 的跳过
+    if (name.startsWith("$") && /^\$\d+$/.test(name)) return name;
 
-    const index = variableToIndex.get(resolvedName!);
+    const index = variableToIndex.get(name);
     if (index !== undefined) return `$${index}`;
 
-    if (!ALLOWED_GLOBALS.has(resolvedName!)) undefinedVars.push(resolvedName!);
-    return resolvedName!;
+    if (!ALLOWED_GLOBALS.has(name)) undefinedVars.push(name);
+    return name;
   });
 
   if (undefinedVars.length > 0) {
diff --git a/src/expr.ts b/src/expr.ts
@@ -1,11 +1,11 @@
-import type { ASTNode } from "./ast-types";
+import type { ASTNode, Placeholder } from "./ast-types";
 import { transformIdentifiers } from "./generate";
 import { parse } from "./parser";
 import { getProxyMetadata } from "./proxy-metadata";
 import { createProxyExpressionWithAST } from "./proxy-variable";
 import type { InferExpressionResult, ValidateExpression } from "./type-parser";
 import type { Proxify } from "./types";
-import { getVariableId, getVariablePlaceholder } from "./variable";
+import { getVariableId } from "./variable";
 
 /**
  * 创建表达式
@@ -95,12 +95,12 @@ export function expr<TContext extends Record<string, unknown>>(
     const ast = parse(source as string);
 
     // 在 AST 级别进行标识符替换
-    const transformedAst = transformIdentifiers(ast, (name) => {
+    const transformedAst = transformIdentifiers(ast, (name): string | ASTNode => {
       // 检查是否是 context 中的变量
       const id = nameToId.get(name);
       if (id) {
-        // 返回占位符标识符名称
-        return getVariablePlaceholder(id);
+        // 返回占位符节点
+        return { type: "Placeholder", id } satisfies Placeholder;
       }
 
       // 检查是否是子表达式
diff --git a/src/generate.ts b/src/generate.ts
@@ -12,8 +12,8 @@ import { BUILTIN_CONSTRUCTORS, PRECEDENCE, RIGHT_ASSOCIATIVE } from "./ast-types
 export interface GenerateContext {
   /** lambda 参数计数器，用于生成唯一参数名 */
   lambdaParamCounter: number;
-  /** 占位符到实际参数名的映射 */
-  paramMapping: Map<string, string>;
+  /** 占位符 Symbol 到实际参数名的映射 */
+  paramMapping: Map<symbol, string>;
 }
 
 /**
@@ -52,10 +52,15 @@ export function generateWithContext(node: ASTNode, ctx: GenerateContext): string
     case "NullLiteral":
       return "null";
 
-    case "Identifier": {
-      // 检查是否是 lambda 参数占位符
-      const mappedName = ctx.paramMapping.get(node.name);
-      return mappedName ?? node.name;
+    case "Identifier":
+      return node.name;
+
+    case "Placeholder": {
+      // 查找 lambda 参数映射
+      const mappedName = ctx.paramMapping.get(node.id);
+      if (mappedName) return mappedName;
+      // 未编译的占位符输出为特殊格式（用于测试/调试）
+      return `$$${node.id.description}$$`;
     }
 
     case "BinaryExpr": {
@@ -118,11 +123,19 @@ export function generateWithContext(node: ASTNode, ctx: GenerateContext): string
     case "ArrowFunctionExpr": {
       // 为每个参数分配唯一的参数名
       const paramNames: string[] = [];
+      const placeholderIds: symbol[] = [];
+
       for (const param of node.params) {
-        const uniqueName = `_${ctx.lambdaParamCounter++}`;
-        paramNames.push(uniqueName);
-        // 建立占位符到实际参数名的映射
-        ctx.paramMapping.set(param.name, uniqueName);
+        if (param.type === "Placeholder") {
+          // Placeholder 参数：分配唯一名称并建立映射
+          const uniqueName = `_${ctx.lambdaParamCounter++}`;
+          paramNames.push(uniqueName);
+          placeholderIds.push(param.id);
+          ctx.paramMapping.set(param.id, uniqueName);
+        } else {
+          // Identifier 参数：直接使用名称
+          paramNames.push(param.name);
+        }
       }
 
       const paramsStr = paramNames.length === 1 ? paramNames[0]! : `(${paramNames.join(",")})`;
@@ -131,11 +144,9 @@ export function generateWithContext(node: ASTNode, ctx: GenerateContext): string
           ? `(${generateWithContext(node.body, ctx)})`
           : generateWithContext(node.body, ctx);
 
-      // 清理参数映射（可选，防止污染外层作用域）
-      // 注意：由于我们使用唯一的参数名，不清理也不会冲突
-      // 但为了语义清晰，在函数体生成完成后移除映射
-      for (const param of node.params) {
-        ctx.paramMapping.delete(param.name);
+      // 清理 Placeholder 参数映射
+      for (const id of placeholderIds) {
+        ctx.paramMapping.delete(id);
       }
 
       return `${paramsStr}=>${body}`;
@@ -220,6 +231,10 @@ export function transformIdentifiers(node: ASTNode, transform: (name: string) =>
       return typeof result === "string" ? { ...node, name: result } : result;
     }
 
+    case "Placeholder":
+      // Placeholder 不是 Identifier，保持不变
+      return node;
+
     case "BinaryExpr":
       return {
         ...node,
@@ -273,8 +288,11 @@ export function transformIdentifiers(node: ASTNode, transform: (name: string) =>
       };
 
     case "ArrowFunctionExpr": {
-      // 箭头函数：参数名不转换，只转换函数体中的非参数标识符
-      const paramNames = new Set(node.params.map((p) => p.name));
+      // 箭头函数：只转换 Identifier 参数名，Placeholder 参数保持不变
+      // 只转换函数体中的非参数标识符
+      const paramNames = new Set(
+        node.params.filter((p): p is { type: "Identifier"; name: string } => p.type === "Identifier").map((p) => p.name)
+      );
       return {
         ...node,
         body: transformIdentifiers(node.body, (name) => (paramNames.has(name) ? name : transform(name))),
@@ -286,6 +304,87 @@ export function transformIdentifiers(node: ASTNode, transform: (name: string) =>
   }
 }
 
+/**
+ * 转换 AST 中的占位符节点
+ * 回调函数接收 symbol，返回 Identifier 节点的名称
+ * 如果返回 null/undefined，则保留原始 Placeholder 节点
+ */
+export function transformPlaceholders(node: ASTNode, transform: (id: symbol) => string | null | undefined): ASTNode {
+  switch (node.type) {
+    case "Placeholder": {
+      const name = transform(node.id);
+      return name != null ? { type: "Identifier", name } : node;
+    }
+
+    case "Identifier":
+      return node;
+
+    case "BinaryExpr":
+      return {
+        ...node,
+        left: transformPlaceholders(node.left, transform),
+        right: transformPlaceholders(node.right, transform),
+      };
+
+    case "UnaryExpr":
+      return {
+        ...node,
+        argument: transformPlaceholders(node.argument, transform),
+      };
+
+    case "ConditionalExpr":
+      return {
+        ...node,
+        test: transformPlaceholders(node.test, transform),
+        consequent: transformPlaceholders(node.consequent, transform),
+        alternate: transformPlaceholders(node.alternate, transform),
+      };
+
+    case "MemberExpr":
+      return {
+        ...node,
+        object: transformPlaceholders(node.object, transform),
+        property: node.computed ? transformPlaceholders(node.property, transform) : node.property,
+      };
+
+    case "CallExpr":
+      return {
+        ...node,
+        callee: transformPlaceholders(node.callee, transform),
+        arguments: node.arguments.map((arg) => transformPlaceholders(arg, transform)),
+      };
+
+    case "ArrayExpr":
+      return {
+        ...node,
+        elements: node.elements.map((el) => transformPlaceholders(el, transform)),
+      };
+
+    case "ObjectExpr":
+      return {
+        ...node,
+        properties: node.properties.map((prop) => ({
+          ...prop,
+          key: prop.computed ? transformPlaceholders(prop.key, transform) : prop.key,
+          value: transformPlaceholders(prop.value, transform),
+        })),
+      };
+
+    case "ArrowFunctionExpr": {
+      // 箭头函数：参数保持不变（Placeholder 参数在代码生成时处理）
+      // 函数体中的 Placeholder 需要转换，但要排除参数本身的 symbol
+      const paramSymbols = new Set(node.params.filter((p) => p.type === "Placeholder").map((p) => p.id));
+      return {
+        ...node,
+        body: transformPlaceholders(node.body, (id) => (paramSymbols.has(id) ? null : transform(id))),
+      };
+    }
+
+    default:
+      return node;
+  }
+}
+
 /**
  * 收集 AST 中所有使用的标识符名称
  */
@@ -341,7 +440,10 @@ export function collectIdentifiers(node: ASTNode): Set<string> {
       case "ArrowFunctionExpr": {
         // 箭头函数：收集参数名和函数体中的标识符
         // 但从闭包角度，只需收集非参数的自由变量
-        const paramNames = new Set(n.params.map((p) => p.name));
+        // 只考虑 Identifier 参数，Placeholder 参数在编译时处理
+        const paramNames = new Set(
+          n.params.filter((p): p is { type: "Identifier"; name: string } => p.type === "Identifier").map((p) => p.name)
+        );
         const bodyIdentifiers = collectIdentifiers(n.body);
         for (const id of bodyIdentifiers) {
           if (!paramNames.has(id)) {
diff --git a/src/lambda.ts b/src/lambda.ts
@@ -149,18 +149,17 @@ function extractBodyAstAndDeps(bodyExpr: unknown): { bodyAst: ASTNode; bodyDeps:
 
 /**
  * 创建箭头函数 AST
- * 使用占位符参数名，在代码生成时再分配实际参数名
+ * 使用 Placeholder 节点作为参数，在代码生成时再分配实际参数名
  */
 function createArrowFunctionAst(bodyAst: ASTNode, paramCount: number, paramSymbols: symbol[]): ASTNode {
-  const paramIdentifiers = Array.from({ length: paramCount }, (_, i) => ({
-    type: "Identifier" as const,
-    // 使用占位符，在 generate 时会被替换为唯一参数名
-    name: `$$VAR_${paramSymbols[i]?.description}$$`,
+  const paramPlaceholders = Array.from({ length: paramCount }, (_, i) => ({
+    type: "Placeholder" as const,
+    id: paramSymbols[i]!,
   }));
 
   return {
     type: "ArrowFunctionExpr",
-    params: paramIdentifiers,
+    params: paramPlaceholders,
     body: bodyAst,
   };
 }
diff --git a/src/proxy-variable.ts b/src/proxy-variable.ts
@@ -9,6 +9,7 @@ import type {
   NullLiteral,
   NumberLiteral,
   ObjectExpr,
+  Placeholder,
   StringLiteral,
 } from "./ast-types";
 import { getProxyMetadata, setProxyMetadata } from "./proxy-metadata";
@@ -45,11 +46,10 @@ const typedArrayConstructors = [
 ];
 
 /**
- * 使用 Symbol.description 生成占位符
- * 用于在表达式源码中标识变量
+ * 创建占位符 AST 节点
  */
-function getVariablePlaceholder(id: symbol): string {
-  return `$$VAR_${id.description}$$`;
+function placeholder(id: symbol): Placeholder {
+  return { type: "Placeholder", id };
 }
 
 /**
@@ -123,9 +123,9 @@ export function serializeArgumentToAST(arg: unknown): ASTNode {
     if (meta) {
       // 如果有 ast，直接返回
       if (meta.ast) return meta.ast;
-      // 否则是根 variable，返回占位符标识符
+      // 否则是根 variable，返回占位符节点
       if (meta.rootVariable) {
-        return identifier(getVariablePlaceholder(meta.rootVariable));
+        return placeholder(meta.rootVariable);
       }
     }
   }
@@ -245,7 +245,7 @@ export function collectDepsFromArgs(args: unknown[], deps: Set<symbol>): void {
  * 根据路径构建成员表达式 AST
  */
 function buildMemberExprAst(rootId: symbol, path: string[]): ASTNode {
-  let ast: ASTNode = identifier(getVariablePlaceholder(rootId));
+  let ast: ASTNode = placeholder(rootId);
   for (const prop of path) {
     ast = memberExpr(ast, identifier(prop));
   }
diff --git a/src/variable.ts b/src/variable.ts
