@variojs/core 0.1.0

package/src/types.ts

@@ -0,0 +1,177 @@
+/**
+ * Vario Core Types
+ * 
+ * 核心类型定义，遵循架构图设计：
+ * - RuntimeContext: 扁平化状态 + $ 前缀系统 API
+ * - Action: 动作接口
+ * - ExpressionCache: 表达式缓存
+ */
+
+/**
+ * 方法处理器类型
+ * 所有注册到 $methods 的方法必须符合此签名
+ * 
+ * 注意：动作处理器也通过 $methods 注册，但它们的参数是 Action
+ */
+export type MethodHandler<TParams = unknown, TResult = unknown> = (
+  ctx: RuntimeContext,
+  params: TParams
+) => Promise<TResult> | TResult
+
+/**
+ * 动作处理器类型（特殊的方法处理器）
+ */
+export type ActionHandler = MethodHandler<Action, void>
+
+/**
+ * 方法注册表类型
+ * 支持普通方法和指令处理器
+ */
+export type MethodsRegistry = Record<string, MethodHandler>
+
+/**
+ * 表达式求值选项
+ */
+export interface ExpressionOptions {
+  /**
+   * 是否允许访问全局对象（默认 false）
+   */
+  allowGlobals?: boolean
+  /**
+   * 最大求值步数
+   */
+  maxSteps?: number
+  /**
+   * 求值超时（毫秒）
+   */
+  timeout?: number
+  /**
+   * 最大嵌套深度（防止 DoS 攻击，默认 50）
+   */
+  maxNestingDepth?: number
+}
+
+/**
+ * 运行时上下文接口
+ * 扁平化状态设计：直接属性访问，无 models. 前缀
+ * 
+ * @template TState 状态类型，用于类型推导和约束
+ * 
+ * 设计说明：
+ * - 使用接口 + 索引签名，既支持类型推导又支持动态属性
+ * - 状态属性通过 TState 泛型约束
+ * - 系统 API 使用具体类型定义，确保类型安全
+ */
+/**
+ * 运行时上下文类型
+ * 使用交叉类型结合接口，既支持状态类型推导又支持动态属性
+ */
+export type RuntimeContext<TState extends Record<string, unknown> = Record<string, unknown>> = 
+  // 状态属性（从 TState 推导）
+  TState &
+  // 系统 API（$ 前缀）
+  {
+    $emit: (event: string, data?: unknown) => void
+    $methods: MethodsRegistry
+    $exprOptions?: ExpressionOptions
+    $event?: Event  // 事件对象（在事件处理中可用）
+    $item?: TState[keyof TState]  // 循环当前项（在 Table/loop 中可用）
+    $index?: number  // 循环索引（在 Table/loop 中可用）
+    // 内部方法（路径解析，不对外暴露）
+    _get: <TPath extends string>(path: TPath) => GetPathValue<TState, TPath>
+    _set: <TPath extends string>(path: TPath, value: SetPathValue<TState, TPath>, options?: { skipCallback?: boolean }) => void
+  } &
+  // 允许动态添加状态属性（运行时扩展）
+  Record<string, unknown>
+
+/**
+ * 路径值类型推导工具
+ * 根据路径字符串推导对应的值类型
+ * 
+ * @example
+ * GetPathValue<{ user: { name: string } }, 'user.name'> // string
+ * GetPathValue<{ items: number[] }, 'items.0'> // number
+ */
+export type GetPathValue<T, TPath extends string> = 
+  TPath extends `${infer Key}.${infer Rest}`
+    ? Key extends keyof T
+      ? T[Key] extends Record<string, unknown>
+        ? GetPathValue<T[Key], Rest>
+        : unknown
+      : unknown
+    : TPath extends keyof T
+      ? T[TPath]
+      : unknown
+
+/**
+ * 路径设置值类型推导工具
+ * 根据路径字符串推导可以设置的值类型
+ */
+export type SetPathValue<T, TPath extends string> = GetPathValue<T, TPath>
+
+/**
+ * 动作接口
+ * 使用泛型约束，根据 type 类型推导参数结构
+ */
+export interface Action {
+  type: string
+  [key: string]: unknown
+}
+
+/**
+ * 动作类型映射
+ * 根据 type 值推导对应的动作参数类型
+ */
+export type ActionMap = {
+  set: { path: string; value: string | unknown }
+  emit: { event: string; data?: string | unknown }
+  navigate: { to: string }
+  log: { level?: 'info' | 'warn' | 'error'; message: string }
+  if: { cond: string; then?: Action[]; else?: Action[] }
+  loop: { var: string; in: string; body: Action[] }
+  call: { method: string; params?: Record<string, unknown>; resultTo?: string }
+  batch: { actions: Action[] }
+  push: { path: string; value: string | unknown }
+  pop: { path: string }
+  shift: { path: string }
+  unshift: { path: string; value: string | unknown }
+  splice: { path: string; start: number | string; deleteCount?: number | string; items?: string | unknown[] }
+}
+
+/**
+ * 类型守卫：检查动作是否符合特定类型
+ */
+export function isActionOfType<T extends keyof ActionMap>(
+  action: Action,
+  actionType: T
+): action is Action & ActionMap[T] {
+  return action.type === actionType
+}
+
+/**
+ * 表达式缓存接口
+ * 结果类型使用 unknown，因为表达式求值结果类型无法静态推导
+ */
+export interface ExpressionCache {
+  expr: string
+  result: unknown  // 表达式求值结果，类型无法静态推导
+  dependencies: string[]  // 支持通配符：['items.*', 'user.name']
+  timestamp: number
+}
+
+/**
+ * 错误类型定义
+ * 
+ * @deprecated 使用 @vario/core/errors 中的错误类
+ * 保留这些导出以保持向后兼容，但建议使用新的错误体系
+ */
+export {
+  ActionError,
+  ExpressionError,
+  ServiceError,
+  BatchError,
+  VarioError,
+  ErrorCodes,
+  type ErrorContext,
+  type ErrorCode
+} from './errors.js'

