@ticatec/dyna-js 0.0.3 → 0.1.0

package/README.md

@@ -11,13 +11,13 @@ A TypeScript library for safe dynamic code execution using `new Function()` that
 
 ## Features
 
-✅ **Universal Compatibility** - Works in both Node.js and browser environments
-✅ **TypeScript Support** - Full type safety with comprehensive type definitions
-✅ **Singleton Pattern** - Initialize once, use anywhere
-✅ **Module Imports** - Pre-define classes and functions for dynamic code
-✅ **Configurable Security** - Fine-grained control over allowed APIs and operations
-✅ **Multiple Build Formats** - CommonJS and ESM support
-✅ **Performance Monitoring** - Built-in execution time tracking  
+✅ **Universal Compatibility** - Works in both Node.js and browser environments  
+✅ **TypeScript Support** - Full type safety with comprehensive type definitions  
+✅ **Singleton Pattern** - Initialize once, use anywhere  
+✅ **Module Imports** - Pre-define classes and functions for dynamic code  
+✅ **Configurable Security** - Fine-grained control over allowed APIs and operations  
+✅ **Multiple Build Formats** - CommonJS and ESM support  
+✅ **Performance Monitoring** - Built-in execution time tracking    
 
 ## Installation
 
@@ -75,7 +75,7 @@ const MyFormClass = loader.executeSync(`
     }
   }
   return CustomForm;
-`).result;
+`);
 
 // Instantiate and use
 const form = new MyFormClass();
@@ -86,27 +86,27 @@ form.show();
 
 ### Core Methods
 
-#### `executeSync<T>(code: string, options?: ExecutionOptions): ExecutionResult<T>`
+#### `executeSync<T>(code: string, options?: ExecutionOptions): T`
 
-Synchronously execute code with result and timing information.
+Synchronously execute code and return the result directly.
 
 ```typescript
-const result = loader.executeSync(`
+const form = loader.executeSync(`
   const form = new FlexiForm();
   form.setTitle('Dynamic Form');
   return form;
 `);
 
-console.log(result.result); // FlexiForm instance
-console.log(result.executionTime); // Execution time in milliseconds
+console.log(form); // FlexiForm instance
+// Execution time is logged to console automatically
 ```
 
-#### `execute<T>(code: string, options?: ExecutionOptions): Promise<ExecutionResult<T>>`
+#### `execute<T>(code: string, options?: ExecutionOptions): Promise<T>`
 
 Asynchronously execute code with timeout support.
 
 ```typescript
-const result = await loader.execute(`
+const form = await loader.execute(`
   return new Promise(resolve => {
     const form = new FlexiForm();
     resolve(form);
@@ -115,14 +115,16 @@ const result = await loader.execute(`
   timeout: 3000,
   context: { customVar: 'value' }
 });
+
+console.log(form); // FlexiForm instance
 ```
 
-#### `executeWithImports<T>(code: string, imports: object, options?: ExecutionOptions): ExecutionResult<T>`
+#### `executeWithImports<T>(code: string, imports: object, options?: ExecutionOptions): T`
 
 Execute code with additional temporary imports.
 
 ```typescript
