@ticatec/dyna-js 0.0.3 → 0.0.4

package/README.md

@@ -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({
@@ -306,7 +308,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
 }
 ```
 

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)
@@ -17,7 +17,7 @@
 ✅ **模块导入** - 为动态代码预定义类和函数
 ✅ **可配置安全性** - 对允许的 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
@@ -306,7 +308,7 @@ try {
   `);
 } catch (error) {
   console.error('执行失败：', error.message);
-  // 错误包含执行时间和详细的错误信息
+  // 错误信息包含执行时间和详细的错误信息
 }
 ```
 
@@ -323,11 +325,11 @@ try {
 具有完整类型定义的 TypeScript 支持：
 
 ```typescript
-import { 
+import {
   DynaJs,
   ExecutionResult,
   ExecutionOptions,
-  ModuleImports 
+  ModuleImports
 } from '@ticatec/dyna-js';
 ```
 
@@ -364,9 +366,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 +379,7 @@ const businessRule = loader.executeSync(`
     // 复杂的业务逻辑
     return processBusinessRule(data);
   };
-`).result;
+`);
 ```
 
 ### 模板渲染
@@ -391,5 +393,5 @@ const templateEngine = loader.executeSync(`
     }
   }
   return TemplateEngine;
-`).result;
+`);
 ```

package/dist/DynaJs.d.ts

@@ -1,18 +1,213 @@
-import { ExecutionOptions, ExecutionResult, DynaJsConfig, ModuleImports } from './types';
+import { ExecutionOptions, DynaJsConfig, ModuleImports } from './types';
+/**
+ * DynaJs - A safe dynamic code execution library
+ *
+ * Provides secure execution of dynamic JavaScript code using new Function()
+ * with configurable security policies and sandboxing capabilities.
+ *
+ * @example
+ * ```typescript
+ * const loader = new DynaJs({
+ *   defaultImports: { MyClass },
+ *   validateCode: true,
+ *   allowBrowserAPIs: false
+ * });
+ *
+ * const result = loader.executeSync(`return new MyClass()`);
+ * ```
+ */
 export default class DynaJs {
     private config;
+    /**
+     * Creates a new DynaJs instance
+     *
+     * @param config - Configuration options for the DynaJs instance
+     * @param config.defaultTimeout - Default timeout for async execution in milliseconds (default: 5000)
+     * @param config.defaultStrict - Whether to use strict mode by default (default: true)
+     * @param config.allowedGlobals - Whitelist of allowed global variables (empty = allow all defaultImports)
+     * @param config.blockedGlobals - Blacklist of blocked global variables
+     * @param config.defaultImports - Pre-imported classes/functions available to dynamic code
+     * @param config.allowTimers - Allow setTimeout/setInterval in dynamic code (default: false)
+     * @param config.allowDynamicImports - Allow import()/require() in dynamic code (default: false)
+     * @param config.validateCode - Enable code validation before execution (default: true)
+     * @param config.allowBrowserAPIs - Allow access to browser APIs like window/document (default: false)
+     * @param config.allowNodeAPIs - Allow access to Node.js APIs like process/require (default: false)
+     */
     constructor(config?: DynaJsConfig);
-    execute<T = any>(code: string, options?: ExecutionOptions): Promise<ExecutionResult<T>>;
-    executeSync<T = any>(code: string, options?: ExecutionOptions): ExecutionResult<T>;
+    /**
+     * Asynchronously execute dynamic code with timeout support
+     *
+     * @template T - The expected return type of the executed code
+     * @param code - The JavaScript code to execute
+     * @param options - Execution options
+     * @param options.context - Additional context variables for the code
+     * @param options.timeout - Execution timeout in milliseconds (overrides defaultTimeout)
+     * @param options.strict - Whether to use strict mode (overrides defaultStrict)
+     * @param options.imports - Additional imports for this execution only
+     * @returns Promise resolving to the execution result
+     */
+    execute<T = any>(code: string, options?: ExecutionOptions): Promise<T>;
+    /**
+     * Synchronously execute dynamic code and return result directly
+     *
+     * @template T - The expected return type of the executed code
+     * @param code - The JavaScript code to execute
+     * @param options - Execution options
+     * @param options.context - Additional context variables for the code
+     * @param options.strict - Whether to use strict mode (overrides defaultStrict)
+     * @param options.imports - Additional imports for this execution only
+     * @returns The direct result of code execution
+     */
+    executeSync<T = any>(code: string, options?: ExecutionOptions): T;
+    /**
+     * Execute code with a timeout constraint
+     *
+     * @private
+     * @template T - The expected return type
+     * @param code - The JavaScript code to execute
+     * @param context - Execution context with available variables
+     * @param timeout - Maximum execution time in milliseconds
+     * @param strict - Whether to use strict mode
+     * @returns Promise resolving to the execution result
+     * @throws {Error} If execution exceeds timeout or runtime error occurs
+     */
     private executeWithTimeout;
+    /**
+     * Core code execution engine using new Function()
+     *
+     * @private
+     * @param code - The JavaScript code to execute
+     * @param context - Execution context with available variables
+     * @param strict - Whether to use strict mode
+     * @returns The execution result
+     * @throws {Error} If code execution fails
+     */
     private executeCode;
+    /**
+     * Create a reusable function from dynamic code
+     *
+     * @template T - The function signature type
+     * @param code - The JavaScript code for the function body
+     * @param paramNames - Array of parameter names for the function
+     * @param options - Execution options
+     * @param options.context - Additional context variables
+     * @param options.strict - Whether to use strict mode
+     * @param options.imports - Additional imports
+     * @returns A function that can be called multiple times
+     * @throws {Error} If function creation fails
+     *
+     * @example
+     * ```typescript
+     * const validator = loader.createFunction<(data: any) => boolean>(`
+     *   return function(data) {
+     *     return data.name && data.email;
+     *   };
+     * `);
+     * const isValid = validator({ name: 'John', email: 'john@example.com' });
+     * ```
+     */
     createFunction<T extends (...args: any[]) => any>(code: string, paramNames?: string[], options?: ExecutionOptions): T;
-    executeWithImports<T = any>(code: string, imports: ModuleImports, options?: ExecutionOptions): ExecutionResult<T>;
-    executeWithImportsAsync<T = any>(code: string, imports: ModuleImports, options?: ExecutionOptions): Promise<ExecutionResult<T>>;
+    /**
+     * Synchronously execute code with additional temporary imports
+     *
+     * @template T - The expected return type
+     * @param code - The JavaScript code to execute
+     * @param imports - Additional imports to merge with defaultImports
+     * @param options - Additional execution options
+     * @returns The direct result of code execution
+     * @throws {Error} If code validation fails or runtime error occurs
+     *
+     * @example
+     * ```typescript
+     * const result = loader.executeWithImports(`
+     *   return new CustomComponent();
+     * `, {
+     *   CustomComponent: MyCustomComponent
+     * });
+     * ```
+     */
+    executeWithImports<T = any>(code: string, imports: ModuleImports, options?: ExecutionOptions): T;
+    /**
+     * Asynchronously execute code with additional temporary imports
+     *
+     * @template T - The expected return type
+     * @param code - The JavaScript code to execute
+     * @param imports - Additional imports to merge with defaultImports
+     * @param options - Additional execution options (including timeout)
+     * @returns Promise resolving to the execution result
+     * @throws {Error} If code validation fails, execution times out, or runtime error occurs
+     *
+     * @example
+     * ```typescript
+     * const result = await loader.executeWithImportsAsync(`
+     *   return await fetchData();
+     * `, {
+     *   fetchData: myFetchFunction
+     * }, { timeout: 5000 });
+     * ```
+     */
+    executeWithImportsAsync<T = any>(code: string, imports: ModuleImports, options?: ExecutionOptions): Promise<T>;
+    /**
+     * Singleton instance of DynaJs
+     * @private
+     */
     static instance: DynaJs | null;
+    /**
+     * Initialize the singleton instance of DynaJs
+     *
+     * @param config - Configuration options for the singleton instance
+     * @returns The initialized singleton instance
+     *
+     * @example
+     * ```typescript
+     * DynaJs.initialize({
+     *   defaultImports: { MyClass, MyFunction },
+     *   validateCode: true
+     * });
+     * ```
+     */
     static initialize(config: DynaJsConfig): DynaJs;
+    /**
+     * Get the singleton instance of DynaJs
+     *
+     * @returns The singleton instance
+     * @throws {Error} If DynaJs hasn't been initialized
+     *
+     * @example
+     * ```typescript
+     * const loader = DynaJs.getInstance();
+     * const result = loader.executeSync(`return 1 + 1`);
+     * ```
+     */
     static getInstance(): DynaJs;
+    /**
+     * Reset the singleton instance (useful for testing)
+     *
+     * @example
+     * ```typescript
+     * DynaJs.reset();
+     * DynaJs.initialize(newConfig);
+     * ```
+     */
     static reset(): void;
+    /**
+     * Prepare the execution context by merging user context, imports, and applying security filters
+     *
+     * Execution flow:
+     * 1. Create safe context (filtering browser/node APIs based on config)
+     * 2. Merge with defaultImports and additional imports
+     * 3. Apply allowedGlobals whitelist filter if configured
+     *
+     * @private
+     * @param userContext - User-provided context variables
+     * @param imports - Additional imports for this execution
+     * @returns The final execution context
+     *
+     * @remarks
+     * If allowedGlobals is set and not empty, only variables in the whitelist will be available.
+     * This happens AFTER merging defaultImports, so make sure to include all needed imports
+     * in the allowedGlobals array if you use this feature.
+     */
     private prepareContext;
 }
 //# sourceMappingURL=DynaJs.d.ts.map

package/dist/DynaJs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DynaJs.d.ts","sourceRoot":"","sources":["../src/DynaJs.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,aAAa,EACd,MAAM,SAAS,CAAC;AAGjB,MAAM,CAAC,OAAO,OAAO,MAAM;IACzB,OAAO,CAAC,MAAM,CAAyB;gBAE3B,MAAM,GAAE,YAAiB;IAe/B,OAAO,CAAC,CAAC,GAAG,GAAG,EACnB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IA4B9B,WAAW,CAAC,CAAC,GAAG,GAAG,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,gBAAqB,GAC7B,eAAe,CAAC,CAAC,CAAC;YA4BP,kBAAkB;IAsBhC,OAAO,CAAC,WAAW;IAenB,cAAc,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAC9C,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,MAAM,EAAO,EACzB,OAAO,GAAE,gBAAqB,GAC7B,CAAC;IAuBJ,kBAAkB,CAAC,CAAC,GAAG,GAAG,EACxB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,aAAa,EACtB,OAAO,GAAE,gBAAqB,GAC7B,eAAe,CAAC,CAAC,CAAC;IAOf,uBAAuB,CAAC,CAAC,GAAG,GAAG,EACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,aAAa,EACtB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IAO9B,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAEtC,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM;IAO/C,MAAM,CAAC,WAAW,IAAI,MAAM;IAO5B,MAAM,CAAC,KAAK,IAAI,IAAI;IAIpB,OAAO,CAAC,cAAc;CAwBvB"}
+{"version":3,"file":"DynaJs.d.ts","sourceRoot":"","sources":["../src/DynaJs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,gBAAgB,EAAE,YAAY,EAAE,aAAa,EAAC,MAAM,SAAS,CAAC;AAGxF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,OAAO,OAAO,MAAM;IACvB,OAAO,CAAC,MAAM,CAAyB;IAEvC;;;;;;;;;;;;;;OAcG;gBACS,MAAM,GAAE,YAAiB;IAerC;;;;;;;;;;;OAWG;IACG,OAAO,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,CAAC,CAAC;IAwBhF;;;;;;;;;;OAUG;IACH,WAAW,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,CAAC;IAuBrE;;;;;;;;;;;OAWG;YACW,kBAAkB;IAiBhC;;;;;;;;;OASG;IACH,OAAO,CAAC,WAAW;IAenB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,cAAc,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAC5C,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,MAAM,EAAO,EACzB,OAAO,GAAE,gBAAqB,GAC/B,CAAC;IAuBJ;;;;;;;;;;;;;;;;;;OAkBG;IACH,kBAAkB,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,GAAE,gBAAqB,GAAG,CAAC;IAOpG;;;;;;;;;;;;;;;;;;OAkBG;IACG,uBAAuB,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,CAAC,CAAC;IAOxH;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAEtC;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM;IAO/C;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,WAAW,IAAI,MAAM;IAO5B;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK,IAAI,IAAI;IAIpB;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,cAAc;CAwBzB"}

package/dist/DynaJs.esm.js

@@ -1,5 +1,37 @@
 import { createSafeContext, validateCode } from './utils';
+/**
+ * DynaJs - A safe dynamic code execution library
+ *
+ * Provides secure execution of dynamic JavaScript code using new Function()
+ * with configurable security policies and sandboxing capabilities.
+ *
+ * @example
+ * ```typescript
+ * const loader = new DynaJs({
+ *   defaultImports: { MyClass },
+ *   validateCode: true,
+ *   allowBrowserAPIs: false
+ * });
+ *
+ * const result = loader.executeSync(`return new MyClass()`);
+ * ```
+ */
 class DynaJs {
+    /**
+     * Creates a new DynaJs instance
+     *
+     * @param config - Configuration options for the DynaJs instance
+     * @param config.defaultTimeout - Default timeout for async execution in milliseconds (default: 5000)
+     * @param config.defaultStrict - Whether to use strict mode by default (default: true)
+     * @param config.allowedGlobals - Whitelist of allowed global variables (empty = allow all defaultImports)
+     * @param config.blockedGlobals - Blacklist of blocked global variables
+     * @param config.defaultImports - Pre-imported classes/functions available to dynamic code
+     * @param config.allowTimers - Allow setTimeout/setInterval in dynamic code (default: false)
+     * @param config.allowDynamicImports - Allow import()/require() in dynamic code (default: false)
+     * @param config.validateCode - Enable code validation before execution (default: true)
+     * @param config.allowBrowserAPIs - Allow access to browser APIs like window/document (default: false)
+     * @param config.allowNodeAPIs - Allow access to Node.js APIs like process/require (default: false)
+     */
     constructor(config = {}) {
         this.config = {
             defaultTimeout: config.defaultTimeout ?? 5000,
@@ -14,6 +46,18 @@ class DynaJs {
             allowNodeAPIs: config.allowNodeAPIs ?? false
         };
     }
+    /**
+     * Asynchronously execute dynamic code with timeout support
+     *
+     * @template T - The expected return type of the executed code
+     * @param code - The JavaScript code to execute
+     * @param options - Execution options
+     * @param options.context - Additional context variables for the code
+     * @param options.timeout - Execution timeout in milliseconds (overrides defaultTimeout)
+     * @param options.strict - Whether to use strict mode (overrides defaultStrict)
+     * @param options.imports - Additional imports for this execution only
+     * @returns Promise resolving to the execution result
+     */
     async execute(code, options = {}) {
         const startTime = performance.now();
         try {
@@ -27,17 +71,25 @@ class DynaJs {
             const timeout = options.timeout ?? this.config.defaultTimeout;
             const strict = options.strict ?? this.config.defaultStrict;
             const result = await this.executeWithTimeout(code, context, timeout, strict);
-            const executionTime = performance.now() - startTime;
-            return {
-                result: result,
-                executionTime
-            };
+            console.info(`Build dyna code in ${performance.now() - startTime}ms`);
+            return result;
         }
         catch (error) {
             const executionTime = performance.now() - startTime;
             throw new Error(`Script execution failed after ${executionTime.toFixed(2)}ms: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    /**
+     * Synchronously execute dynamic code and return result directly
+     *
+     * @template T - The expected return type of the executed code
+     * @param code - The JavaScript code to execute
+     * @param options - Execution options
+     * @param options.context - Additional context variables for the code
+     * @param options.strict - Whether to use strict mode (overrides defaultStrict)
+     * @param options.imports - Additional imports for this execution only
+     * @returns The direct result of code execution
+     */
     executeSync(code, options = {}) {
         const startTime = performance.now();
         try {
@@ -50,17 +102,26 @@ class DynaJs {
             const context = this.prepareContext(options.context, options.imports);
             const strict = options.strict ?? this.config.defaultStrict;
             const result = this.executeCode(code, context, strict);
-            const executionTime = performance.now() - startTime;
-            return {
-                result: result,
-                executionTime
-            };
+            console.info(`Build dyna code in ${performance.now() - startTime}ms`);
+            return result;
         }
         catch (error) {
             const executionTime = performance.now() - startTime;
             throw new Error(`Script execution failed after ${executionTime.toFixed(2)}ms: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    /**
+     * Execute code with a timeout constraint
+     *
+     * @private
+     * @template T - The expected return type
+     * @param code - The JavaScript code to execute
+     * @param context - Execution context with available variables
+     * @param timeout - Maximum execution time in milliseconds
+     * @param strict - Whether to use strict mode
+     * @returns Promise resolving to the execution result
+     * @throws {Error} If execution exceeds timeout or runtime error occurs
+     */
     async executeWithTimeout(code, context, timeout, strict) {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
@@ -77,6 +138,16 @@ class DynaJs {
             }
         });
     }
+    /**
+     * Core code execution engine using new Function()
+     *
+     * @private
+     * @param code - The JavaScript code to execute
+     * @param context - Execution context with available variables
+     * @param strict - Whether to use strict mode
+     * @returns The execution result
+     * @throws {Error} If code execution fails
+     */
     executeCode(code, context, strict) {
         const contextKeys = Object.keys(context);
         const contextValues = Object.values(context);
@@ -90,6 +161,29 @@ class DynaJs {
             throw new Error(`Code execution error: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    /**
+     * Create a reusable function from dynamic code
+     *
+     * @template T - The function signature type
+     * @param code - The JavaScript code for the function body
+     * @param paramNames - Array of parameter names for the function
+     * @param options - Execution options
+     * @param options.context - Additional context variables
+     * @param options.strict - Whether to use strict mode
+     * @param options.imports - Additional imports
+     * @returns A function that can be called multiple times
+     * @throws {Error} If function creation fails
+     *
+     * @example
+     * ```typescript
+     * const validator = loader.createFunction<(data: any) => boolean>(`
+     *   return function(data) {
+     *     return data.name && data.email;
+     *   };
+     * `);
+     * const isValid = validator({ name: 'John', email: 'john@example.com' });
+     * ```
+     */
     createFunction(code, paramNames = [], options = {}) {
         const context = this.prepareContext(options.context, options.imports);
         const strict = options.strict ?? this.config.defaultStrict;
@@ -109,33 +203,124 @@ class DynaJs {
             throw new Error(`Function creation error: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    /**
+     * Synchronously execute code with additional temporary imports
+     *
+     * @template T - The expected return type
+     * @param code - The JavaScript code to execute
+     * @param imports - Additional imports to merge with defaultImports
+     * @param options - Additional execution options
+     * @returns The direct result of code execution
+     * @throws {Error} If code validation fails or runtime error occurs
+     *
+     * @example
+     * ```typescript
+     * const result = loader.executeWithImports(`
+     *   return new CustomComponent();
+     * `, {
+     *   CustomComponent: MyCustomComponent
+     * });
+     * ```
+     */
     executeWithImports(code, imports, options = {}) {
         return this.executeSync(code, {
             ...options,
             imports: { ...this.config.defaultImports, ...imports }
         });
     }
+    /**
+     * Asynchronously execute code with additional temporary imports
+     *
+     * @template T - The expected return type
+     * @param code - The JavaScript code to execute
+     * @param imports - Additional imports to merge with defaultImports
+     * @param options - Additional execution options (including timeout)
+     * @returns Promise resolving to the execution result
+     * @throws {Error} If code validation fails, execution times out, or runtime error occurs
+     *
+     * @example
+     * ```typescript
+     * const result = await loader.executeWithImportsAsync(`
+     *   return await fetchData();
+     * `, {
+     *   fetchData: myFetchFunction
+     * }, { timeout: 5000 });
+     * ```
+     */
     async executeWithImportsAsync(code, imports, options = {}) {
         return this.execute(code, {
             ...options,
             imports: { ...this.config.defaultImports, ...imports }
         });
     }
+    /**
+     * Initialize the singleton instance of DynaJs
+     *
+     * @param config - Configuration options for the singleton instance
+     * @returns The initialized singleton instance
+     *
+     * @example
+     * ```typescript
+     * DynaJs.initialize({
+     *   defaultImports: { MyClass, MyFunction },
+     *   validateCode: true
+     * });
+     * ```
+     */
     static initialize(config) {
         if (DynaJs.instance == null) {
             DynaJs.instance = new DynaJs(config);
         }
         return DynaJs.instance;
     }
+    /**
+     * Get the singleton instance of DynaJs
+     *
+     * @returns The singleton instance
+     * @throws {Error} If DynaJs hasn't been initialized
+     *
+     * @example
+     * ```typescript
+     * const loader = DynaJs.getInstance();
+     * const result = loader.executeSync(`return 1 + 1`);
+     * ```
+     */
     static getInstance() {
         if (DynaJs.instance == null) {
             throw new Error("DynaJs hasn't been initialized. Call DynaJs.initialize() first.");
         }
         return DynaJs.instance;
     }
+    /**
+     * Reset the singleton instance (useful for testing)
+     *
+     * @example
+     * ```typescript
+     * DynaJs.reset();
+     * DynaJs.initialize(newConfig);
+     * ```
+     */
     static reset() {
         DynaJs.instance = null;
     }
+    /**
+     * Prepare the execution context by merging user context, imports, and applying security filters
+     *
+     * Execution flow:
+     * 1. Create safe context (filtering browser/node APIs based on config)
+     * 2. Merge with defaultImports and additional imports
+     * 3. Apply allowedGlobals whitelist filter if configured
+     *
+     * @private
+     * @param userContext - User-provided context variables
+     * @param imports - Additional imports for this execution
+     * @returns The final execution context
+     *
+     * @remarks
+     * If allowedGlobals is set and not empty, only variables in the whitelist will be available.
+     * This happens AFTER merging defaultImports, so make sure to include all needed imports
+     * in the allowedGlobals array if you use this feature.
+     */
     prepareContext(userContext = {}, imports = {}) {
         let context = createSafeContext(userContext, {
             allowBrowserAPIs: this.config.allowBrowserAPIs,
@@ -155,5 +340,9 @@ class DynaJs {
         return context;
     }
 }
+/**
+ * Singleton instance of DynaJs
+ * @private
+ */
 DynaJs.instance = null;
 export default DynaJs;

package/dist/DynaJs.js

@@ -1,7 +1,39 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const utils_1 = require("./utils");
+/**
+ * DynaJs - A safe dynamic code execution library
+ *
+ * Provides secure execution of dynamic JavaScript code using new Function()
+ * with configurable security policies and sandboxing capabilities.
+ *
+ * @example
+ * ```typescript
+ * const loader = new DynaJs({
+ *   defaultImports: { MyClass },
+ *   validateCode: true,
+ *   allowBrowserAPIs: false
+ * });
+ *
+ * const result = loader.executeSync(`return new MyClass()`);
+ * ```
+ */
 class DynaJs {
+    /**
+     * Creates a new DynaJs instance
+     *
+     * @param config - Configuration options for the DynaJs instance
+     * @param config.defaultTimeout - Default timeout for async execution in milliseconds (default: 5000)
+     * @param config.defaultStrict - Whether to use strict mode by default (default: true)
+     * @param config.allowedGlobals - Whitelist of allowed global variables (empty = allow all defaultImports)
+     * @param config.blockedGlobals - Blacklist of blocked global variables
+     * @param config.defaultImports - Pre-imported classes/functions available to dynamic code
+     * @param config.allowTimers - Allow setTimeout/setInterval in dynamic code (default: false)
+     * @param config.allowDynamicImports - Allow import()/require() in dynamic code (default: false)
+     * @param config.validateCode - Enable code validation before execution (default: true)
+     * @param config.allowBrowserAPIs - Allow access to browser APIs like window/document (default: false)
+     * @param config.allowNodeAPIs - Allow access to Node.js APIs like process/require (default: false)
+     */
     constructor(config = {}) {
         var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
         this.config = {
@@ -17,6 +49,18 @@ class DynaJs {
             allowNodeAPIs: (_k = config.allowNodeAPIs) !== null && _k !== void 0 ? _k : false
         };
     }
+    /**
+     * Asynchronously execute dynamic code with timeout support
+     *
+     * @template T - The expected return type of the executed code
+     * @param code - The JavaScript code to execute
+     * @param options - Execution options
+     * @param options.context - Additional context variables for the code
+     * @param options.timeout - Execution timeout in milliseconds (overrides defaultTimeout)
+     * @param options.strict - Whether to use strict mode (overrides defaultStrict)
+     * @param options.imports - Additional imports for this execution only
+     * @returns Promise resolving to the execution result
+     */
     async execute(code, options = {}) {
         var _a, _b;
         const startTime = performance.now();
@@ -31,17 +75,25 @@ class DynaJs {
             const timeout = (_a = options.timeout) !== null && _a !== void 0 ? _a : this.config.defaultTimeout;
             const strict = (_b = options.strict) !== null && _b !== void 0 ? _b : this.config.defaultStrict;
             const result = await this.executeWithTimeout(code, context, timeout, strict);
-            const executionTime = performance.now() - startTime;
-            return {
-                result: result,
-                executionTime
-            };
+            console.info(`Build dyna code in ${performance.now() - startTime}ms`);
+            return result;
         }
         catch (error) {
             const executionTime = performance.now() - startTime;
             throw new Error(`Script execution failed after ${executionTime.toFixed(2)}ms: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    /**
+     * Synchronously execute dynamic code and return result directly
+     *
+     * @template T - The expected return type of the executed code
+     * @param code - The JavaScript code to execute
+     * @param options - Execution options
+     * @param options.context - Additional context variables for the code
+     * @param options.strict - Whether to use strict mode (overrides defaultStrict)
+     * @param options.imports - Additional imports for this execution only
+     * @returns The direct result of code execution
+     */
     executeSync(code, options = {}) {
         var _a;
         const startTime = performance.now();
@@ -55,17 +107,26 @@ class DynaJs {
             const context = this.prepareContext(options.context, options.imports);
             const strict = (_a = options.strict) !== null && _a !== void 0 ? _a : this.config.defaultStrict;
             const result = this.executeCode(code, context, strict);
-            const executionTime = performance.now() - startTime;
-            return {
-                result: result,
-                executionTime
-            };
+            console.info(`Build dyna code in ${performance.now() - startTime}ms`);
+            return result;
         }
         catch (error) {
             const executionTime = performance.now() - startTime;
             throw new Error(`Script execution failed after ${executionTime.toFixed(2)}ms: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    /**
+     * Execute code with a timeout constraint
+     *
+     * @private
+     * @template T - The expected return type
+     * @param code - The JavaScript code to execute
+     * @param context - Execution context with available variables
+     * @param timeout - Maximum execution time in milliseconds
+     * @param strict - Whether to use strict mode
+     * @returns Promise resolving to the execution result
+     * @throws {Error} If execution exceeds timeout or runtime error occurs
+     */
     async executeWithTimeout(code, context, timeout, strict) {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
@@ -82,6 +143,16 @@ class DynaJs {
             }
         });
     }
+    /**
+     * Core code execution engine using new Function()
+     *
+     * @private
+     * @param code - The JavaScript code to execute
+     * @param context - Execution context with available variables
+     * @param strict - Whether to use strict mode
+     * @returns The execution result
+     * @throws {Error} If code execution fails
+     */
     executeCode(code, context, strict) {
         const contextKeys = Object.keys(context);
         const contextValues = Object.values(context);
@@ -95,6 +166,29 @@ class DynaJs {
             throw new Error(`Code execution error: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    /**
+     * Create a reusable function from dynamic code
+     *
+     * @template T - The function signature type
+     * @param code - The JavaScript code for the function body
+     * @param paramNames - Array of parameter names for the function
+     * @param options - Execution options
+     * @param options.context - Additional context variables
+     * @param options.strict - Whether to use strict mode
+     * @param options.imports - Additional imports
+     * @returns A function that can be called multiple times
+     * @throws {Error} If function creation fails
+     *
+     * @example
+     * ```typescript
+     * const validator = loader.createFunction<(data: any) => boolean>(`
+     *   return function(data) {
+     *     return data.name && data.email;
+     *   };
+     * `);
+     * const isValid = validator({ name: 'John', email: 'john@example.com' });
+     * ```
+     */
     createFunction(code, paramNames = [], options = {}) {
         var _a;
         const context = this.prepareContext(options.context, options.imports);
@@ -115,27 +209,118 @@ class DynaJs {
             throw new Error(`Function creation error: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    /**
+     * Synchronously execute code with additional temporary imports
+     *
+     * @template T - The expected return type
+     * @param code - The JavaScript code to execute
+     * @param imports - Additional imports to merge with defaultImports
+     * @param options - Additional execution options
+     * @returns The direct result of code execution
+     * @throws {Error} If code validation fails or runtime error occurs
+     *
+     * @example
+     * ```typescript
+     * const result = loader.executeWithImports(`
+     *   return new CustomComponent();
+     * `, {
+     *   CustomComponent: MyCustomComponent
+     * });
+     * ```
+     */
     executeWithImports(code, imports, options = {}) {
         return this.executeSync(code, Object.assign(Object.assign({}, options), { imports: Object.assign(Object.assign({}, this.config.defaultImports), imports) }));
     }
+    /**
+     * Asynchronously execute code with additional temporary imports
+     *
+     * @template T - The expected return type
+     * @param code - The JavaScript code to execute
+     * @param imports - Additional imports to merge with defaultImports
+     * @param options - Additional execution options (including timeout)
+     * @returns Promise resolving to the execution result
+     * @throws {Error} If code validation fails, execution times out, or runtime error occurs
+     *
+     * @example
+     * ```typescript
+     * const result = await loader.executeWithImportsAsync(`
+     *   return await fetchData();
+     * `, {
+     *   fetchData: myFetchFunction
+     * }, { timeout: 5000 });
+     * ```
+     */
     async executeWithImportsAsync(code, imports, options = {}) {
         return this.execute(code, Object.assign(Object.assign({}, options), { imports: Object.assign(Object.assign({}, this.config.defaultImports), imports) }));
     }
+    /**
+     * Initialize the singleton instance of DynaJs
+     *
+     * @param config - Configuration options for the singleton instance
+     * @returns The initialized singleton instance
+     *
+     * @example
+     * ```typescript
+     * DynaJs.initialize({
+     *   defaultImports: { MyClass, MyFunction },
+     *   validateCode: true
+     * });
+     * ```
+     */
     static initialize(config) {
         if (DynaJs.instance == null) {
             DynaJs.instance = new DynaJs(config);
         }
         return DynaJs.instance;
     }
+    /**
+     * Get the singleton instance of DynaJs
+     *
+     * @returns The singleton instance
+     * @throws {Error} If DynaJs hasn't been initialized
+     *
+     * @example
+     * ```typescript
+     * const loader = DynaJs.getInstance();
+     * const result = loader.executeSync(`return 1 + 1`);
+     * ```
+     */
     static getInstance() {
         if (DynaJs.instance == null) {
             throw new Error("DynaJs hasn't been initialized. Call DynaJs.initialize() first.");
         }
         return DynaJs.instance;
     }
+    /**
+     * Reset the singleton instance (useful for testing)
+     *
+     * @example
+     * ```typescript
+     * DynaJs.reset();
+     * DynaJs.initialize(newConfig);
+     * ```
+     */
     static reset() {
         DynaJs.instance = null;
     }
+    /**
+     * Prepare the execution context by merging user context, imports, and applying security filters
+     *
+     * Execution flow:
+     * 1. Create safe context (filtering browser/node APIs based on config)
+     * 2. Merge with defaultImports and additional imports
+     * 3. Apply allowedGlobals whitelist filter if configured
+     *
+     * @private
+     * @param userContext - User-provided context variables
+     * @param imports - Additional imports for this execution
+     * @returns The final execution context
+     *
+     * @remarks
+     * If allowedGlobals is set and not empty, only variables in the whitelist will be available.
+     * This happens AFTER merging defaultImports, so make sure to include all needed imports
+     * in the allowedGlobals array if you use this feature.
+     */
     prepareContext(userContext = {}, imports = {}) {
         let context = (0, utils_1.createSafeContext)(userContext, {
             allowBrowserAPIs: this.config.allowBrowserAPIs,
@@ -155,5 +340,9 @@ class DynaJs {
         return context;
     }
 }
+/**
+ * Singleton instance of DynaJs
+ * @private
+ */
 DynaJs.instance = null;
 exports.default = DynaJs;

package/dist/types.d.ts

@@ -9,12 +9,6 @@ export interface ExecutionOptions {
     timeout?: number;
     strict?: boolean;
     imports?: ModuleImports;
-    injectedKeys?: string[];
-    useProxy?: boolean;
-}
-export interface ExecutionResult<T = any> {
-    result: T;
-    executionTime: number;
 }
 export interface DynaJsConfig {
     defaultTimeout?: number;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,GAAG;IACtC,MAAM,EAAE,CAAC,CAAC;IACV,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ticatec/dyna-js",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "A TypeScript library for dynamic code execution using new Function() that works in both Node.js and browser environments",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",