package/src/vm/errors.ts

@@ -0,0 +1,10 @@
+/**
+ * Action VM 错误类型
+ */
+
+export {
+  ActionError,
+  ExpressionError,
+  ServiceError,
+  BatchError
+} from '../types.js'

package/src/vm/executor.ts

@@ -0,0 +1,210 @@
+/**
+ * Action VM 执行器
+ * 
+ * 功能：
+ * - 执行动作序列
+ * - 通过 $methods 查找动作处理器
+ * - 错误处理和堆栈跟踪
+ * - 超时保护（防止无限循环）
+ * 
+ * 参考架构图：vario-core/vm - Action VM
+ */
+
+import type { RuntimeContext, Action } from '../types.js'
+import { ActionError, ServiceError, ErrorCodes } from '../errors.js'
+
+/**
+ * 执行动作序列的选项
+ */
+export interface ExecuteOptions {
+  /**
+   * 超时时间（毫秒），默认 5000ms
+   */
+  timeout?: number
+  /**
+   * 最大执行步数，默认 10000
+   * 每执行一个动作计为一步
+   */
+  maxSteps?: number
+}
+
+/**
+ * 执行动作序列
+ * 
+ * @param actions 动作数组
+ * @param ctx 运行时上下文
+ * @param options 执行选项
+ */
+export async function execute(
+  actions: Action[],
+  ctx: RuntimeContext,
+  options: ExecuteOptions = {}
+): Promise<void> {
+  const timeout = options.timeout ?? 5000
+  const maxSteps = options.maxSteps ?? 10000
+  const startTime = Date.now()
+  let stepCount = 0
+  
+  // 创建 AbortController 用于超时中断（如果支持）
+  let abortController: AbortController | null = null
+  if (typeof AbortController !== 'undefined') {
+    abortController = new AbortController()
+    
+    // 设置超时定时器
+    const timeoutId = setTimeout(() => {
+      abortController?.abort()
+    }, timeout)
+    
+    // 清理定时器（如果执行完成）
+    const cleanup = () => clearTimeout(timeoutId)
+    
+    try {
+      await executeActions(actions, ctx, abortController.signal, maxSteps, () => {
+        stepCount++
+        if (stepCount > maxSteps) {
+          throw new ActionError(
+            actions[actions.length - 1] || { type: 'unknown' } as Action,
+            `Action execution exceeded max steps (${maxSteps})`,
+            ErrorCodes.ACTION_MAX_STEPS_EXCEEDED,
+            {
+              metadata: {
+                maxSteps,
+                currentSteps: stepCount
+              }
+            }
+          )
+        }
+        // 检查超时
+        if (Date.now() - startTime > timeout) {
+          throw new ActionError(
+            actions[actions.length - 1] || { type: 'unknown' } as Action,
+            `Action execution exceeded timeout (${timeout}ms)`,
+            ErrorCodes.ACTION_TIMEOUT,
+            {
+              metadata: {
+                timeout,
+                elapsedTime: Date.now() - startTime
+              }
+            }
+          )
+        }
+      })
+      cleanup()
+    } catch (error) {
+      cleanup()
+      throw error
+    }
+  } else {
+    // 不支持 AbortController 的环境，使用时间检查
+    await executeActions(actions, ctx, null, maxSteps, () => {
+      stepCount++
+      if (stepCount > maxSteps) {
+        throw new ActionError(
+          actions[actions.length - 1] || { type: 'unknown' } as Action,
+          `Action execution exceeded max steps (${maxSteps})`,
+          ErrorCodes.ACTION_MAX_STEPS_EXCEEDED,
+          {
+            metadata: {
+              maxSteps,
+              currentSteps: stepCount
+            }
+          }
+        )
+      }
+      // 检查超时
+      if (Date.now() - startTime > timeout) {
+        throw new ActionError(
+          actions[actions.length - 1] || { type: 'unknown' } as Action,
+          `Action execution exceeded timeout (${timeout}ms)`,
+          ErrorCodes.ACTION_TIMEOUT,
+          {
+            metadata: {
+              timeout,
+              elapsedTime: Date.now() - startTime
+            }
+          }
+        )
+      }
+    })
+  }
+  
+  // 最终检查超时（即使有 AbortController，也做双重检查）
+  if (Date.now() - startTime > timeout) {
+    throw new ActionError(
+      actions[actions.length - 1] || { type: 'unknown' } as Action,
+      `Action execution exceeded timeout (${timeout}ms)`,
+      ErrorCodes.ACTION_TIMEOUT,
+      {
+        metadata: {
+          timeout,
+          elapsedTime: Date.now() - startTime,
+          actionCount: actions.length
+        }
+      }
+    )
+  }
+}
+
+/**
+ * 执行动作序列（内部实现）
+ */
+async function executeActions(
+  actions: Action[],
+  ctx: RuntimeContext,
+  signal: AbortSignal | null,
+  _maxSteps: number,  // 用于类型，实际限制在 checkLimits 中检查
+  checkLimits: () => void
+): Promise<void> {
+  for (const action of actions) {
+    // 检查中断信号
+    if (signal?.aborted) {
+      throw new ActionError(
+        action,
+        'Action execution was aborted',
+        ErrorCodes.ACTION_ABORTED
+      )
+    }
+    
+    // 检查步数和超时限制
+    checkLimits()
+    
+    // 所有动作（包括内置动作）统一通过 $methods 注册
+    const handler = ctx.$methods[action.type]
+    
+    if (!handler) {
+      throw new ActionError(
+        action,
+        `Unknown action type: ${action.type}. Make sure the action is registered in $methods`,
+        ErrorCodes.ACTION_UNKNOWN_TYPE
+      )
+    }
+    
+    try {
+      await handler(ctx, action)
+    } catch (error: unknown) {
+      // 如果已经是 ActionError，直接抛出
+      if (error instanceof ActionError) {
+        throw error
+      }
+      
+      // 如果已经是 ServiceError，直接抛出
+      if (error instanceof ServiceError) {
+        throw error
+      }
+      
+      // 包装为 ActionError，收集上下文信息
+      const errorMessage = error instanceof Error ? error.message : String(error)
+      throw new ActionError(
+        action,
+        `Action execution failed: ${errorMessage}`,
+        ErrorCodes.ACTION_EXECUTION_ERROR,
+        {
+          metadata: {
+            originalError: error instanceof Error ? error.name : 'Unknown',
+            stack: error instanceof Error ? error.stack?.split('\n').slice(0, 5) : undefined
+          }
+        }
+      )
+    }
+  }
+}