-const result = loader.executeWithImports(`
+const component = loader.executeWithImports(`
   return new CustomComponent({
     message: 'Hello from dynamic code!'
   });
@@ -254,7 +256,7 @@ const DynamicFormBuilder = loader.executeSync(`
   }
 
   return FormBuilder;
-`).result;
+`);
 
 // Use the dynamically created form builder
 const formBuilder = new DynamicFormBuilder({
@@ -296,6 +298,206 @@ const validation = dynamicValidator({
 });
 ```
 
+## ModuleLoader - Dynamic Module Management
+
+`ModuleLoader` is a singleton class for managing dynamic JavaScript modules with automatic caching and version control. It's perfect for loading remote code modules and managing their lifecycle.
+
+### Key Features
+
+- **Singleton Pattern** - Single instance manages all modules
+- **Version Control** - Automatic digest-based freshness checking
+- **Local Caching** - Stores modules in localStorage for offline access
+- **Lazy Loading** - Modules are only instantiated when needed
+- **Custom Hooks** - Override default behaviors with custom implementations
+
+### Basic Usage
+
+#### 1. Initialize the ModuleLoader
+
+```typescript
+import { ModuleLoader } from '@ticatec/dyna-js';
+
+// Define how to load modules from your server
+const loadModuleFromServer = async (moduleInfo) => {
+  const response = await fetch(`/api/modules/${moduleInfo.code}`);
+  return response.json(); // Should return { code, digest, scriptText }
+};
+
+// Initialize the singleton
+const moduleLoader = ModuleLoader.initialize(loadModuleFromServer, {
+  // All options are optional - defaults use localStorage
+});
+```
+
+#### 2. Check and Update Modules
+
+```typescript
+// Check a list of modules and update if needed
+await moduleLoader.checkFreshScripts([
+  { code: 'user-form', digest: 'abc123...' },
+  { code: 'data-grid', digest: 'def456...' },
+  { code: 'chart-widget', digest: 'ghi789...' }
+]);
+
+// This will:
+// 1. Check each module's digest against localStorage
+// 2. Download and save modules that have changed
+// 3. Clear the module instance cache
+```
+
+#### 3. Create and Use Modules
+
+```typescript
+// Import dependencies that the module needs
+import React from 'react';
+import ReactDOM from 'react-dom';
+
+// Create the module instance
+const UserForm = moduleLoader.createModule('user-form', {
+  React,
+  ReactDOM,
+  // Add any other dependencies your module needs
+});
+
+// Use the module (it's now cached for subsequent calls)
+const formInstance = new UserForm({
+  title: 'User Registration',
+  onSubmit: handleSubmit
+});
+```
+
+### Advanced Configuration
+
+#### Custom Module Check Function
+
+```typescript
+const moduleLoader = ModuleLoader.initialize(loadModuleFromServer, {
+  // Custom logic to check if module needs updating
+  moduleCheck: (moduleInfo) => {
+    const localVersion = localStorage.getItem(`version:${moduleInfo.code}`);
+    return localVersion === moduleInfo.version;
+  }
+});
+```
+
+#### Custom Storage Implementation
+
+```typescript
+// Use your own storage solution (IndexedDB, custom cache, etc.)
+const moduleLoader = ModuleLoader.initialize(loadModuleFromServer, {
+  // Custom save function
+  saveModule: (moduleData) => {
+    myCustomCache.set(moduleData.code, {
+      digest: moduleData.digest,
+      script: moduleData.scriptText,
+      timestamp: Date.now()
+    });
+  },
+
+  // Custom load function
+  loadLocalModule: (moduleCode) => {
+    const cached = myCustomCache.get(moduleCode);
+    return cached ? cached.script : null;
+  }
+});
+```
+
+### Complete Example
+
+```typescript
+import { ModuleLoader, initializeDynaJs } from '@ticatec/dyna-js';
+import React from 'react';
+import ReactDOM from 'react-dom';
+
+// 1. Initialize DynaJs with your base imports
+initializeDynaJs({
+  defaultImports: {
+    Dialog: DialogClass,
+    MessageBox: MessageBoxClass
+  }
+});
+
+// 2. Setup module loader
+const loadModule = async (moduleInfo) => {
+  const response = await fetch(`/api/modules/${moduleInfo.code}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ digest: moduleInfo.digest })
+  });
+
+  if (!response.ok) throw new Error('Failed to load module');
+  return response.json();
+};
+
+const moduleLoader = ModuleLoader.initialize(loadModule, {});
+
+// 3. On application startup, check for module updates
+async function initializeApp() {
+  try {
+    // Get module manifest from server
+    const manifest = await fetch('/api/modules/manifest').then(r => r.json());
+
+    // Update all modules that have changed
+    await moduleLoader.checkFreshScripts(manifest.modules);
+
+    console.log('All modules are up to date!');
+  } catch (error) {
+    console.error('Failed to update modules:', error);
+  }
+}
+
+// 4. Load and use modules on demand
+function loadUserForm() {
+  // This will use the cached version from localStorage
+  const UserForm = moduleLoader.createModule('user-form', {
+    React,
+    ReactDOM,
+    Dialog: DialogClass,
+    MessageBox: MessageBoxClass
+  });
+
+  // Subsequent calls return the same cached instance
+  const form = new UserForm();
+  form.render();
+}
+
+// Initialize
+initializeApp().then(() => {
+  loadUserForm();
+});
+```
+
+### Module Data Format
+
+Your server should return module data in this format:
+
+```typescript
+interface ModuleData {
+  code: string;        // Unique module identifier
+  digest: string;      // Hash/version identifier (e.g., MD5, SHA-256)
+  scriptText: string;  // The actual JavaScript code to execute
+}
+```
+
+### Best Practices
+
+1. **Version Control**: Use content-based hashing (MD5, SHA-256) for the digest field
+2. **Graceful Degradation**: Handle network failures when loading modules
+3. **Dependency Injection**: Pass all required dependencies in the imports object
+4. **Cache Invalidation**: Call `checkFreshScripts()` on app startup and periodically
+5. **Error Handling**: Wrap module creation in try-catch blocks
+
+```typescript
+try {
+  const module = moduleLoader.createModule('my-module', imports);
+  const instance = new module();
+  instance.run();
+} catch (error) {
+  console.error('Module failed to load or execute:', error);
+  // Fallback to default behavior
+}
+```
+
 ## Error Handling
 
 ```typescript
