@variojs/core 0.1.0

package/src/expression/parser.ts

@@ -0,0 +1,54 @@
+/**
+ * 表达式解析器
+ * 
+ * 使用 @babel/parser 解析 JavaScript 表达式为 AST
+ * 移除 models. 前缀支持
+ */
+
+import { parse } from '@babel/parser'
+import type * as ESTree from '@babel/types'
+import { ExpressionError, ErrorCodes } from '../errors.js'
+
+/**
+ * 解析表达式为 AST
+ * 
+ * @param expr 表达式字符串（如 "user.name + 1"）
+ * @returns ESTree.Node AST 节点
+ */
+export function parseExpression(expr: string): ESTree.Node {
+  try {
+    // 解析为表达式（ExpressionStatement）
+    const ast = parse(`(${expr})`, {
+      plugins: ['typescript'],
+      sourceType: 'module',
+      allowReturnOutsideFunction: true,
+    })
+    
+    // 提取表达式部分
+    const statement = ast.program.body[0]
+    if (statement?.type === 'ExpressionStatement') {
+      return statement.expression
+    }
+    
+    throw new ExpressionError(
+      expr,
+      `Failed to parse expression: ${expr}`,
+      ErrorCodes.EXPRESSION_PARSE_ERROR
+    )
+  } catch (error: unknown) {
+    if (error instanceof ExpressionError) {
+      throw error
+    }
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    throw new ExpressionError(
+      expr,
+      `Expression parse error: ${errorMessage}`,
+      ErrorCodes.EXPRESSION_PARSE_ERROR,
+      {
+        metadata: {
+          originalError: error instanceof Error ? error.name : 'Unknown'
+        }
+      }
+    )
+  }
+}

package/src/expression/utils.ts

@@ -0,0 +1,89 @@
+/**
+ * 表达式工具函数
+ * 
+ * 提供表达式解析、格式化的通用工具
+ * 支持 {{ }} 格式的表达式提取和规范化
+ */
+
+/**
+ * 提取表达式字符串
+ * 支持 {{ expression }} 格式，自动去掉包装
+ * 
+ * @param expr 表达式字符串，可能是 "{{ showContent }}" 或 "showContent"
+ * @returns 去掉 {{ }} 包装后的表达式字符串
+ * 
+ * @example
+ * ```typescript
+ * extractExpression("{{ showContent }}") // => "showContent"
+ * extractExpression("showContent") // => "showContent"
+ * extractExpression("{{ userRole === 'admin' }}") // => "userRole === 'admin'"
+ * ```
+ */
+export function extractExpression(expr: string): string {
+  if (typeof expr !== 'string') {
+    return String(expr)
+  }
+  
+  // 如果表达式是 {{ }} 格式，去掉包装
+  if (expr.startsWith('{{') && expr.endsWith('}}')) {
+    return expr.slice(2, -2).trim()
+  }
+  
+  return expr.trim()
+}
+
+/**
+ * 规范化表达式字符串
+ * 确保表达式格式统一，便于后续处理
+ * 
+ * @param expr 表达式字符串
+ * @returns 规范化后的表达式字符串（去掉 {{ }} 包装）
+ */
+export function normalizeExpression(expr: string): string {
+  return extractExpression(expr)
+}
+
+/**
+ * 检查是否为表达式格式
+ * 
+ * @param value 要检查的值
+ * @returns 如果是 {{ }} 格式返回 true
+ */
+export function isExpressionFormat(value: any): boolean {
+  return typeof value === 'string' && value.startsWith('{{') && value.endsWith('}}')
+}
+
+/**
+ * 批量提取表达式
+ * 从对象或数组中提取所有表达式字符串
+ * 
+ * @param value 要处理的值（对象、数组或字符串）
+ * @param extractor 提取函数，默认使用 extractExpression
+ * @returns 处理后的值
+ */
+export function extractExpressionsRecursively(
+  value: any,
+  extractor: (expr: string) => string = extractExpression
+): any {
+  // 字符串：检查是否为表达式
+  if (typeof value === 'string') {
+    return extractor(value)
+  }
+  
+  // 数组：递归处理每个元素
+  if (Array.isArray(value)) {
+    return value.map(item => extractExpressionsRecursively(item, extractor))
+  }
+  
+  // 对象：递归处理每个属性值
+  if (value && typeof value === 'object') {
+    const result: Record<string, any> = {}
+    for (const [key, val] of Object.entries(value)) {
+      result[key] = extractExpressionsRecursively(val, extractor)
+    }
+    return result
+  }
+  
+  // 其他类型：直接返回
+  return value
+}

