@variojs/core 0.0.1 → 0.0.2

package/README.md

@@ -1,16 +1,13 @@
-# @variojs/core
+# ⚡ @variojs/core
 
-Vario Core Runtime - 指令虚拟机、表达式系统、运行时上下文
+Vario 核心运行时 - 指令虚拟机、表达式系统、运行时上下文
 
-## 简介
+## 特点
 
-`@variojs/core` 是 Vario 的核心运行时模块，提供了框架无关的基础能力：
-
-- **RuntimeContext**: 扁平化状态管理 + `$` 前缀系统 API
-- **Expression System**: 安全表达式解析、编译和求值
-- **Action VM**: 指令虚拟机，执行各种操作指令
-- **安全沙箱**: 多层防护机制，防止恶意代码执行
-- **性能优化**: 表达式缓存、对象池、路径记忆化
+- 🚀 **高性能**：表达式缓存、对象池、路径记忆化
+- 🔒 **安全沙箱**：多层防护，白名单机制，防止恶意代码
+- 📦 **框架无关**：可在任何 JavaScript 环境中使用
+- 🎯 **扁平化状态**：`$` 前缀系统 API，简洁直观
 
 ## 安装
 
@@ -20,15 +17,12 @@ npm install @variojs/core
 pnpm add @variojs/core
 ```
 
-## 核心概念
-
-### RuntimeContext 运行时上下文
-
-运行时上下文是 Vario 的核心，提供了扁平化的状态管理和系统 API：
+## 快速开始
 
 ```typescript
-import { createRuntimeContext } from '@variojs/core'
+import { createRuntimeContext, createVMExecutor } from '@variojs/core'
 