package/src/vm/handlers/array/pop.ts

@@ -0,0 +1,47 @@
+/**
+ * pop 动作处理器
+ * 
+ * 功能：删除数组末尾元素
+ * 示例：{ "type": "pop", "path": "items" }
+ */
+
+import type { RuntimeContext, Action } from '@/types.js'
+import { ActionError, ErrorCodes } from '@/errors.js'
+import { invalidateCache } from '@/expression/cache.js'
+
+/**
+ * 处理 pop 动作
+ */
+export async function handlePop(
+  ctx: RuntimeContext,
+  action: Action
+): Promise<void> {
+  const { path } = action
+  
+  if (!path || typeof path !== 'string') {
+    throw new ActionError(
+      action,
+      'pop action requires "path" parameter',
+      ErrorCodes.ACTION_MISSING_PARAM,
+      { metadata: { param: 'path' } }
+    )
+  }
+  
+  // 获取数组
+  const array = ctx._get(path)
+  if (!Array.isArray(array)) {
+    throw new ActionError(
+      action,
+      `Path "${path}" does not point to an array`,
+      ErrorCodes.ACTION_INVALID_PARAM,
+      { metadata: { param: 'path', path, actualType: typeof array } }
+    )
+  }
+  
+  // 删除末尾元素
+  array.pop()
+  
+  // 使相关缓存失效
+  invalidateCache(path, ctx)
+  invalidateCache(`${path}.*`, ctx)
+}

