@ticatec/dyna-js 0.0.2 → 0.0.4

package/dist/DynaJs.js

@@ -1,24 +1,66 @@
 "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, _l, _m;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
         this.config = {
             defaultTimeout: (_a = config.defaultTimeout) !== null && _a !== void 0 ? _a : 5000,
             defaultStrict: (_b = config.defaultStrict) !== null && _b !== void 0 ? _b : true,
             allowedGlobals: (_c = config.allowedGlobals) !== null && _c !== void 0 ? _c : [],
             blockedGlobals: (_d = config.blockedGlobals) !== null && _d !== void 0 ? _d : [],
             defaultImports: (_e = config.defaultImports) !== null && _e !== void 0 ? _e : {},
-            defaultInjectedKeys: (_f = config.defaultInjectedKeys) !== null && _f !== void 0 ? _f : [],
-            useProxyByDefault: (_g = config.useProxyByDefault) !== null && _g !== void 0 ? _g : true,
-            allowTimers: (_h = config.allowTimers) !== null && _h !== void 0 ? _h : false,
-            allowDynamicImports: (_j = config.allowDynamicImports) !== null && _j !== void 0 ? _j : false,
-            validateCode: (_k = config.validateCode) !== null && _k !== void 0 ? _k : true,
-            allowBrowserAPIs: (_l = config.allowBrowserAPIs) !== null && _l !== void 0 ? _l : false,
-            allowNodeAPIs: (_m = config.allowNodeAPIs) !== null && _m !== void 0 ? _m : false
+            allowTimers: (_f = config.allowTimers) !== null && _f !== void 0 ? _f : false,
+            allowDynamicImports: (_g = config.allowDynamicImports) !== null && _g !== void 0 ? _g : false,
+            validateCode: (_h = config.validateCode) !== null && _h !== void 0 ? _h : true,
+            allowBrowserAPIs: (_j = config.allowBrowserAPIs) !== null && _j !== void 0 ? _j : false,
+            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();
@@ -33,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();
@@ -57,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(() => {
@@ -84,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);
@@ -97,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);
@@ -117,79 +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) }));
     }
-    createFormClass(code, context = {}, injectedKeys = []) {
-        const useProxy = this.config.useProxyByDefault;
-        const mergedContext = Object.assign(Object.assign({}, context), this.config.defaultImports);
-        const mergedKeys = [...this.config.defaultInjectedKeys, ...injectedKeys];
-        if (useProxy) {
-            return this.executeWithProxy(code, mergedContext, mergedKeys);
-        }
-        else {
-            return this.executeSync(code, {
-                context: mergedContext,
-                imports: this.config.defaultImports
-            }).result;
-        }
-    }
-    executeWithProxy(code, context, injectedKeys) {
-        const injected = {};
-        for (const key of injectedKeys) {
-            if (context.window && key in context.window) {
-                injected[key] = context.window[key];
-            }
-            else if (key in context) {
-                injected[key] = context[key];
-            }
-        }
-        const sandboxContext = Object.assign(Object.assign({}, context), injected);
-        const sandbox = new Proxy(sandboxContext, {
-            has(target, key) {
-                if (key in target)
-                    return true;
-                if (context.window && key in context.window)
-                    return true;
-                return false;
-            },
-            get(target, key) {
-                if (key in target)
-                    return target[key];
-                if (context.window && key in context.window)
-                    return context.window[key];
-                console.warn(`DynaJs: ${String(key)} not found`);
-                return undefined;
-            }
-        });
-        const wrappedCode = `
-      with (sandbox) {
-        ${Object.keys(sandbox).map(k => `const ${k} = sandbox.${k};`).join('\n')}
-        
-        ${code}
-      }
-    `;
-        const fn = new Function('sandbox', wrappedCode);
-        return fn(sandbox);
-    }
+    /**
+     * 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,
@@ -209,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;
@@ -22,8 +16,6 @@ export interface DynaJsConfig {
     allowedGlobals?: string[];
     blockedGlobals?: string[];
     defaultImports?: ModuleImports;
-    defaultInjectedKeys?: string[];
-    useProxyByDefault?: boolean;
     allowTimers?: boolean;
     allowDynamicImports?: boolean;
     validateCode?: boolean;

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,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,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.2",
+  "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",