package/src/expression/whitelist.ts

@@ -0,0 +1,224 @@
+/**
+ * AST 白名单验证器
+ * 
+ * 功能：
+ * - 深度遍历 AST，检查每个节点
+ * - 只允许安全的语法节点
+ * - 禁止危险的语法（赋值、函数、this 等）
+ * - 检查函数调用中的函数名是否在白名单中
+ */
+
+import type * as ESTree from '@babel/types'
+import { ExpressionError, ErrorCodes } from '../errors.js'
+
+/**
+ * 白名单全局函数
+ */
+const WHITELISTED_GLOBALS = new Set([
+  'String', 'Number', 'Boolean', 'BigInt', 'Symbol',
+  'Array', 'Object', 'Math', 'Date',
+])
+
+/**
+ * 白名单函数（带命名空间）
+ */
+const WHITELISTED_FUNCTIONS = new Set([
+  'Array.isArray',
+  'Object.is',
+  'Number.isFinite',
+  'Number.isInteger',
+  'Number.isNaN',
+  'Number.isSafeInteger',
+  'Math.abs',
+  'Math.round',
+  'Math.floor',
+  'Math.ceil',
+  'Math.random',
+  'Math.max',
+  'Math.min',
+  'Date.now',
+])
+
+/**
+ * 检查名称是否为全局对象名称
+ */
+function isGlobalObjectName(name: string): boolean {
+  return ['window', 'document', 'global', 'globalThis', 'self'].includes(name)
+}
+
+/**
+ * 允许的 AST 节点类型
+ * 
+ * 注意：@babel/types 可能使用更具体的字面量类型（如 NumericLiteral, StringLiteral）
+ * 这些都应该被允许，因为它们都是 Literal 的子类型
+ */
+const ALLOWED_NODE_TYPES = new Set([
+  'MemberExpression',      // 成员访问：user.name
+  'OptionalMemberExpression', // 可选链：user?.name
+  'ArrayExpression',       // 数组字面量：[1, 2, 3]
+  'ObjectExpression',      // 对象字面量：{ a: 1 }
+  'ObjectProperty',        // 对象属性：{ a: 1 } 中的 a: 1
+  'Literal',               // 字面量：'string', 123, true
+  'NumericLiteral',        // 数字字面量：123（@babel/types 的具体类型）
+  'StringLiteral',         // 字符串字面量：'string'
+  'BooleanLiteral',        // 布尔字面量：true, false
+  'NullLiteral',           // null 字面量
+  'Identifier',            // 标识符：user, name
+  'BinaryExpression',     // 二元运算：a + b
+  'LogicalExpression',     // 逻辑运算：a && b
+  'UnaryExpression',       // 一元运算：!a, -b
+  'ConditionalExpression', // 三元表达式：a ? b : c
+  'CallExpression',        // 函数调用：Math.max()
+  'TemplateLiteral',      // 模板字符串：`${name}`
+  'SequenceExpression',   // 序列表达式：(a, b)
+  'NullishCoalescingExpression', // 空值合并：a ?? b
+])
+
+/**
+ * 禁止的 AST 节点类型
+ */
+const FORBIDDEN_NODE_TYPES = new Set([
+  'AssignmentExpression',      // 赋值：a = b
+  'UpdateExpression',          // 自增/自减：a++, --b
+  'FunctionExpression',         // 函数表达式：function() {}
+  'ArrowFunctionExpression',    // 箭头函数：() => {}
+  'ThisExpression',            // this
+  'NewExpression',             // new 运算符
+  'YieldExpression',          // yield
+  'AwaitExpression',           // await
+  'ImportExpression',          // import()
+  'MetaProperty',              // import.meta
+  'SpreadElement',             // 展开运算符：...array（在函数调用中不安全）
+])
+
+/**
+ * 默认最大嵌套深度（防止 DoS 攻击）
+ */
+const DEFAULT_MAX_NESTING_DEPTH = 50
+
+/**
+ * 验证 AST 是否通过白名单检查
+ * 
+ * @param ast AST 节点
+ * @param options 验证选项
+ * @param options.allowGlobals 是否允许全局函数调用（跳过白名单检查）
+ * @param options.maxNestingDepth 最大嵌套深度（默认 50）
+ * @throws ExpressionError 如果发现禁止的节点
+ */
+export function validateAST(ast: ESTree.Node, options?: { allowGlobals?: boolean; maxNestingDepth?: number }): void {
+  const allowGlobals = options?.allowGlobals === true
+  const maxNestingDepth = options?.maxNestingDepth ?? DEFAULT_MAX_NESTING_DEPTH
+  const errors: string[] = []
+  
+  function getFunctionName(callee: ESTree.Node): string | null {
+    if (callee.type === 'Identifier') {
+      return callee.name
+    }
+    if (callee.type === 'MemberExpression') {
+      const member = callee as ESTree.MemberExpression
+      if (member.object.type === 'Identifier' && member.property.type === 'Identifier') {
+        return `${member.object.name}.${member.property.name}`
+      }
+    }
+    return null
+  }
+
+  function traverse(node: ESTree.Node, path: string = 'root', depth: number = 0): void {
+    // 检查嵌套深度（防止 DoS 攻击）
+    if (depth > maxNestingDepth) {
+      errors.push(`Maximum nesting depth (${maxNestingDepth}) exceeded at ${path}`)
+      return
+    }
+    
+    // 检查节点类型
+    if (FORBIDDEN_NODE_TYPES.has(node.type)) {
+      errors.push(`Forbidden node type "${node.type}" at ${path}`)
+      return
+    }
+    
+    // 检查函数调用中的函数名
+    if (node.type === 'CallExpression') {
+      const call = node as ESTree.CallExpression
+      const funcName = getFunctionName(call.callee)
+      if (funcName) {
+        // 检查是否为危险函数（eval, Function, etc.）- 即使 allowGlobals 也禁止
+        const dangerousFunctions = ['eval', 'Function', 'setTimeout', 'setInterval', 'execScript']
+        if (dangerousFunctions.includes(funcName) || funcName.startsWith('eval') || funcName.startsWith('Function')) {
+          errors.push(`Dangerous function "${funcName}" is not allowed at ${path}`)
+          return
+        }
+        
+        // 如果 allowGlobals，跳过白名单检查
+        if (!allowGlobals) {
+          // 检查是否为全局函数调用（如 Array.isArray, Math.max）
+          const isGlobalFunction = 
+            WHITELISTED_FUNCTIONS.has(funcName) ||
+            WHITELISTED_GLOBALS.has(funcName.split('.')[0])
+          
+          // 检查是否为对象方法调用（如 array.slice, user.getName）
+          // 如果 callee 是 MemberExpression 且 object 不是全局对象，则允许
+          let isObjectMethod = false
+          if (call.callee.type === 'MemberExpression') {
+            const member = call.callee as ESTree.MemberExpression
+            // 如果 object 是 Identifier（变量名），且不在全局对象白名单中，则认为是对象方法
+            if (member.object.type === 'Identifier') {
+              const objName = member.object.name
+              // 不是全局对象名称，则认为是用户数据的对象方法
+              if (!WHITELISTED_GLOBALS.has(objName) && !isGlobalObjectName(objName)) {
+                isObjectMethod = true
+              }
+            }
+          }
+          
+          if (!isGlobalFunction && !isObjectMethod && !funcName.startsWith('$')) {
+            // 不在白名单中的函数，禁止调用
+            errors.push(`Function "${funcName}" is not in whitelist at ${path}`)
+            return
+          }
+        }
+      }
+    }
+    
+    if (!ALLOWED_NODE_TYPES.has(node.type) && node.type !== 'Program') {
+      // 未知节点类型，保守策略：禁止
+      errors.push(`Unknown node type "${node.type}" at ${path}`)
+      return
+    }
+    
+    // 递归遍历子节点
+    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, index) => {
+          if (child && typeof child === 'object' && 'type' in child) {
+            traverse(child as ESTree.Node, `${path}[${index}]`, depth + 1)
+          }
+        })
+      }
+      // 处理对象节点
+      else if (value && typeof value === 'object' && 'type' in value) {
+        traverse(value as ESTree.Node, `${path}.${key}`, depth + 1)
+      }
+    }
+  }
+  
+  traverse(ast, 'root', 0)
+  
+  if (errors.length > 0) {
+    throw new ExpressionError(
+      JSON.stringify(ast),
+      `AST validation failed:\n${errors.join('\n')}`,
+      ErrorCodes.EXPRESSION_VALIDATION_ERROR,
+      {
+        metadata: {
+          errors,
+          nodeType: ast.type
+        }
+      }
+    )
+  }
+}