@@ -306,7 +508,7 @@ try {
   `);
 } catch (error) {
   console.error('Execution failed:', error.message);
-  // Error includes execution time and detailed error information
+  // Error message includes execution time and detailed error information
 }
 ```
 
@@ -325,7 +527,6 @@ Full TypeScript support with comprehensive type definitions:
 ```typescript
 import { 
   DynaJs,
-  ExecutionResult,
   ExecutionOptions,
   ModuleImports 
 } from '@ticatec/dyna-js';

package/README_CN.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://badge.fury.io/js/@ticatec%2Fdyna-js.svg)](https://badge.fury.io/js/@ticatec%2Fdyna-js)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
+[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org())
 [![Node.js](https://img.shields.io/badge/Node.js-14%2B-green.svg)](https://nodejs.org/)
 
 [English Documentation](README.md)
@@ -11,12 +11,12 @@
 
 ## 功能特性
 
-✅ **通用兼容性** - 同时支持 Node.js 和浏览器环境
-✅ **TypeScript 支持** - 完整的类型安全和类型定义
-✅ **单例模式** - 一次初始化，全局使用
-✅ **模块导入** - 为动态代码预定义类和函数
-✅ **可配置安全性** - 对允许的 API 和操作进行细粒度控制
-✅ **多种构建格式** - 支持 CommonJS 和 ESM
+✅ **通用兼容性** - 同时支持 Node.js 和浏览器环境  
+✅ **TypeScript 支持** - 完整的类型安全和类型定义  
+✅ **单例模式** - 一次初始化，全局使用  
+✅ **模块导入** - 为动态代码预定义类和函数  
+✅ **可配置安全性** - 对允许的 API 和操作进行细粒度控制  
+✅ **多种构建格式** - 支持 CommonJS 和 ESM  
 ✅ **性能监控** - 内置执行时间跟踪  
 
 ## 安装
@@ -75,7 +75,7 @@ const MyFormClass = loader.executeSync(`
     }
   }
   return CustomForm;
-`).result;
+`);
 
 // 实例化并使用
 const form = new MyFormClass();
@@ -86,27 +86,27 @@ form.show();
 
 ### 核心方法
 
-#### `executeSync<T>(code: string, options?: ExecutionOptions): ExecutionResult<T>`
+#### `executeSync<T>(code: string, options?: ExecutionOptions): T`
 
-同步执行代码并返回结果和计时信息。
+同步执行代码并直接返回结果。
 
 ```typescript
-const result = loader.executeSync(`
+const form = loader.executeSync(`
   const form = new FlexiForm();
   form.setTitle('动态表单');
   return form;
 `);
 
-console.log(result.result); // FlexiForm 实例
-console.log(result.executionTime); // 执行时间（毫秒）
+console.log(form); // FlexiForm 实例
+// 执行时间会自动记录到控制台
 ```
 
-#### `execute<T>(code: string, options?: ExecutionOptions): Promise<ExecutionResult<T>>`
+#### `execute<T>(code: string, options?: ExecutionOptions): Promise<T>`
 
 异步执行代码，支持超时控制。
 
 ```typescript
