@variojs/core 0.0.2 → 0.1.1

package/dist/index.d.ts

@@ -1,18 +1,831 @@
+import { SchemaNode } from '@variojs/schema';
+import * as ESTree from '@babel/types';
+
 /**
- * @variojs/core - Vario Core Runtime
- *
- * 核心运行时模块，包含：
- * - RuntimeContext: 扁平化状态 + $ 前缀系统 API
- * - Expression System: 安全表达式求值
- * - Action VM: 动作虚拟机
- * - Path Utilities: 统一的路径解析工具
- */
-export { createRuntimeContext, createProxy, createExpressionSandbox, isSafePropertyAccess, createLoopContext, releaseLoopContext, parsePath, parsePathCached, clearPathCache, stringifyPath, getPathValue, setPathValue, matchPath, getParentPath, getLastSegment } from './runtime/index.js';
-export type { RuntimeContext, CreateContextOptions, OnStateChangeCallback } from './types.js';
-export type { PathSegment } from './runtime/path.js';
-export { parseExpression, validateAST, evaluateExpression, evaluate, extractExpression, extractDependencies, getCachedExpression, setCachedExpression, invalidateCache, clearCache, getCacheStats } from './expression/index.js';
-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';
-//# sourceMappingURL=index.d.ts.map
+ * Vario 错误处理体系
+ *
+ * 统一的错误基类和错误码系统
+ */
+
+/**
+ * 错误上下文信息
+ */
+interface ErrorContext {
+    /** Schema 路径（如 "events.click[0]"） */
+    schemaPath?: string;
+    /** 表达式字符串 */
+    expression?: string;
+    /** 动作对象 */
+    action?: Action;
+    /** 调用栈（简化版） */
+    stack?: string[];
+    /** 额外上下文信息 */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Vario 错误基类
+ *
+ * 所有 Vario 相关错误都应继承此类
+ */
+declare class VarioError extends Error {
+    /** 错误码 */
+    readonly code: string;
+    /** 错误上下文 */
+    readonly context: ErrorContext;
+    constructor(message: string, code: string, context?: ErrorContext);
+    /**
+     * 获取友好的错误消息
+     */
+    getFriendlyMessage(): string;
+    /**
+     * 转换为 JSON（用于序列化）
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * 动作执行错误
+ */
+declare class ActionError extends VarioError {
+    constructor(action: Action, message: string, code?: string, context?: Omit<ErrorContext, 'action'>);
+}
+/**
+ * 表达式求值错误
+ */
+declare class ExpressionError extends VarioError {
+    constructor(expression: string, message: string, code?: string, context?: Omit<ErrorContext, 'expression'>);
+}
+/**
+ * 服务调用错误
+ */
+declare class ServiceError extends VarioError {
+    readonly service: string;
+    readonly originalError?: Error;
+    constructor(service: string, message: string, originalError?: Error, context?: ErrorContext);
+}
+/**
+ * 批量执行错误
+ */
+declare class BatchError extends VarioError {
+    readonly failedActions: Array<{
+        action: Action;
+        error: Error;
+    }>;
+    constructor(failedActions: Array<{
+        action: Action;
+        error: Error;
+    }>, message: string, context?: ErrorContext);
+}
+/**
+ * 错误码定义
+ */
+declare const ErrorCodes: {
+    readonly ACTION_UNKNOWN_TYPE: "ACTION_UNKNOWN_TYPE";
+    readonly ACTION_EXECUTION_ERROR: "ACTION_EXECUTION_ERROR";
+    readonly ACTION_ABORTED: "ACTION_ABORTED";
+    readonly ACTION_TIMEOUT: "ACTION_TIMEOUT";
+    readonly ACTION_MAX_STEPS_EXCEEDED: "ACTION_MAX_STEPS_EXCEEDED";
+    readonly ACTION_MISSING_PARAM: "ACTION_MISSING_PARAM";
+    readonly ACTION_INVALID_PARAM: "ACTION_INVALID_PARAM";
+    readonly EXPRESSION_PARSE_ERROR: "EXPRESSION_PARSE_ERROR";
+    readonly EXPRESSION_VALIDATION_ERROR: "EXPRESSION_VALIDATION_ERROR";
+    readonly EXPRESSION_EVALUATION_ERROR: "EXPRESSION_EVALUATION_ERROR";
+    readonly EXPRESSION_TIMEOUT: "EXPRESSION_TIMEOUT";
+    readonly EXPRESSION_MAX_STEPS_EXCEEDED: "EXPRESSION_MAX_STEPS_EXCEEDED";
+    readonly EXPRESSION_UNSAFE_ACCESS: "EXPRESSION_UNSAFE_ACCESS";
+    readonly EXPRESSION_FUNCTION_NOT_WHITELISTED: "EXPRESSION_FUNCTION_NOT_WHITELISTED";
+    readonly SERVICE_NOT_FOUND: "SERVICE_NOT_FOUND";
+    readonly SERVICE_CALL_ERROR: "SERVICE_CALL_ERROR";
+    readonly BATCH_ERROR: "BATCH_ERROR";
+    readonly SCHEMA_VALIDATION_ERROR: "SCHEMA_VALIDATION_ERROR";
+    readonly SCHEMA_INVALID_ACTION: "SCHEMA_INVALID_ACTION";
+};
+type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
+
+/**
+ * Vario Core Types
+ *
+ * 复杂类型集中在此定义，便于推演类型关系、保持业务/运行时逻辑代码简洁。
+ * 核心：RuntimeContext、路径值推导(GetPathValue/SetPathValue)、上下文创建选项(CreateContextOptions)等。
+ */
+/**
+ * 方法处理器类型
+ * 所有注册到 $methods 的方法必须符合此签名
+ *
+ * 注意：动作处理器也通过 $methods 注册，但它们的参数是 Action
+ */
+type MethodHandler<TParams = unknown, TResult = unknown> = (ctx: RuntimeContext, params: TParams) => Promise<TResult> | TResult;
+/**
+ * 动作处理器类型（特殊的方法处理器）
+ */
+type ActionHandler = MethodHandler<Action, void>;
+/**
+ * 方法注册表类型
+ * 支持普通方法和指令处理器
+ */
+type MethodsRegistry = Record<string, MethodHandler>;
+/**
+ * 表达式求值选项
+ */
+interface ExpressionOptions {
+    /**
+     * 是否允许访问全局对象（默认 false）
+     */
+    allowGlobals?: boolean;
+    /**
+     * 最大求值步数
+     */
+    maxSteps?: number;
+    /**
+     * 求值超时（毫秒）
+     */
+    timeout?: number;
+    /**
+     * 最大嵌套深度（防止 DoS 攻击，默认 50）
+     */
+    maxNestingDepth?: number;
+}
+/**
+ * 运行时上下文接口
+ * 扁平化状态设计：直接属性访问，无 models. 前缀
+ *
+ * @template TState 状态类型，用于类型推导和约束
+ *
+ * 设计说明：
+ * - 使用接口 + 索引签名，既支持类型推导又支持动态属性
+ * - 状态属性通过 TState 泛型约束
+ * - 系统 API 使用具体类型定义，确保类型安全
+ */
+/**
+ * 运行时上下文类型
+ * 使用交叉类型结合接口，既支持状态类型推导又支持动态属性
+ */
+type RuntimeContext<TState extends Record<string, unknown> = Record<string, unknown>> = TState & {
+    $emit: (event: string, data?: unknown) => void;
+    $methods: MethodsRegistry;
+    $exprOptions?: ExpressionOptions;
+    /**
+     * 事件值（在事件处理中可用）
+     * - 对于 DOM 原生事件：Event 对象
+     * - 对于 Vue 组件 emit：emit 的参数值（如 string[]、number 等）
+     */
+    $event?: unknown;
+    $item?: TState[keyof TState];
+    $index?: number;
+    _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
+ * GetPathValue<{ list: { id: number }[] }, 'list.0.id'> // number
+ */
+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> : T[Key] extends readonly (infer E)[] ? Rest extends `${number}` ? E : Rest extends `${number}.${infer R}` ? GetPathValue<E, R> : unknown : unknown : unknown : TPath extends keyof T ? T[TPath] : unknown;
+/**
+ * 路径设置值类型推导工具
+ * 根据路径字符串推导可以设置的值类型
+ */
+type SetPathValue<T, TPath extends string> = GetPathValue<T, TPath>;
+/**
+ * 状态变更回调：path 与 value 类型联动，TPath 由 path 推导，value 为 GetPathValue<TState, TPath>
+ */
+type OnStateChangeCallback<TState extends Record<string, unknown>> = <TPath extends string>(path: TPath, value: GetPathValue<TState, TPath>, ctx: RuntimeContext<TState>) => void;
+/**
+ * RuntimeContext 创建选项
+ * @template TState 与 context 一致的状态类型，供 onStateChange 等回调获得完整类型推导
+ */
+interface CreateContextOptions<TState extends Record<string, unknown> = Record<string, unknown>> {
+    onEmit?: (event: string, data?: unknown) => void;
+    methods?: MethodsRegistry;
+    /** 在 _set 调用后触发，value 类型随 path 推导 */
+    onStateChange?: OnStateChangeCallback<TState>;
+    createObject?: () => Record<string, unknown>;
+    createArray?: () => unknown[];
+    exprOptions?: ExpressionOptions;
+}
+/**
+ * 动作接口
+ * 使用泛型约束，根据 type 类型推导参数结构
+ */
+interface Action {
+    type: string;
+    [key: string]: unknown;
+}
+/**
+ * 动作类型映射
+ * 根据 type 值推导对应的动作参数类型
+ */
+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>;
+        args?: unknown[];
+        resultTo?: string;
+        modifiers?: Record<string, boolean>;
+    };
+    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[];
+    };
+};
+/**
+ * 表达式缓存接口
+ * 结果类型使用 unknown，因为表达式求值结果类型无法静态推导
+ */
+interface ExpressionCache {
+    expr: string;
+    result: unknown;
+    dependencies: string[];
+    timestamp: number;
+}
+
+/**
+ * RuntimeContext 创建工厂
+ *
+ * 实现要点：扁平化状态存储、系统 API 保护、命名冲突检测、Proxy 保护。
+ * 复杂类型见 ../types.ts（CreateContextOptions、OnStateChangeCallback 等）。
+ */
+
+/**
+ * 创建运行时上下文（传入具体 initialState 时，TState 从实参自动推导）
+ */
+declare function createRuntimeContext<TState extends Record<string, unknown>>(initialState: TState, options?: CreateContextOptions<TState>): RuntimeContext<TState>;
+/**
+ * 创建运行时上下文（显式指定 TState 时可传空或部分初始状态，如 createRuntimeContext<MyState>({}, options)）
+ */
+declare function createRuntimeContext<TState extends Record<string, unknown>>(initialState: Partial<TState> & Record<string, unknown>, options?: CreateContextOptions<TState>): RuntimeContext<TState>;
+/**
+ * 创建运行时上下文（不传或传空且未指定 TState 时，退回 Record<string, unknown>）
+ */
+declare function createRuntimeContext(initialState?: Record<string, unknown>, options?: CreateContextOptions<Record<string, unknown>>): RuntimeContext<Record<string, unknown>>;
+
+/**
+ * Proxy 沙箱实现
+ *
+ * 功能：
+ * - 防止覆盖系统 API（$ 和 _ 前缀保护）
+ * - 拦截属性设置操作
+ */
+
+/**
+ * 创建受保护的 Proxy 上下文
+ * 禁止设置以 $ 或 _ 开头的属性
+ *
+ * @template T 上下文类型，必须是 RuntimeContext 的子类型
+ * @param ctx 运行时上下文对象
+ * @returns 受保护的 Proxy 包装的上下文
+ */
+declare function createProxy<T extends RuntimeContext>(ctx: T): T;
+
+/**
+ * 沙箱边界控制
+ *
+ * 功能：
+ * - 表达式层：严格沙箱，无法访问全局对象
+ * - 方法层：白名单控制，可访问全局对象
+ */
+
+/**
+ * 创建表达式沙箱上下文
+ * 移除全局对象访问能力
+ */
+declare function createExpressionSandbox(ctx: RuntimeContext): RuntimeContext;
+/**
+ * 检查属性访问是否安全（用于表达式求值）
+ */
+declare function isSafePropertyAccess(prop: string, ctx: RuntimeContext, options?: {
+    allowGlobals?: boolean;
+}): boolean;
+
+/**
+ * 循环上下文对象池
+ *
+ * 功能：
+ * - 复用循环上下文对象，减少内存分配
+ * - 提升循环性能
+ * - 自动清理和重置
+ */
+
+/**
+ * 创建循环上下文（使用对象池）
+ *
+ * @param parentCtx 父上下文
+ * @param item 循环项
+ * @param index 循环索引
+ * @returns 循环上下文
+ */
+declare function createLoopContext(parentCtx: RuntimeContext, item: unknown, index: number): RuntimeContext;
+/**
+ * 释放循环上下文（回收到对象池）
+ *
+ * @param loopCtx 循环上下文
+ */
+declare function releaseLoopContext(loopCtx: Partial<RuntimeContext>): void;
+
+/**
+ * 路径解析工具模块
+ *
+ * 统一的路径解析逻辑，供 vario-core 和框架集成层使用
+ *
+ * 设计原则：
+ * - 单一职责：只处理路径解析，不涉及响应式
+ * - 可组合：提供原子操作，框架集成层可自由组合
+ * - 类型安全：尽可能提供类型推导
+ */
+/**
+ * 路径段类型
+ */
+type PathSegment = string | number;
+/**
+ * 解析路径字符串为段数组
+ *
+ * 支持两种语法：
+ * - 点语法：`user.name` → ['user', 'name']
+ * - 括号语法：`users[0].name` → ['users', 0, 'name']
+ * - 混合语法：`data.users[0].profile.tags[1]` → ['data', 'users', 0, 'profile', 'tags', 1]
+ * - 空括号：`users[].name` → ['users', -1, 'name']（-1 表示动态索引，由循环上下文填充）
+ *
+ * @param path 路径字符串
+ * @returns 路径段数组
+ *
+ * @example
+ * parsePath('user.name') // ['user', 'name']
+ * parsePath('items.0.text') // ['items', 0, 'text']
+ * parsePath('users[0].name') // ['users', 0, 'name']
+ * parsePath('users[].name') // ['users', -1, 'name']
+ */
+declare function parsePath(path: string): PathSegment[];
+/**
+ * 解析路径（带缓存）
+ *
+ * @param path 点分隔的路径字符串
+ * @returns 路径段数组
+ */
+declare function parsePathCached(path: string): PathSegment[];
+/**
+ * 清理路径缓存
+ */
+declare function clearPathCache(): void;
+/**
+ * 将路径段数组转换为路径字符串
+ *
+ * @param segments 路径段数组
+ * @returns 点分隔的路径字符串
+ */
+declare function stringifyPath(segments: PathSegment[]): string;
+/**
+ * 获取嵌套路径的值
+ *
+ * @param obj 目标对象
+ * @param path 路径字符串或路径段数组
+ * @returns 路径对应的值，不存在返回 undefined
+ */
+declare function getPathValue(obj: Record<string, unknown>, path: string | PathSegment[]): unknown;
+/**
+ * 设置嵌套路径的值
+ *
+ * @param obj 目标对象
+ * @param path 路径字符串或路径段数组
+ * @param value 要设置的值
+ * @param options 配置选项
+ * @returns 是否设置成功
+ */
+declare function setPathValue(obj: Record<string, unknown>, path: string | PathSegment[], value: unknown, options?: {
+    /**
+     * 自动创建中间路径
+     * @default true
+     */
+    createIntermediate?: boolean;
+    /**
+     * 创建对象的工厂函数
+     * 用于框架集成层创建响应式对象
+     */
+    createObject?: () => Record<string, unknown>;
+    /**
+     * 创建数组的工厂函数
+     * 用于框架集成层创建响应式数组
+     */
+    createArray?: () => unknown[];
+}): boolean;
+/**
+ * 检查路径是否匹配（支持通配符）
+ *
+ * @param pattern 模式路径（支持 * 通配符）
+ * @param path 目标路径
+ * @returns 是否匹配
+ *
+ * @example
+ * matchPath('items.*', 'items.0') // true
+ * matchPath('items.*.name', 'items.0.name') // true
+ * matchPath('user.name', 'user.name') // true
+ * matchPath('user.name', 'user.age') // false
+ */
+declare function matchPath(pattern: string, path: string): boolean;
+/**
+ * 提取路径的父路径
+ *
+ * @param path 路径字符串
+ * @returns 父路径，顶层路径返回空字符串
+ */
+declare function getParentPath(path: string): string;
+/**
+ * 获取路径的最后一段
+ *
+ * @param path 路径字符串
+ * @returns 最后一段
+ */
+declare function getLastSegment(path: string): PathSegment | undefined;
+
+type TraversalCallback = (node: SchemaNode, path: string, depth: number, parent: SchemaNode | null) => boolean | void;
+/**
+ * 通用 Schema 遍历工具 (UI Component Tree 风格)
+ * 采用深度优先遍历 (DFS)
+ *
+ * @param root 根节点
+ * @param callback 回调函数
+ * @param separator 路径分隔符，默认为 '.'
+ */
+declare function traverseSchema(root: SchemaNode, callback: TraversalCallback, separator?: string): void;
+
+/**
+ * 表达式解析器
+ *
+ * 使用 @babel/parser 解析 JavaScript 表达式为 AST
+ * 移除 models. 前缀支持
+ */
+
+/**
+ * 解析表达式为 AST
+ *
+ * @param expr 表达式字符串（如 "user.name + 1"）
+ * @returns ESTree.Node AST 节点
+ */
+declare function parseExpression(expr: string): ESTree.Node;
+
+/**
+ * AST 白名单验证器
+ *
+ * 功能：
+ * - 深度遍历 AST，检查每个节点
+ * - 只允许安全的语法节点
+ * - 禁止危险的语法（赋值、函数、this 等）
+ * - 检查函数调用中的函数名是否在白名单中
+ */
+
+/**
+ * 验证 AST 是否通过白名单检查
+ *
+ * @param ast AST 节点
+ * @param options 验证选项
+ * @param options.allowGlobals 是否允许全局函数调用（跳过白名单检查）
+ * @param options.maxNestingDepth 最大嵌套深度（默认 50）
+ * @throws ExpressionError 如果发现禁止的节点
+ */
+declare function validateAST(ast: ESTree.Node, options?: {
+    allowGlobals?: boolean;
+    maxNestingDepth?: number;
+}): void;
+
+/**
+ * 表达式求值器
+ *
+ * 功能：
+ * - 安全求值 AST
+ * - 支持白名单函数调用
+ * - 执行步数/时间限制
+ */
+
+/**
+ * 安全求值 AST
+ *
+ * @param ast AST 节点
+ * @param ctx 运行时上下文
+ * @param options 求值选项
+ * @returns 求值结果（类型无法静态推导）
+ *
+ * 注意：表达式求值结果类型无法在编译时确定，返回 unknown
+ */
+declare function evaluateExpression(ast: ESTree.Node, ctx: RuntimeContext, options?: ExpressionOptions): unknown;
+
+/**
+ * 表达式求值入口函数
+ *
+ * 整合解析、验证、缓存、求值流程
+ */
+
+/**
+ * 求值表达式（完整流程）
+ *
+ * @param expr 表达式字符串
+ * @param ctx 运行时上下文
+ * @returns 求值结果（类型无法静态推导，返回 unknown）
+ *
+ * 注意：表达式求值结果类型无法在编译时确定，因为：
+ * 1. 表达式是运行时字符串
+ * 2. 状态类型是动态的
+ * 3. 表达式可能返回任意类型
+ *
+ * 如果需要类型安全，应在使用结果时进行类型守卫或类型断言
+ */
+declare function evaluate(expr: string, ctx: RuntimeContext, options?: ExpressionOptions): unknown;
+
+/**
+ * 依赖提取算法
+ *
+ * 功能：
+ * - 从 AST 中提取状态依赖
+ * - 支持通配符依赖（items.*）
+ * - 保守策略：标记整个对象
+ */
+
+/**
+ * 从 AST 中提取依赖的状态路径
+ *
+ * @param ast AST 节点
+ * @returns 依赖路径数组（支持通配符）
+ */
+declare function extractDependencies(ast: ESTree.Node): string[];
+
+/**
+ * 表达式缓存系统
+ *
+ * 功能：
+ * - 每个 RuntimeContext 独立缓存（WeakMap 关联）
+ * - LRU 淘汰策略
+ * - 通配符依赖匹配
+ * - 缓存失效机制
+ *
+ * 设计原则：
+ * - 惰性求值：只在需要时计算
+ * - 依赖追踪：精确的缓存失效
+ * - 内存友好：WeakMap + LRU 淘汰
+ */
+
+/**
+ * 获取缓存的表达式结果
+ *
+ * @param expr 表达式字符串
+ * @param ctx 运行时上下文
+ * @returns 缓存的结果，无缓存或已失效返回 null
+ */
+declare function getCachedExpression(expr: string, ctx: RuntimeContext): unknown | null;
+/**
+ * 设置表达式缓存
+ *
+ * @param expr 表达式字符串
+ * @param result 求值结果
+ * @param dependencies 依赖的状态路径
+ * @param ctx 运行时上下文
+ */
+declare function setCachedExpression(expr: string, result: unknown, dependencies: string[], ctx: RuntimeContext): void;
+/**
+ * 使缓存失效
+ *
+ * 当状态变化时调用，精确删除依赖该状态的缓存
+ *
+ * @param changedPath 变化的状态路径
+ * @param ctx 运行时上下文
+ */
+declare function invalidateCache(changedPath: string, ctx: RuntimeContext): void;
+/**
+ * 清除指定上下文的所有缓存
+ */
+declare function clearCache(ctx: RuntimeContext): void;
+/**
+ * 获取缓存统计信息（调试用）
+ */
+declare function getCacheStats(ctx: RuntimeContext): {
+    size: number;
+    expressions: string[];
+};
+
+/**
+ * 表达式工具函数
+ *
+ * 提供表达式解析、格式化的通用工具
+ * 支持 {{ }} 格式的表达式提取和规范化
+ */
+/**
+ * 提取表达式字符串
+ * 支持 {{ expression }} 格式，自动去掉包装
+ *
+ * @param expr 表达式字符串，可能是 "{{ showContent }}" 或 "showContent"
+ * @returns 去掉 {{ }} 包装后的表达式字符串
+ *
+ * @example
+ * ```typescript
+ * extractExpression("{{ showContent }}") // => "showContent"
+ * extractExpression("showContent") // => "showContent"
+ * extractExpression("{{ userRole === 'admin' }}") // => "userRole === 'admin'"
+ * ```
+ */
+declare function extractExpression(expr: string): string;
+
+/**
+ * Action VM 执行器
+ *
+ * 功能：
+ * - 执行动作序列
+ * - 通过 $methods 查找动作处理器
+ * - 错误处理和堆栈跟踪
+ * - 超时保护（防止无限循环）
+ *
+ * 参考架构图：vario-core/vm - Action VM
+ */
+
+/**
+ * 执行动作序列的选项
+ */
+interface ExecuteOptions {
+    /**
+     * 超时时间（毫秒），默认 5000ms
+     */
+    timeout?: number;
+    /**
+     * 最大执行步数，默认 10000
+     * 每执行一个动作计为一步
+     */
+    maxSteps?: number;
+}
+/**
+ * 执行动作序列
+ *
+ * @param actions 动作数组
+ * @param ctx 运行时上下文
+ * @param options 执行选项
+ */
+declare function execute(actions: Action[], ctx: RuntimeContext, options?: ExecuteOptions): Promise<void>;
+
+/**
+ * 内置动作处理器
+ *
+ * 所有内置动作统一注册到 ctx.$methods
+ */
+
+/**
+ * 注册所有内置动作到 $methods
+ *
+ * 注意：此函数通过向现有 $methods 对象添加属性来注册方法，
+ * 而不是整体覆盖 $methods，以确保在 Proxy 保护下也能正常工作。
+ */
+declare function registerBuiltinMethods(ctx: RuntimeContext): void;
+
+/**
+ * Schema 分析器 - 框架无关的纯函数实现
+ *
+ * 提供 Schema 统计和索引构建能力，不依赖任何前端框架
+ */
+
+/**
+ * Schema 统计信息
+ */
+interface SchemaStats {
+    /** 节点总数 */
+    nodeCount: number;
+    /** 最大深度 */
+    maxDepth: number;
+}
+/**
+ * Schema 索引映射
+ */
+interface SchemaIndex {
+    /** ID -> 路径的映射 */
+    idMap: Map<string, string>;
+    /** 路径 -> 节点的映射（可选，用于快速访问） */
+    pathMap?: Map<string, SchemaNode>;
+}
+/**
+ * 分析结果
+ */
+interface AnalysisResult {
+    stats: SchemaStats;
+    index: SchemaIndex;
+}
+/**
+ * 分析 Schema 结构
+ *
+ * 遍历整个 Schema 树，收集统计信息和构建索引
+ *
+ * @param schema 要分析的 Schema 根节点
+ * @param options 分析选项
+ * @returns 分析结果
+ */
+declare function analyzeSchema(schema: SchemaNode, options?: {
+    /** 是否构建路径映射（会增加内存开销） */
+    buildPathMap?: boolean;
+    /** 自定义回调，在遍历每个节点时调用 */
+    onNode?: (node: SchemaNode, path: string, depth: number) => void;
+}): AnalysisResult;
+/**
+ * 在 Schema 中查找节点
+ *
+ * @param schema Schema 根节点
+ * @param predicate 判断条件
+ * @returns 匹配的节点路径数组
+ */
+declare function findNodes(schema: SchemaNode, predicate: (node: SchemaNode) => boolean): Array<{
+    node: SchemaNode;
+    path: string;
+}>;
+/**
+ * 在 Schema 中查找第一个匹配的节点
+ *
+ * @param schema Schema 根节点
+ * @param predicate 判断条件
+ * @returns 匹配的节点和路径，如果未找到返回 null
+ */
+declare function findNode(schema: SchemaNode, predicate: (node: SchemaNode) => boolean): {
+    node: SchemaNode;
+    path: string;
+} | null;
+/**
+ * 通过 ID 查找节点路径
+ *
+ * @param schema Schema 根节点
+ * @param id 节点 ID
+ * @returns 节点路径，如果未找到返回 null
+ */
+declare function findPathById(schema: SchemaNode, id: string): string | null;
+
+/**
+ * Schema 查询引擎 - 框架无关的查询 API
+ */
+
+/**
+ * 查询引擎配置
+ */
+interface QueryEngineOptions {
+    /** Schema 根节点 */
+    schema: SchemaNode;
+    /** 索引（可选，用于加速 ID 查询） */
+    index?: SchemaIndex;
+}
+/**
+ * 节点查询结果
+ */
+interface NodeResult {
+    /** 节点对象 */
+    node: SchemaNode;
+    /** 节点路径 */
+    path: string;
+}
+/**
+ * 创建查询引擎
+ *
+ * 提供高性能的 Schema 查询能力
+ */
+declare function createQueryEngine(options: QueryEngineOptions): {
+    findById: (id: string) => NodeResult | null;
+    getParent: (path: string) => NodeResult | null;
+};
+
+export { type Action, ActionError, type ActionHandler, type ActionMap, type AnalysisResult, BatchError, type CreateContextOptions, type ErrorCode, ErrorCodes, type ErrorContext, type ExecuteOptions, type ExpressionCache, ExpressionError, type ExpressionOptions, type MethodsRegistry, type NodeResult, type OnStateChangeCallback, type PathSegment, type QueryEngineOptions, type RuntimeContext, type SchemaIndex, type SchemaStats, ServiceError, type TraversalCallback, VarioError, analyzeSchema, clearCache, clearPathCache, createExpressionSandbox, createLoopContext, createProxy, createQueryEngine, createRuntimeContext, evaluate, evaluateExpression, execute, extractDependencies, extractExpression, findNode, findNodes, findPathById, getCacheStats, getCachedExpression, getLastSegment, getParentPath, getPathValue, invalidateCache, isSafePropertyAccess, matchPath, parseExpression, parsePath, parsePathCached, registerBuiltinMethods, releaseLoopContext, setCachedExpression, setPathValue, stringifyPath, traverseSchema, validateAST };