package/src/vm/handlers/array/push.ts

@@ -0,0 +1,68 @@
+/**
+ * push 动作处理器
+ * 
+ * 功能：添加元素到数组末尾
+ * 示例：{ "type": "push", "path": "items", "value": "{{ newItem }}" }
+ * 示例：{ "type": "push", "path": "todos", "items": [{ text: "{{ newTodo }}", done: false }] }
+ */
+
+import type { RuntimeContext, Action } from '@/types.js'
+import { ActionError, ErrorCodes } from '@/errors.js'
+import { invalidateCache } from '@/expression/cache.js'
+import { evaluateExpressionsRecursively } from './utils.js'
+
+/**
+ * 处理 push 动作
+ */
+export async function handlePush(
+  ctx: RuntimeContext,
+  action: Action
+): Promise<void> {
+  const { path, value, items } = action
+  
+  if (!path || typeof path !== 'string') {
+    throw new ActionError(
+      action,
+      'push action requires "path" parameter',
+      ErrorCodes.ACTION_MISSING_PARAM,
+      { metadata: { param: 'path' } }
+    )
+  }
+  
+  // 获取数组
+  const array = ctx._get(path)
+  if (!Array.isArray(array)) {
+    throw new ActionError(
+      action,
+      `Path "${path}" does not point to an array`,
+      ErrorCodes.ACTION_INVALID_PARAM,
+      { metadata: { param: 'path', path, actualType: typeof array } }
+    )
+  }
+  
+  // 支持 items 作为 value 的别名
+  const inputValue = items !== undefined ? items : value
+  
+  if (inputValue === undefined) {
+    throw new ActionError(
+      action,
+      'push action requires "value" or "items" parameter',
+      ErrorCodes.ACTION_MISSING_PARAM,
+      { metadata: { param: 'value|items' } }
+    )
+  }
+  
+  // 递归求值表达式（支持对象/数组中的表达式）
+  const finalValue = evaluateExpressionsRecursively(inputValue, ctx)
+  
+  // 如果是数组，展开添加
+  if (Array.isArray(finalValue)) {
+    array.push(...finalValue)
+  } else {
+    array.push(finalValue)
+  }
+  
+  // 使相关缓存失效
+  invalidateCache(path, ctx)
+  invalidateCache(`${path}.*`, ctx)
+}

package/src/vm/handlers/array/shift.ts

@@ -0,0 +1,47 @@
+/**
+ * shift 动作处理器
+ * 
+ * 功能：删除数组首元素
+ * 示例：{ "type": "shift", "path": "items" }
+ */
+
+import type { RuntimeContext, Action } from '@/types.js'
+import { ActionError, ErrorCodes } from '@/errors.js'
+import { invalidateCache } from '@/expression/cache.js'
+
+/**
+ * 处理 shift 动作
+ */
+export async function handleShift(
+  ctx: RuntimeContext,
+  action: Action
+): Promise<void> {
+  const { path } = action
+  
+  if (!path || typeof path !== 'string') {
+    throw new ActionError(
+      action,
+      'shift action requires "path" parameter',
+      ErrorCodes.ACTION_MISSING_PARAM,
+      { metadata: { param: 'path' } }
+    )
+  }
+  
+  // 获取数组
+  const array = ctx._get(path)
+  if (!Array.isArray(array)) {
+    throw new ActionError(
+      action,
+      `Path "${path}" does not point to an array`,
+      ErrorCodes.ACTION_INVALID_PARAM,
+      { metadata: { param: 'path', path, actualType: typeof array } }
+    )
+  }
+  
+  // 删除首元素
+  array.shift()
+  
+  // 使相关缓存失效
+  invalidateCache(path, ctx)
+  invalidateCache(`${path}.*`, ctx)
+}

package/src/vm/handlers/array/splice.ts

