@variojs/core 0.1.0

package/src/expression/compiler.ts

@@ -0,0 +1,144 @@
+/**
+ * 表达式编译器
+ * 
+ * 功能：
+ * - 将简单表达式编译为直接访问函数
+ * - 提升简单表达式的执行性能
+ * - 复杂表达式回退到解释执行
+ */
+
+import type * as ESTree from '@babel/types'
+import type { RuntimeContext } from '../types.js'
+
+/**
+ * 编译后的表达式函数类型
+ */
+export type CompiledExpression = (ctx: RuntimeContext) => unknown
+
+/**
+ * 编译缓存（全局，表达式字符串 → 编译函数）
+ */
+const compiledCache = new Map<string, CompiledExpression | null>()
+
+/**
+ * 提取静态路径（从 MemberExpression）
+ * 
+ * 例如：user.name → "user.name"
+ * 例如：items.0.text → "items.0.text"
+ */
+function extractStaticPath(node: ESTree.Node): string | null {
+  if (node.type === 'Identifier') {
+    return node.name
+  }
+  
+  if (node.type === 'MemberExpression') {
+    const object = extractStaticPath(node.object)
+    if (!object) return null
+    
+    if (node.computed) {
+      // 计算属性：obj[key]，需要检查 key 是否为字面量
+      if (node.property.type === 'NumericLiteral') {
+        const prop = (node.property as ESTree.NumericLiteral).value
+        return `${object}.${String(prop)}`
+      }
+      if (node.property.type === 'StringLiteral') {
+        const prop = (node.property as ESTree.StringLiteral).value
+        return `${object}.${String(prop)}`
+      }
+      // 处理其他字面量类型（已由上面的具体类型处理，这里不需要）
+      return null
+    } else {
+      // 静态属性：obj.prop
+      if (node.property.type === 'Identifier') {
+        return `${object}.${node.property.name}`
+      }
+      return null
+    }
+  }
+  
+  return null
+}
+
+/**
+ * 编译简单表达式为直接访问函数
+ * 
+ * @param ast AST 节点
+ * @returns 编译后的函数，如果无法编译则返回 null
+ */
+export function compileSimpleExpression(ast: ESTree.Node): CompiledExpression | null {
+  // 字面量：{{ 42 }} → () => 42
+  if (ast.type === 'NumericLiteral') {
+    const value = (ast as ESTree.NumericLiteral).value
+    return () => value
+  }
+  if (ast.type === 'StringLiteral') {
+    const value = (ast as ESTree.StringLiteral).value
+    return () => value
+  }
+  if (ast.type === 'BooleanLiteral') {
+    const value = (ast as ESTree.BooleanLiteral).value
+    return () => value
+  }
+  if (ast.type === 'NullLiteral') {
+    return () => null
+  }
+  // 注意：Literal 类型已被更具体的类型（NumericLiteral, StringLiteral等）替代
+  // 如果遇到其他字面量类型，回退到解释执行
+  
+  // 标识符：{{ user }} → (ctx) => ctx._get('user')
+  // 注意：全局对象名称（window, document等）不应该被编译，应该回退到解释执行以进行安全检查
+  if (ast.type === 'Identifier') {
+    const name = ast.name
+    // 全局对象名称不应该被编译（需要安全检查）
+    const globalObjectNames = ['window', 'document', 'global', 'globalThis', 'self']
+    if (globalObjectNames.includes(name)) {
+      return null  // 回退到解释执行
+    }
+    return (ctx: RuntimeContext) => ctx._get(name)
+  }
+  
+  // 静态成员访问：{{ user.name }} → (ctx) => ctx._get('user.name')
+  // 注意：如果路径以全局对象名称开头，不应该被编译
+  const path = extractStaticPath(ast)
+  if (path) {
+    // 检查路径是否以全局对象名称开头
+    const globalObjectNames = ['window', 'document', 'global', 'globalThis', 'self']
+    const firstSegment = path.split('.')[0]
+    if (globalObjectNames.includes(firstSegment)) {
+      return null  // 回退到解释执行以进行安全检查
+    }
+    return (ctx: RuntimeContext) => ctx._get(path)
+  }
+  
+  return null  // 复杂表达式，无法编译
+}
+
+/**
+ * 获取或编译表达式
+ * 
+ * @param expr 表达式字符串
+ * @param ast AST 节点（已解析）
+ * @returns 编译后的函数，如果无法编译则返回 null
+ */
+export function getCompiledExpression(
+  expr: string,
+  ast: ESTree.Node
+): CompiledExpression | null {
+  // 检查缓存
+  if (compiledCache.has(expr)) {
+    return compiledCache.get(expr) || null
+  }
+  
+  // 尝试编译
+  const compiled = compileSimpleExpression(ast)
+  compiledCache.set(expr, compiled)
+  
+  return compiled
+}
+
+/**
+ * 清除编译缓存
+ */
+export function clearCompiledCache(): void {
+  compiledCache.clear()
+}