+// 创建运行时上下文
 const ctx = createRuntimeContext({
   state: {
     count: 0,
@@ -46,224 +40,45 @@ ctx.count  // 0
 ctx.user.name  // 'John'
 
 // 使用系统 API
-ctx._get('count')  // 0
-ctx._set('count', 10)  // 设置值
-ctx.$emit('countChanged', 10)  // 发射事件
-```
-
-### Expression System 表达式系统
-
-安全、强大的表达式求值引擎，支持复杂的条件判断、数据访问和计算：
-
-```typescript
-import { createExpressionSandbox, compileExpression } from '@variojs/core'
-
-const sandbox = createExpressionSandbox(ctx)
-
-// 编译表达式
-const expr = compileExpression('count > 10 && user.age >= 18')
-
-// 求值
-const result = expr.evaluate(sandbox)  // true/false
-```
-
-**支持的语法**：
-- 变量访问：`count`, `user.name`
-- 数组访问：`items[0]`, `todos[index]`
-- 可选链：`user?.profile?.email`
-- 二元运算：`count + 1`, `price * quantity`
-- 比较运算：`count > 10`, `role === "admin"`
-- 逻辑运算：`showContent && isActive`
-- 三元表达式：`count > 10 ? "high" : "low"`
-- 函数调用（白名单）：`Array.isArray(items)`, `Math.max(a, b)`
-
-### Action VM 指令虚拟机
-
-执行各种操作指令，如 `set`、`call`、`if`、`loop` 等：
-
-```typescript
-import { createVMExecutor } from '@variojs/core'
+ctx._set('count', 10)
+ctx.$emit('countChanged', 10)
 
+// 执行指令
 const executor = createVMExecutor(ctx)
-
-// 执行 set 指令
 await executor.execute({
   type: 'set',
   path: 'count',
   value: 10
 })
-
-// 执行 call 指令
-await executor.execute({
-  type: 'call',
-  method: 'increment'
-})
-
-// 执行 if 指令
-await executor.execute({
-  type: 'if',
-  cond: 'count > 10',
-  then: {
-    type: 'set',
-    path: 'status',
-    value: 'high'
-  }
-})
 ```
 
-## API 参考
-
-### createRuntimeContext
-
-创建运行时上下文。
-
-```typescript
-function createRuntimeContext<TState extends Record<string, unknown>>(
-  options: CreateContextOptions<TState>
-): RuntimeContext<TState>
-```
-
-**选项**：
-
-```typescript
-interface CreateContextOptions<TState> {
-  /** 初始状态 */
-  state?: TState
-  /** 方法注册表 */
-  methods?: Record<string, MethodHandler>
-  /** 表达式选项 */
-  exprOptions?: ExpressionOptions
-  /** 事件发射器 */
-  onEmit?: (event: string, data?: unknown) => void
-  /** 状态变化回调 */
-  onStateChange?: (path: string, value: unknown) => void
-}
-```
-
-### Expression System
-
-```typescript
-// 创建表达式沙箱
-function createExpressionSandbox(ctx: RuntimeContext): ExpressionSandbox
-
-// 编译表达式
-function compileExpression(expr: string): CompiledExpression
-
-// 解析表达式
-function parseExpression(expr: string): ExpressionAST
-
-// 求值表达式
-function evaluateExpression(expr: string, ctx: RuntimeContext): unknown
-```
+## 表达式系统
 
-### Action VM
+安全、强大的表达式求值引擎：
 
 ```typescript
-// 创建 VM 执行器
-function createVMExecutor(ctx: RuntimeContext): VMExecutor
+import { compileExpression, createExpressionSandbox } from '@variojs/core'
 
-// 执行动作
-function executeAction(action: Action, ctx: RuntimeContext): Promise<void>
-```
-
-### Path Utilities
-
-路径解析和操作工具：
-
-```typescript
-// 解析路径
-function parsePath(path: string): PathSegment[]
-
-// 获取路径值
-function getPathValue(obj: Record<string, unknown>, path: string): unknown
-
-// 设置路径值
-function setPathValue(
-  obj: Record<string, unknown>,
-  path: string,
-  value: unknown,
-  options?: { createObject?: () => object, createArray?: () => unknown[] }
-): void
-
-// 路径匹配
-function matchPath(pattern: string, path: string): boolean
-```
-
-## 安全特性
-
-### 表达式白名单
-
-表达式系统使用白名单机制，只允许安全的操作：
-
-- ✅ 允许：属性访问、数组访问、数学运算、比较运算
-- ✅ 允许：白名单函数（`Array.isArray`, `Math.max` 等）
-- ❌ 禁止：`eval`, `Function`, `global`, `window` 等危险操作
-- ❌ 禁止：直接访问 Node.js API（`require`, `process` 等）
-
-### 沙箱机制
-
-表达式在隔离的沙箱中执行，无法访问外部作用域：
-
-```typescript
 const sandbox = createExpressionSandbox(ctx)
-
-// 只能访问 ctx 中定义的状态和方法
-// 无法访问全局变量、Node.js API 等
-```
-
-## 性能优化
-
-### 表达式缓存
-
-编译后的表达式会被缓存，避免重复编译：
-
-```typescript
-// 第一次编译
-const expr1 = compileExpression('count > 10')  // 编译
-
-// 第二次使用相同表达式
-const expr2 = compileExpression('count > 10')  // 从缓存获取
-```
-
-### 路径缓存
-
-路径解析结果会被缓存：
-
-```typescript
-parsePathCached('user.profile.name')  // 第一次解析
-parsePathCached('user.profile.name')  // 从缓存获取
-```
-
-### 对象池
-
-循环上下文使用对象池复用，减少内存分配：
-
-```typescript
-import { createLoopContext, releaseLoopContext } from '@variojs/core'
-
-// 创建循环上下文（从池中获取）
-const loopCtx = createLoopContext(ctx, { item, index })
-
-// 使用后释放（归还到池中）
-releaseLoopContext(loopCtx)
+const expr = compileExpression('count > 10 && user.age >= 18')
+const result = expr.evaluate(sandbox)  // true/false
 ```
 
-## 类型支持
-
-完整的 TypeScript 类型定义：
-
-```typescript
-import type {
-  RuntimeContext,
-  Action,
-  ExpressionOptions,
-  MethodHandler
-} from '@variojs/core'
-```
+**支持的语法**：
+- 变量访问：`count`, `user.name`
+- 数组访问：`items[0]`
+- 可选链：`user?.profile?.email`
+- 运算：`count + 1`, `price * quantity`
+- 逻辑：`showContent && isActive`
+- 三元：`count > 10 ? "high" : "low"`
+- 白名单函数：`Array.isArray`, `Math.max`
 
-## 示例
+## 优势
 
-查看主项目的 `play/src/examples/` 目录下的完整示例。
+- ✅ **类型安全**：完整的 TypeScript 类型定义
+- ✅ **性能优化**：表达式缓存、路径缓存、对象池复用
+- ✅ **安全可靠**：白名单机制，沙箱隔离，防止代码注入
+- ✅ **易于扩展**：支持自定义指令和方法
 
 ## 许可证
 

package/dist/errors.js

@@ -1,132 +1,4 @@
-/**
- * Vario 错误处理体系
- *
- * 统一的错误基类和错误码系统
- */
-/**
- * Vario 错误基类
- *
- * 所有 Vario 相关错误都应继承此类
- */
-export class VarioError extends Error {
-    /** 错误码 */
-    code;
-    /** 错误上下文 */
-    context;
-    constructor(message, code, context = {}) {
-        super(message);
-        this.name = 'VarioError';
-        this.code = code;
-        this.context = context;
-        // 确保 stack 属性存在
-        if (Error.captureStackTrace) {
-            Error.captureStackTrace(this, VarioError);
-        }
-    }
-    /**
-     * 获取友好的错误消息
-     */
-    getFriendlyMessage() {
-        const parts = [this.message];
-        if (this.context.schemaPath) {
-            parts.push(`\n  Schema 路径: ${this.context.schemaPath}`);
-        }
-        if (this.context.expression) {
-            parts.push(`\n  表达式: ${this.context.expression}`);
-        }
-        if (this.context.action) {
-            parts.push(`\n  动作类型: ${this.context.action.type}`);
-        }
-        return parts.join('');
-    }
-    /**
-     * 转换为 JSON（用于序列化）
-     */
-    toJSON() {
-        return {
-            name: this.name,
-            message: this.message,
-            code: this.code,
-            context: this.context,
-            stack: this.stack
-        };
-    }
-}
-/**
- * 动作执行错误
- */
-export class ActionError extends VarioError {
-    constructor(action, message, code = 'ACTION_ERROR', context = {}) {
-        super(message, code, {
-            ...context,
-            action
-        });
-        this.name = 'ActionError';
-    }
-}
-/**
- * 表达式求值错误
- */
-export class ExpressionError extends VarioError {
-    constructor(expression, message, code = 'EXPRESSION_ERROR', context = {}) {
-        super(message, code, {
-            ...context,
-            expression
-        });
-        this.name = 'ExpressionError';
-    }
-}
-/**
- * 服务调用错误
- */
-export class ServiceError extends VarioError {
-    service;
-    originalError;
-    constructor(service, message, originalError, context = {}) {
-        super(message, 'SERVICE_ERROR', context);
-        this.name = 'ServiceError';
-        this.service = service;
-        this.originalError = originalError;
-    }
-}
-/**
- * 批量执行错误
- */
-export class BatchError extends VarioError {
-    failedActions;
-    constructor(failedActions, message, context = {}) {
-        super(message, 'BATCH_ERROR', context);
-        this.name = 'BatchError';
-        this.failedActions = failedActions;
-    }
-}
-/**
- * 错误码定义
- */
-export const ErrorCodes = {
-    // 动作相关错误
-    ACTION_UNKNOWN_TYPE: 'ACTION_UNKNOWN_TYPE',
-    ACTION_EXECUTION_ERROR: 'ACTION_EXECUTION_ERROR',
-    ACTION_ABORTED: 'ACTION_ABORTED',
-    ACTION_TIMEOUT: 'ACTION_TIMEOUT',
-    ACTION_MAX_STEPS_EXCEEDED: 'ACTION_MAX_STEPS_EXCEEDED',
-    ACTION_MISSING_PARAM: 'ACTION_MISSING_PARAM',
-    ACTION_INVALID_PARAM: 'ACTION_INVALID_PARAM',
-    // 表达式相关错误
-    EXPRESSION_PARSE_ERROR: 'EXPRESSION_PARSE_ERROR',
-    EXPRESSION_VALIDATION_ERROR: 'EXPRESSION_VALIDATION_ERROR',
-    EXPRESSION_EVALUATION_ERROR: 'EXPRESSION_EVALUATION_ERROR',
-    EXPRESSION_TIMEOUT: 'EXPRESSION_TIMEOUT',
-    EXPRESSION_MAX_STEPS_EXCEEDED: 'EXPRESSION_MAX_STEPS_EXCEEDED',
-    EXPRESSION_UNSAFE_ACCESS: 'EXPRESSION_UNSAFE_ACCESS',
-    EXPRESSION_FUNCTION_NOT_WHITELISTED: 'EXPRESSION_FUNCTION_NOT_WHITELISTED',
-    // 服务相关错误
-    SERVICE_NOT_FOUND: 'SERVICE_NOT_FOUND',
-    SERVICE_CALL_ERROR: 'SERVICE_CALL_ERROR',
-    // 批量执行错误
-    BATCH_ERROR: 'BATCH_ERROR',
-    // Schema 相关错误
-    SCHEMA_VALIDATION_ERROR: 'SCHEMA_VALIDATION_ERROR',
-    SCHEMA_INVALID_ACTION: 'SCHEMA_INVALID_ACTION',
-};
-//# sourceMappingURL=errors.js.map
+class R extends Error{code;context;constructor(E,t,r={}){super(E),this.name="VarioError",this.code=t,this.context=r,Error.captureStackTrace&&Error.captureStackTrace(this,R)}getFriendlyMessage(){const E=[this.message];return this.context.schemaPath&&E.push(`
+  Schema \u8DEF\u5F84: ${this.context.schemaPath}`),this.context.expression&&E.push(`
+  \u8868\u8FBE\u5F0F: ${this.context.expression}`),this.context.action&&E.push(`
+  \u52A8\u4F5C\u7C7B\u578B: ${this.context.action.type}`),E.join("")}toJSON(){return{name:this.name,message:this.message,code:this.code,context:this.context,stack:this.stack}}}class _ extends R{constructor(E,t,r="ACTION_ERROR",e={}){super(t,r,{...e,action:E}),this.name="ActionError"}}class O extends R{constructor(E,t,r="EXPRESSION_ERROR",e={}){super(t,r,{...e,expression:E}),this.name="ExpressionError"}}class I extends R{service;originalError;constructor(E,t,r,e={}){super(t,"SERVICE_ERROR",e),this.name="ServiceError",this.service=E,this.originalError=r}}class S extends R{failedActions;constructor(E,t,r={}){super(t,"BATCH_ERROR",r),this.name="BatchError",this.failedActions=E}}const A={ACTION_UNKNOWN_TYPE:"ACTION_UNKNOWN_TYPE",ACTION_EXECUTION_ERROR:"ACTION_EXECUTION_ERROR",ACTION_ABORTED:"ACTION_ABORTED",ACTION_TIMEOUT:"ACTION_TIMEOUT",ACTION_MAX_STEPS_EXCEEDED:"ACTION_MAX_STEPS_EXCEEDED",ACTION_MISSING_PARAM:"ACTION_MISSING_PARAM",ACTION_INVALID_PARAM:"ACTION_INVALID_PARAM",EXPRESSION_PARSE_ERROR:"EXPRESSION_PARSE_ERROR",EXPRESSION_VALIDATION_ERROR:"EXPRESSION_VALIDATION_ERROR",EXPRESSION_EVALUATION_ERROR:"EXPRESSION_EVALUATION_ERROR",EXPRESSION_TIMEOUT:"EXPRESSION_TIMEOUT",EXPRESSION_MAX_STEPS_EXCEEDED:"EXPRESSION_MAX_STEPS_EXCEEDED",EXPRESSION_UNSAFE_ACCESS:"EXPRESSION_UNSAFE_ACCESS",EXPRESSION_FUNCTION_NOT_WHITELISTED:"EXPRESSION_FUNCTION_NOT_WHITELISTED",SERVICE_NOT_FOUND:"SERVICE_NOT_FOUND",SERVICE_CALL_ERROR:"SERVICE_CALL_ERROR",BATCH_ERROR:"BATCH_ERROR",SCHEMA_VALIDATION_ERROR:"SCHEMA_VALIDATION_ERROR",SCHEMA_INVALID_ACTION:"SCHEMA_INVALID_ACTION"};export{_ as ActionError,S as BatchError,A as ErrorCodes,O as ExpressionError,I as ServiceError,R as VarioError};

package/dist/expression/cache.js

@@ -1,158 +1 @@
-/**
- * 表达式缓存系统
- *
- * 功能：
- * - 每个 RuntimeContext 独立缓存（WeakMap 关联）
- * - LRU 淘汰策略
- * - 通配符依赖匹配
- * - 缓存失效机制
- *
- * 设计原则：
- * - 惰性求值：只在需要时计算
- * - 依赖追踪：精确的缓存失效
- * - 内存友好：WeakMap + LRU 淘汰
- */
-import { matchPath } from '../runtime/path.js';
-/**
- * 每个上下文独立缓存
- * 使用 RuntimeContext 作为键（WeakMap 自动回收）
- */
-const cacheMap = new WeakMap();
-/**
- * 缓存配置
- */
-const CACHE_CONFIG = {
-    /** 最大缓存条目数 */
-    maxSize: 100,
-    /** 缓存有效期（毫秒），0 表示不过期 */
-    ttl: 0
-};
-/**
- * 获取上下文的缓存 Map
- */
-function getCache(ctx) {
-    let cache = cacheMap.get(ctx);
-    if (!cache) {
-        cache = new Map();
-        cacheMap.set(ctx, cache);
-    }
-    return cache;
-}
-/**
- * 检查缓存条目是否有效
- */
-function isCacheValid(entry, ctx) {
-    // TTL 检查
-    if (CACHE_CONFIG.ttl > 0 && Date.now() - entry.timestamp > CACHE_CONFIG.ttl) {
-        return false;
-    }
-    // 依赖检查：所有依赖的值必须存在
-    return entry.dependencies.every(dep => {
-        if (dep.includes('*')) {
-            // 通配符依赖：检查父路径是否存在
-            const parentPath = dep.split('.*')[0];
-            return ctx._get(parentPath) != null;
-        }
-        // 具体路径：检查值是否存在
-        return ctx._get(dep) !== undefined;
-    });
-}
-/**
- * LRU 淘汰：删除最旧的缓存条目
- */
-function evictOldest(cache) {
-    let oldestKey = null;
-    let oldestTime = Infinity;
-    for (const [key, entry] of cache.entries()) {
-        if (entry.timestamp < oldestTime) {
-            oldestTime = entry.timestamp;
-            oldestKey = key;
-        }
-    }
-    if (oldestKey) {
-        cache.delete(oldestKey);
-    }
-}
-/**
- * 获取缓存的表达式结果
- *
- * @param expr 表达式字符串
- * @param ctx 运行时上下文
- * @returns 缓存的结果，无缓存或已失效返回 null
- */
-export function getCachedExpression(expr, ctx) {
-    const cache = getCache(ctx);
-    const entry = cache.get(expr);
-    if (!entry) {
-        return null;
-    }
-    if (!isCacheValid(entry, ctx)) {
-        cache.delete(expr);
-        return null;
-    }
-    // 更新时间戳（LRU）
-    entry.timestamp = Date.now();
-    return entry.result;
-}
-/**
- * 设置表达式缓存
- *
- * @param expr 表达式字符串
- * @param result 求值结果
- * @param dependencies 依赖的状态路径
- * @param ctx 运行时上下文
- */
-export function setCachedExpression(expr, result, dependencies, ctx) {
-    const cache = getCache(ctx);
-    // LRU 淘汰
-    if (cache.size >= CACHE_CONFIG.maxSize) {
-        evictOldest(cache);
-    }
-    cache.set(expr, {
-        expr,
-        result,
-        dependencies,
-        timestamp: Date.now()
-    });
-}
-/**
- * 使缓存失效
- *
- * 当状态变化时调用，精确删除依赖该状态的缓存
- *
- * @param changedPath 变化的状态路径
- * @param ctx 运行时上下文
- */
-export function invalidateCache(changedPath, ctx) {
-    const cache = getCache(ctx);
-    const toDelete = [];
-    for (const [expr, entry] of cache.entries()) {
-        // 检查是否有依赖被影响
-        const isAffected = entry.dependencies.some(dep => matchPath(dep, changedPath) || matchPath(changedPath, dep));
-        if (isAffected) {
-            toDelete.push(expr);
-        }
-    }
-    // 批量删除
-    for (const expr of toDelete) {
-        cache.delete(expr);
-    }
-}
-/**
- * 清除指定上下文的所有缓存
- */
-export function clearCache(ctx) {
-    const cache = getCache(ctx);
-    cache.clear();
-}
-/**
- * 获取缓存统计信息（调试用）
- */
-export function getCacheStats(ctx) {
-    const cache = getCache(ctx);
-    return {
-        size: cache.size,
-        expressions: Array.from(cache.keys())
-    };
-}
-//# sourceMappingURL=cache.js.map
+import{matchPath as a}from"../runtime/path.js";const f=new WeakMap,o={maxSize:100,ttl:0};function i(t){let e=f.get(t);return e||(e=new Map,f.set(t,e)),e}function u(t,e){return o.ttl>0&&Date.now()-t.timestamp>o.ttl?!1:t.dependencies.every(n=>{if(n.includes("*")){const s=n.split(".*")[0];return e._get(s)!=null}return e._get(n)!==void 0})}function p(t){let e=null,n=1/0;for(const[s,c]of t.entries())c.timestamp<n&&(n=c.timestamp,e=s);e&&t.delete(e)}function d(t,e){const n=i(e),s=n.get(t);return s?u(s,e)?(s.timestamp=Date.now(),s.result):(n.delete(t),null):null}function C(t,e,n,s){const c=i(s);c.size>=o.maxSize&&p(c),c.set(t,{expr:t,result:e,dependencies:n,timestamp:Date.now()})}function y(t,e){const n=i(e),s=[];for(const[c,l]of n.entries())l.dependencies.some(r=>a(r,t)||a(t,r))&&s.push(c);for(const c of s)n.delete(c)}function x(t){i(t).clear()}function g(t){const e=i(t);return{size:e.size,expressions:Array.from(e.keys())}}export{x as clearCache,g as getCacheStats,d as getCachedExpression,y as invalidateCache,C as setCachedExpression};