package/src/globals.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 全局类型声明
+ * 用于支持跨平台代码（Node.js 和浏览器）
+ */
+
+// 声明全局变量，避免 TypeScript 错误（使用 any 以避免 DOM lib 依赖）
+declare const window: any
+declare const document: any
+declare const self: any
+declare const global: typeof globalThis | undefined

package/src/index.ts

@@ -0,0 +1,72 @@
+/**
+ * @vario/core - Vario Core Runtime
+ * 
+ * 核心运行时模块，包含：
+ * - RuntimeContext: 扁平化状态 + $ 前缀系统 API
+ * - Expression System: 安全表达式求值
+ * - Action VM: 动作虚拟机
+ * - Path Utilities: 统一的路径解析工具
+ */
+
+// Runtime
+export {
+  createRuntimeContext,
+  createProxy,
+  createExpressionSandbox,
+  isSafePropertyAccess,
+  // 循环上下文（供框架集成层使用）
+  createLoopContext,
+  releaseLoopContext,
+  // 路径工具（供框架集成层使用）
+  parsePath,
+  parsePathCached,
+  clearPathCache,
+  stringifyPath,
+  getPathValue,
+  setPathValue,
+  matchPath,
+  getParentPath,
+  getLastSegment
+} from './runtime/index.js'
+export type { RuntimeContext } from './types.js'
+export type { PathSegment } from './runtime/path.js'
+export type { CreateContextOptions } from './runtime/create-context.js'
+
+// Expression
+export {
+  parseExpression,
+  validateAST,
+  evaluateExpression,
+  evaluate,
+  extractExpression,
+  extractDependencies,
+  getCachedExpression,
+  setCachedExpression,
+  invalidateCache,
+  clearCache
+} from './expression/index.js'
+
+// VM
+export {
+  execute,
+  registerBuiltinMethods
+} from './vm/index.js'
+export type { ExecuteOptions } from './vm/index.js'
+export {
+  ActionError,
+  ExpressionError,
+  ServiceError,
+  BatchError,
+  VarioError,
+  ErrorCodes,
+  type ErrorContext,
+  type ErrorCode
+} from './errors.js'
+export type { 
+  Action, 
+  ActionMap,
+  ActionHandler,
+  ExpressionCache, 
+  MethodsRegistry, 
+  ExpressionOptions 
+} from './types.js'