package/src/expression/dependencies.ts

@@ -0,0 +1,116 @@
+/**
+ * 依赖提取算法
+ * 
+ * 功能：
+ * - 从 AST 中提取状态依赖
+ * - 支持通配符依赖（items.*）
+ * - 保守策略：标记整个对象
+ */
+
+import type * as ESTree from '@babel/types'
+
+/**
+ * 从 AST 中提取依赖的状态路径
+ * 
+ * @param ast AST 节点
+ * @returns 依赖路径数组（支持通配符）
+ */
+export function extractDependencies(ast: ESTree.Node): string[] {
+  const dependencies = new Set<string>()
+  
+  function traverse(node: ESTree.Node, path: string = ''): void {
+    switch (node.type) {
+      case 'Identifier': {
+        const id = node as ESTree.Identifier
+        // 标识符可能是状态依赖（排除全局函数）
+        if (!isGlobalFunction(id.name)) {
+          dependencies.add(id.name)
+        }
+        break
+      }
+      
+      case 'MemberExpression': {
+        const member = node as ESTree.MemberExpression
+        const object = member.object
+        
+        if (object.type === 'Identifier') {
+          const basePath = object.name
+          
+          if (member.computed) {
+            // 计算属性：items[0] -> 保守策略：标记 items.*
+            dependencies.add(`${basePath}.*`)
+            traverse(member.property, path)
+          } else {
+            // 静态属性：user.name
+            const prop = (member.property as ESTree.Identifier).name
+            dependencies.add(`${basePath}.${prop}`)
+            // 同时添加通配符依赖（保守策略）
+            dependencies.add(`${basePath}.*`)
+          }
+        } else {
+          // 嵌套成员访问：user.profile.name
+          traverse(object, path)
+        }
+        
+        break
+      }
+      
+      case 'OptionalMemberExpression': {
+        const member = node as ESTree.OptionalMemberExpression
+        const object = member.object
+        
+        if (object.type === 'Identifier') {
+          const basePath = object.name
+          
+          if (member.computed) {
+            dependencies.add(`${basePath}.*`)
+            traverse(member.property, path)
+          } else {
+            const prop = (member.property as ESTree.Identifier).name
+            dependencies.add(`${basePath}.${prop}`)
+            dependencies.add(`${basePath}.*`)
+          }
+        } else {
+          traverse(object, path)
+        }
+        
+        break
+      }
+      
+      default: {
+        // 递归遍历所有子节点
+        for (const key in node) {
+          const value = (node as unknown as Record<string, unknown>)[key]
+          
+          if (value == null) continue
+          
+          if (Array.isArray(value)) {
+            value.forEach(child => {
+              if (child && typeof child === 'object' && 'type' in child) {
+                traverse(child as ESTree.Node, path)
+              }
+            })
+          } else if (value && typeof value === 'object' && 'type' in value) {
+            traverse(value as ESTree.Node, path)
+          }
+        }
+      }
+    }
+  }
+  
+  traverse(ast)
+  return Array.from(dependencies)
+}
+
+/**
+ * 检查是否为全局函数（不应作为依赖）
+ */
+function isGlobalFunction(name: string): boolean {
+  const globals = new Set([
+    'String', 'Number', 'Boolean', 'BigInt', 'Symbol',
+    'Array', 'Object', 'Math', 'Date',
+    'console', 'JSON', 'parseInt', 'parseFloat',
+    'isNaN', 'isFinite',
+  ])
+  return globals.has(name)
+}

