@ticatec/dyna-js 0.0.3 → 0.1.0

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;