package/src/runtime/context.ts

@@ -0,0 +1,8 @@
+/**
+ * Runtime Context
+ * 
+ * 运行时上下文主模块，导出创建函数
+ */
+
+export { createRuntimeContext } from './create-context.js'
+export type { RuntimeContext } from '../types.js'

package/src/runtime/create-context.ts

@@ -0,0 +1,133 @@
+/**
+ * RuntimeContext 创建工厂
+ * 
+ * 实现要点：
+ * - 扁平化状态存储
+ * - 系统 API 保护（$ 和 _ 前缀）
+ * - 命名冲突检测
+ * - Proxy 拦截防止覆盖系统 API
+ */
+
+import type { RuntimeContext, MethodsRegistry, GetPathValue, SetPathValue, ExpressionOptions } from '../types.js'
+import { createProxy } from './proxy.js'
+import { registerBuiltinMethods } from '../vm/handlers/index.js'
+import { getPathValue as getPath, setPathValue as setPath } from './path.js'
+import { invalidateCache } from '../expression/cache.js'
+
+/**
+ * RuntimeContext 创建选项
+ */
+export interface CreateContextOptions {
+  /**
+   * 事件发射回调
+   */
+  onEmit?: (event: string, data?: unknown) => void
+  
+  /**
+   * 预注册的方法
+   */
+  methods?: MethodsRegistry
+  
+  /**
+   * 状态变更钩子（用于框架集成）
+   * 在 _set 调用后触发，可用于缓存失效等
+   */
+  onStateChange?: (path: string, value: unknown, ctx: RuntimeContext) => void
+  
+  /**
+   * 创建对象的工厂函数（用于框架集成创建响应式对象）
+   */
+  createObject?: () => Record<string, unknown>
+  
+  /**
+   * 创建数组的工厂函数（用于框架集成创建响应式数组）
+   */
+  createArray?: () => unknown[]
+
+  /**
+   * 表达式求值配置
+   */
+  exprOptions?: ExpressionOptions
+}
+
+/**
+ * 创建运行时上下文
+ * 
+ * @param initialState 初始状态（扁平化）
+ * @param options 配置选项
+ * 
+ * @template TState 状态类型，从 initialState 推导
+ */
+export function createRuntimeContext<
+  TState extends Record<string, unknown> = Record<string, unknown>
+>(
+  initialState: Partial<TState> = {} as Partial<TState>,
+  options: CreateContextOptions = {}
+): RuntimeContext<TState> {
+  // 1. 验证命名冲突
+  validateStateKeys(initialState)
+
+  const {
+    onEmit,
+    methods = {},
+    onStateChange,
+    createObject = () => ({}),
+    createArray = () => [],
+    exprOptions
+  } = options
+
+  // 用于存储 proxied 引用，以便 _set 中的 onStateChange 能使用正确的引用
+  let proxiedRef: RuntimeContext<TState> | null = null
+
+  // 2. 创建基础上下文对象
+  const ctx = {
+    ...initialState,
+    $emit: (event: string, data?: unknown) => {
+      if (onEmit) {
+        onEmit(event, data)
+      }
+    },
+    $methods: methods as MethodsRegistry,
+    $exprOptions: exprOptions,
+    _get: <TPath extends string>(path: TPath): GetPathValue<TState, TPath> => {
+      return getPath(ctx as Record<string, unknown>, path) as GetPathValue<TState, TPath>
+    },
+    _set: <TPath extends string>(path: TPath, value: SetPathValue<TState, TPath>, options?: { skipCallback?: boolean }): void => {
+      setPath(ctx as Record<string, unknown>, path, value, {
+        createObject,
+        createArray
+      })
+      // 使缓存失效（使用 proxied 引用以确保缓存键一致）
+      invalidateCache(path, (proxiedRef || ctx) as RuntimeContext)
+      // 触发状态变更钩子
+      if (onStateChange && !options?.skipCallback) {
+        onStateChange(path, value, (proxiedRef || ctx) as RuntimeContext)
+      }
+    },
+  } as RuntimeContext<TState>
+
+  // 3. 自动注册内置指令到 $methods
+  registerBuiltinMethods(ctx as RuntimeContext)
+
+  // 4. 使用 Proxy 保护系统 API
+  const proxied = createProxy(ctx as unknown as RuntimeContext) as RuntimeContext<TState>
+  
+  // 5. 保存 proxied 引用供 _set 使用
+  proxiedRef = proxied
+  
+  return proxied
+}
+
+/**
+ * 验证状态键名，防止与系统 API 冲突
+ */
+function validateStateKeys(state: Record<string, unknown>): void {
+  for (const key in state) {
+    if (key.startsWith('$') || key.startsWith('_')) {
+      throw new Error(
+        `Property name "${key}" conflicts with system API. ` +
+        `Properties starting with "$" or "_" are reserved. Use a different name.`
+      )
+    }
+  }
+}

package/src/runtime/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Runtime 模块导出
+ */
+
+export { createRuntimeContext } from './create-context.js'
+export { createProxy } from './proxy.js'
+export { createExpressionSandbox, isSafePropertyAccess } from './sandbox.js'
+export {
+  createLoopContext,
+  releaseLoopContext,
+  getLoopContextPool,
+  clearLoopContextPool
+} from './loop-context-pool.js'
+export type { RuntimeContext } from '../types.js'
+
+// 路径工具（供框架集成层使用）
+export {
+  parsePath,
+  parsePathCached,
+  clearPathCache,
+  stringifyPath,
+  getPathValue,
+  setPathValue,
+  matchPath,
+  getParentPath,
+  getLastSegment,
+  type PathSegment
+} from './path.js'