package/src/expression/evaluate.ts

@@ -0,0 +1,95 @@
+/**
+ * 表达式求值入口函数
+ * 
+ * 整合解析、验证、缓存、求值流程
+ */
+
+import type { RuntimeContext, ExpressionOptions } from '../types.js'
+import { ExpressionError, ErrorCodes } from '../errors.js'
+import { parseExpression } from './parser.js'
+import { validateAST } from './whitelist.js'
+import { evaluateExpression } from './evaluator.js'
+import { extractDependencies } from './dependencies.js'
+import { getCompiledExpression } from './compiler.js'
+import {
+  getCachedExpression,
+  setCachedExpression,
+} from './cache.js'
+
+/**
+ * 求值表达式（完整流程）
+ * 
+ * @param expr 表达式字符串
+ * @param ctx 运行时上下文
+ * @returns 求值结果（类型无法静态推导，返回 unknown）
+ * 
+ * 注意：表达式求值结果类型无法在编译时确定，因为：
+ * 1. 表达式是运行时字符串
+ * 2. 状态类型是动态的
+ * 3. 表达式可能返回任意类型
+ * 
+ * 如果需要类型安全，应在使用结果时进行类型守卫或类型断言
+ */
+export function evaluate(
+  expr: string,
+  ctx: RuntimeContext,
+  options: ExpressionOptions = {}
+): unknown {
+  try {
+    // 合并选项：ctx.$exprOptions 优先级低于直接传入的 options
+    const mergedOptions = {
+      ...ctx.$exprOptions,
+      ...options
+    }
+    
+    // 1. 检查结果缓存
+    const cached = getCachedExpression(expr, ctx)
+    if (cached !== null) {
+      return cached
+    }
+    
+    // 2. 解析为 AST
+    const ast = parseExpression(expr)
+    
+    // 3. AST 白名单校验（传递 allowGlobals 和 maxNestingDepth 选项）
+    validateAST(ast, { 
+      allowGlobals: mergedOptions.allowGlobals,
+      maxNestingDepth: mergedOptions.maxNestingDepth
+    })
+    
+    // 4. 尝试使用编译缓存（简单表达式）
+    const compiled = getCompiledExpression(expr, ast)
+    if (compiled) {
+      const result = compiled(ctx)
+      // 提取依赖并缓存结果
+      const dependencies = extractDependencies(ast)
+      setCachedExpression(expr, result, dependencies, ctx)
+      return result
+    }
+    
+    // 5. 复杂表达式，使用解释执行
+    const result = evaluateExpression(ast, ctx, mergedOptions)
+    
+    // 6. 提取依赖并缓存
+    const dependencies = extractDependencies(ast)
+    setCachedExpression(expr, result, dependencies, ctx)
+    
+    return result
+  } catch (error: unknown) {
+    if (error instanceof ExpressionError) {
+      throw error
+    }
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    throw new ExpressionError(
+      expr,
+      `Expression evaluation failed: ${errorMessage}`,
+      ErrorCodes.EXPRESSION_EVALUATION_ERROR,
+      {
+        metadata: {
+          originalError: error instanceof Error ? error.name : 'Unknown',
+          stack: error instanceof Error ? error.stack?.split('\n').slice(0, 5) : undefined
+        }
+      }
+    )
+  }
+}