-const result = await loader.execute(`
+const form = await loader.execute(`
   return new Promise(resolve => {
     const form = new FlexiForm();
     resolve(form);
@@ -115,14 +115,16 @@ const result = await loader.execute(`
   timeout: 3000,
   context: { customVar: 'value' }
 });
+
+console.log(form); // FlexiForm 实例
 ```
 
-#### `executeWithImports<T>(code: string, imports: object, options?: ExecutionOptions): ExecutionResult<T>`
+#### `executeWithImports<T>(code: string, imports: object, options?: ExecutionOptions): T`
 
 使用额外的临时导入执行代码。
 
 ```typescript
-const result = loader.executeWithImports(`
+const component = loader.executeWithImports(`
   return new CustomComponent({
     message: '来自动态代码的问候！'
   });
@@ -254,7 +256,7 @@ const DynamicFormBuilder = loader.executeSync(`
   }
 
   return FormBuilder;
-`).result;
+`);
 
 // 使用动态创建的表单构建器
 const formBuilder = new DynamicFormBuilder({
@@ -273,15 +275,15 @@ formBuilder
 const dynamicValidator = loader.createFunction(`
   return function validateForm(formData) {
     const errors = [];
-    
+
     if (!formData.name) {
       errors.push('姓名是必填项');
     }
-    
+
     if (!formData.email || !formData.email.includes('@')) {
       errors.push('需要有效的邮箱地址');
     }
-    
+
     return {
       isValid: errors.length === 0,
       errors: errors
@@ -296,6 +298,206 @@ const validation = dynamicValidator({
 });
 ```
 
+## ModuleLoader - 动态模块管理
+
+`ModuleLoader` 是一个单例类，用于管理具有自动缓存和版本控制的动态 JavaScript 模块。它非常适合加载远程代码模块并管理它们的生命周期。
+
+### 核心特性
+
+- **单例模式** - 单个实例管理所有模块
+- **版本控制** - 基于摘要的自动新鲜度检查
+- **本地缓存** - 将模块存储在 localStorage 中以供离线访问
+- **懒加载** - 模块仅在需要时才实例化
+- **自定义钩子** - 使用自定义实现覆盖默认行为
+
+### 基础用法
+
+#### 1. 初始化 ModuleLoader
+
+```typescript
+import { ModuleLoader } from '@ticatec/dyna-js';
+
+// 定义如何从服务器加载模块
+const loadModuleFromServer = async (moduleInfo) => {
+  const response = await fetch(`/api/modules/${moduleInfo.code}`);
+  return response.json(); // 应该返回 { code, digest, scriptText }
+};
+
+// 初始化单例
+const moduleLoader = ModuleLoader.initialize(loadModuleFromServer, {
+  // 所有选项都是可选的 - 默认使用 localStorage
+});
+```
+
+#### 2. 检查和更新模块
+
+```typescript
+// 检查模块列表并在需要时更新
+await moduleLoader.checkFreshScripts([
+  { code: 'user-form', digest: 'abc123...' },
+  { code: 'data-grid', digest: 'def456...' },
+  { code: 'chart-widget', digest: 'ghi789...' }
+]);
+
+// 这将：
+// 1. 检查每个模块的摘要与 localStorage 中的对比
+// 2. 下载并保存已更改的模块
+// 3. 清除模块实例缓存
+```
+
+#### 3. 创建和使用模块
+
+```typescript
+// 导入模块需要的依赖项
+import React from 'react';
+import ReactDOM from 'react-dom';
+
+// 创建模块实例
+const UserForm = moduleLoader.createModule('user-form', {
+  React,
+  ReactDOM,
+  // 添加模块需要的任何其他依赖项
+});
+
+// 使用模块（它现在已被缓存以供后续调用）
+const formInstance = new UserForm({
+  title: '用户注册',
+  onSubmit: handleSubmit
+});
+```
+
+### 高级配置
+
+#### 自定义模块检查函数
+
+```typescript
+const moduleLoader = ModuleLoader.initialize(loadModuleFromServer, {
+  // 自定义逻辑来检查模块是否需要更新
+  moduleCheck: (moduleInfo) => {
+    const localVersion = localStorage.getItem(`version:${moduleInfo.code}`);
+    return localVersion === moduleInfo.version;
+  }
+});
+```
+
+#### 自定义存储实现
+
+```typescript
+// 使用您自己的存储解决方案（IndexedDB、自定义缓存等）
+const moduleLoader = ModuleLoader.initialize(loadModuleFromServer, {
+  // 自定义保存函数
+  saveModule: (moduleData) => {
+    myCustomCache.set(moduleData.code, {
+      digest: moduleData.digest,
+      script: moduleData.scriptText,
+      timestamp: Date.now()
+    });
+  },
+
+  // 自定义加载函数
+  loadLocalModule: (moduleCode) => {
+    const cached = myCustomCache.get(moduleCode);
+    return cached ? cached.script : null;
+  }
+});
+```
+
+### 完整示例
+
+```typescript
+import { ModuleLoader, initializeDynaJs } from '@ticatec/dyna-js';
+import React from 'react';
+import ReactDOM from 'react-dom';
+
+// 1. 使用基础导入初始化 DynaJs
+initializeDynaJs({
+  defaultImports: {
+    Dialog: DialogClass,
+    MessageBox: MessageBoxClass
+  }
+});
+
+// 2. 设置模块加载器
+const loadModule = async (moduleInfo) => {
+  const response = await fetch(`/api/modules/${moduleInfo.code}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ digest: moduleInfo.digest })
+  });
+
+  if (!response.ok) throw new Error('加载模块失败');
+  return response.json();
+};
+
+const moduleLoader = ModuleLoader.initialize(loadModule, {});
+
+// 3. 在应用启动时，检查模块更新
+async function initializeApp() {
+  try {
+    // 从服务器获取模块清单
+    const manifest = await fetch('/api/modules/manifest').then(r => r.json());
+
+    // 更新所有已更改的模块
+    await moduleLoader.checkFreshScripts(manifest.modules);
+
+    console.log('所有模块都是最新的！');
+  } catch (error) {
+    console.error('更新模块失败：', error);
+  }
+}
+
+// 4. 按需加载和使用模块
+function loadUserForm() {
+  // 这将使用 localStorage 中的缓存版本
+  const UserForm = moduleLoader.createModule('user-form', {
+    React,
+    ReactDOM,
+    Dialog: DialogClass,
+    MessageBox: MessageBoxClass
+  });
+
+  // 后续调用返回相同的缓存实例
+  const form = new UserForm();
+  form.render();
+}
+
+// 初始化
+initializeApp().then(() => {
+  loadUserForm();
+});
+```
+
+### 模块数据格式
+
+您的服务器应以此格式返回模块数据：
+
+```typescript
+interface ModuleData {
+  code: string;        // 唯一的模块标识符
+  digest: string;      // 哈希/版本标识符（例如 MD5、SHA-256）
+  scriptText: string;  // 要执行的实际 JavaScript 代码
+}
+```
+
+### 最佳实践
+
+1. **版本控制**：对 digest 字段使用基于内容的哈希（MD5、SHA-256）
+2. **优雅降级**：处理加载模块时的网络故障
+3. **依赖注入**：在 imports 对象中传递所有必需的依赖项
+4. **缓存失效**：在应用启动时和定期调用 `checkFreshScripts()`
+5. **错误处理**：将模块创建包装在 try-catch 块中
+
+```typescript
+try {
+  const module = moduleLoader.createModule('my-module', imports);
+  const instance = new module();
+  instance.run();
+} catch (error) {
+  console.error('模块加载或执行失败：', error);
+  // 回退到默认行为
+}
+```
+
 ## 错误处理
 
 ```typescript
@@ -306,7 +508,7 @@ try {
   `);
 } catch (error) {
   console.error('执行失败：', error.message);
-  // 错误包含执行时间和详细的错误信息
+  // 错误信息包含执行时间和详细的错误信息
 }
 ```
 
@@ -323,11 +525,10 @@ try {
 具有完整类型定义的 TypeScript 支持：
 
 ```typescript
-import { 
+import {
   DynaJs,
-  ExecutionResult,
   ExecutionOptions,
-  ModuleImports 
+  ModuleImports
 } from '@ticatec/dyna-js';
 ```
 
@@ -364,9 +565,9 @@ MIT 许可证 - 详情请查看 [LICENSE](LICENSE) 文件。
 ### 动态表单创建
 ```typescript
 // 适合创建各种动态表单组件
-const ContactForm = loader.executeSync(`...`).result;
-const SurveyForm = loader.executeSync(`...`).result;
-const RegistrationForm = loader.executeSync(`...`).result;
+const ContactForm = loader.executeSync(`...`);
+const SurveyForm = loader.executeSync(`...`);
+const RegistrationForm = loader.executeSync(`...`);
 ```
 
 ### 业务规则执行
@@ -377,7 +578,7 @@ const businessRule = loader.executeSync(`
     // 复杂的业务逻辑
     return processBusinessRule(data);
   };
-`).result;
+`);
 ```
 
 ### 模板渲染
@@ -391,5 +592,5 @@ const templateEngine = loader.executeSync(`
     }
   }
   return TemplateEngine;
-`).result;
+`);
 ```