@@ -0,0 +1,78 @@
+/**
+ * splice 动作处理器
+ * 
+ * 功能：删除或替换数组元素
+ * 示例：{ "type": "splice", "path": "items", "start": 0, "deleteCount": 1, "items": "{{ newItem }}" }
+ */
+
+import type { RuntimeContext, Action } from '@/types.js'
+import { ActionError, ErrorCodes } from '@/errors.js'
+import { evaluate } from '@/expression/evaluate.js'
+import { invalidateCache } from '@/expression/cache.js'
+import { evaluateExpressionsRecursively } from './utils.js'
+
+/**
+ * 处理 splice 动作
+ */
+export async function handleSplice(
+  ctx: RuntimeContext,
+  action: Action
+): Promise<void> {
+  const { path, start, deleteCount = 0, items } = action
+  
+  if (!path || typeof path !== 'string') {
+    throw new ActionError(
+      action,
+      'splice action requires "path" parameter',
+      ErrorCodes.ACTION_MISSING_PARAM,
+      { metadata: { param: 'path' } }
+    )
+  }
+  
+  // 获取数组
+  const array = ctx._get(path)
+  if (!Array.isArray(array)) {
+    throw new ActionError(
+      action,
+      `Path "${path}" does not point to an array`,
+      ErrorCodes.ACTION_INVALID_PARAM,
+      { metadata: { param: 'path', path, actualType: typeof array } }
+    )
+  }
+  
+  // 求值 start（支持表达式）
+  let finalStart: number
+  if (typeof start === 'string' && start.startsWith('{{') && start.endsWith('}}')) {
+    const expr = start.slice(2, -2).trim()
+    finalStart = Number(evaluate(expr, ctx) as number)
+  } else {
+    finalStart = Number(start as number)
+  }
+
+  // 求值 deleteCount（支持表达式）
+  let finalDeleteCount: number
+  if (typeof deleteCount === 'string' && deleteCount.startsWith('{{') && deleteCount.endsWith('}}')) {
+    const expr = deleteCount.slice(2, -2).trim()
+    finalDeleteCount = Number(evaluate(expr, ctx) as number)
+  } else {
+    finalDeleteCount = Number(deleteCount as number)
+  }
+  
+  // 求值 items（支持递归表达式）
+  let finalItems: unknown[] = []
+  if (items != null) {
+    const evaluated = evaluateExpressionsRecursively(items, ctx)
+    if (Array.isArray(evaluated)) {
+      finalItems = evaluated
+    } else {
+      finalItems = [evaluated]
+    }
+  }
+  
+  // 执行 splice
+  array.splice(finalStart, finalDeleteCount, ...finalItems)
+  
+  // 使相关缓存失效
+  invalidateCache(path, ctx)
+  invalidateCache(`${path}.*`, ctx)
+}

package/src/vm/handlers/array/unshift.ts

@@ -0,0 +1,68 @@
+/**
+ * unshift 动作处理器
+ * 
+ * 功能：添加元素到数组开头
+ * 示例：{ "type": "unshift", "path": "items", "value": "{{ firstItem }}" }
+ * 示例：{ "type": "unshift", "path": "todos", "items": [{ text: "{{ newTodo }}", done: false }] }
+ */
+
+import type { RuntimeContext, Action } from '@/types.js'
+import { ActionError, ErrorCodes } from '@/errors.js'
+import { invalidateCache } from '@/expression/cache.js'
+import { evaluateExpressionsRecursively } from './utils.js'
+
+/**
+ * 处理 unshift 动作
+ */
+export async function handleUnshift(
+  ctx: RuntimeContext,
+  action: Action
+): Promise<void> {
+  const { path, value, items } = action
+  
+  if (!path || typeof path !== 'string') {
+    throw new ActionError(
+      action,
+      'unshift action requires "path" parameter',
+      ErrorCodes.ACTION_MISSING_PARAM,
+      { metadata: { param: 'path' } }
+    )
+  }
+  
+  // 获取数组
+  const array = ctx._get(path)
+  if (!Array.isArray(array)) {
+    throw new ActionError(
+      action,
+      `Path "${path}" does not point to an array`,
+      ErrorCodes.ACTION_INVALID_PARAM,
+      { metadata: { param: 'path', path, actualType: typeof array } }
+    )
+  }
+  
+  // 支持 items 作为 value 的别名
+  const inputValue = items !== undefined ? items : value
+  
+  if (inputValue === undefined) {
+    throw new ActionError(
+      action,
+      'unshift action requires "value" or "items" parameter',
+      ErrorCodes.ACTION_MISSING_PARAM,
+      { metadata: { param: 'value|items' } }
+    )
+  }
+  
+  // 递归求值表达式（支持对象/数组中的表达式）
+  const finalValue = evaluateExpressionsRecursively(inputValue, ctx)
+  
+  // 如果是数组，展开添加
+  if (Array.isArray(finalValue)) {
+    array.unshift(...finalValue)
+  } else {
+    array.unshift(finalValue)
+  }
+  
+  // 使相关缓存失效
+  invalidateCache(path, ctx)
+  invalidateCache(`${path}.*`, ctx)
+}