@twin.org/modules 0.0.2-next.4 → 0.0.2-next.6

package/dist/cjs/index.cjs

@@ -14,6 +14,13 @@ class ModuleHelper {
      * Runtime name for the class.
      */
     static CLASS_NAME = "ModuleHelper";
+    /**
+     * Override the import function for modules.
+     * @param overrideImport The override import function.
+     */
+    static overrideImport(overrideImport) {
+        core.SharedStore.set("overrideImport", overrideImport);
+    }
     /**
      * Get the module entry.
      * @param module The module.
@@ -24,7 +31,16 @@ class ModuleHelper {
     static async getModuleEntry(module, entry) {
         let moduleInstance;
         try {
-            moduleInstance = await import(module);
+            let useDefault = true;
+            const overrideImport = core.SharedStore.get("overrideImport");
+            if (!core.Is.empty(overrideImport)) {
+                const overrideResult = await overrideImport(module);
+                moduleInstance = overrideResult.module;
+                useDefault = overrideResult.useDefault;
+            }
+            if (useDefault) {
+                moduleInstance = await import(module);
+            }
         }
         catch (err) {
             throw new core.GeneralError(ModuleHelper.CLASS_NAME, "moduleNotFound", {
@@ -32,7 +48,7 @@ class ModuleHelper {
                 entry
             }, core.BaseError.fromError(err));
         }
-        const moduleEntry = moduleInstance[entry];
+        const moduleEntry = moduleInstance?.[entry];
         if (core.Is.empty(moduleEntry)) {
             throw new core.GeneralError(ModuleHelper.CLASS_NAME, "entryNotFound", {
                 module,
@@ -95,8 +111,8 @@ class ModuleHelper {
 	try {
 		const { workerData, parentPort } = await import('node:worker_threads');
 
-		function rejectError(type, innerError) {
-			parentPort.postMessage({ errorType: type, innerError });
+		function rejectError(errorType, cause) {
+			parentPort.postMessage({ errorType, cause });
 		}
 
 		async function executeMethod(method) {
@@ -136,7 +152,7 @@ class ModuleHelper {
 			`, { eval: true, workerData: { module, method, args: args ?? [] } });
             worker.on("message", msg => {
                 if (core.Is.stringValue(msg.errorType)) {
-                    reject(new core.GeneralError(ModuleHelper.CLASS_NAME, msg.errorType, { module, entry: method }, msg.innerError));
+                    reject(new core.GeneralError(ModuleHelper.CLASS_NAME, msg.errorType, { module, entry: method }, msg.cause));
                 }
                 else {
                     resolve(msg.result);
@@ -159,6 +175,22 @@ class ModuleHelper {
             });
         });
     }
+    /**
+     * Check if a module is a local module.
+     * @param name The name of the module.
+     * @returns True if the module is local, false otherwise.
+     */
+    static isLocalModule(name) {
+        return name.startsWith(".") || name.startsWith("/");
+    }
+    /**
+     * Check if a module is a relative module.
+     * @param name The name of the module.
+     * @returns True if the module is relative, false otherwise.
+     */
+    static isRelativeModule(name) {
+        return name.startsWith(".");
+    }
 }
 
 exports.ModuleHelper = ModuleHelper;

package/dist/esm/index.mjs

@@ -1,5 +1,5 @@
 import { Worker } from 'node:worker_threads';
-import { GeneralError, BaseError, Is } from '@twin.org/core';
+import { SharedStore, Is, GeneralError, BaseError } from '@twin.org/core';
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
@@ -12,6 +12,13 @@ class ModuleHelper {
      * Runtime name for the class.
      */
     static CLASS_NAME = "ModuleHelper";
+    /**
+     * Override the import function for modules.
+     * @param overrideImport The override import function.
+     */
+    static overrideImport(overrideImport) {
+        SharedStore.set("overrideImport", overrideImport);
+    }
     /**
      * Get the module entry.
      * @param module The module.
@@ -22,7 +29,16 @@ class ModuleHelper {
     static async getModuleEntry(module, entry) {
         let moduleInstance;
         try {
-            moduleInstance = await import(module);
+            let useDefault = true;
+            const overrideImport = SharedStore.get("overrideImport");
+            if (!Is.empty(overrideImport)) {
+                const overrideResult = await overrideImport(module);
+                moduleInstance = overrideResult.module;
+                useDefault = overrideResult.useDefault;
+            }
+            if (useDefault) {
+                moduleInstance = await import(module);
+            }
         }
         catch (err) {
             throw new GeneralError(ModuleHelper.CLASS_NAME, "moduleNotFound", {
@@ -30,7 +46,7 @@ class ModuleHelper {
                 entry
             }, BaseError.fromError(err));
         }
-        const moduleEntry = moduleInstance[entry];
+        const moduleEntry = moduleInstance?.[entry];
         if (Is.empty(moduleEntry)) {
             throw new GeneralError(ModuleHelper.CLASS_NAME, "entryNotFound", {
                 module,
@@ -93,8 +109,8 @@ class ModuleHelper {
 	try {
 		const { workerData, parentPort } = await import('node:worker_threads');
 
-		function rejectError(type, innerError) {
-			parentPort.postMessage({ errorType: type, innerError });
+		function rejectError(errorType, cause) {
+			parentPort.postMessage({ errorType, cause });
 		}
 
 		async function executeMethod(method) {
@@ -134,7 +150,7 @@ class ModuleHelper {
 			`, { eval: true, workerData: { module, method, args: args ?? [] } });
             worker.on("message", msg => {
                 if (Is.stringValue(msg.errorType)) {
-                    reject(new GeneralError(ModuleHelper.CLASS_NAME, msg.errorType, { module, entry: method }, msg.innerError));
+                    reject(new GeneralError(ModuleHelper.CLASS_NAME, msg.errorType, { module, entry: method }, msg.cause));
                 }
                 else {
                     resolve(msg.result);
@@ -157,6 +173,22 @@ class ModuleHelper {
             });
         });
     }
+    /**
+     * Check if a module is a local module.
+     * @param name The name of the module.
+     * @returns True if the module is local, false otherwise.
+     */
+    static isLocalModule(name) {
+        return name.startsWith(".") || name.startsWith("/");
+    }
+    /**
+     * Check if a module is a relative module.
+     * @param name The name of the module.
+     * @returns True if the module is relative, false otherwise.
+     */
+    static isRelativeModule(name) {
+        return name.startsWith(".");
+    }
 }
 
 export { ModuleHelper };

package/dist/types/helpers/moduleHelper.d.ts

@@ -6,6 +6,14 @@ export declare class ModuleHelper {
      * Runtime name for the class.
      */
     static readonly CLASS_NAME: string;
+    /**
+     * Override the import function for modules.
+     * @param overrideImport The override import function.
+     */
+    static overrideImport(overrideImport: (moduleName: string) => Promise<{
+        module?: unknown;
+        useDefault: boolean;
+    }>): void;
     /**
      * Get the module entry.
      * @param module The module.
@@ -40,4 +48,16 @@ export declare class ModuleHelper {
      * @throws GeneralError if executing the module entry failed.
      */
     static execModuleMethodThread<T>(module: string, method: string, args?: unknown[]): Promise<T>;
+    /**
+     * Check if a module is a local module.
+     * @param name The name of the module.
+     * @returns True if the module is local, false otherwise.
+     */
+    static isLocalModule(name: string): boolean;
+    /**
+     * Check if a module is a relative module.
+     * @param name The name of the module.
+     * @returns True if the module is relative, false otherwise.
+     */
+    static isRelativeModule(name: string): boolean;
 }

package/docs/changelog.md

@@ -1,5 +1,41 @@
 # @twin.org/modules - Changelog
 
+## [0.0.2-next.6](https://github.com/twinfoundation/framework/compare/modules-v0.0.2-next.5...modules-v0.0.2-next.6) (2025-08-27)
+
+
+### Features
+
+* provide module helper override ([e998a64](https://github.com/twinfoundation/framework/commit/e998a64842cfd18693a14444be33b084fef2bb90))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.2-next.5 to 0.0.2-next.6
+    * @twin.org/nameof bumped from 0.0.2-next.5 to 0.0.2-next.6
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.2-next.5 to 0.0.2-next.6
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.2-next.5 to 0.0.2-next.6
+
+## [0.0.2-next.5](https://github.com/twinfoundation/framework/compare/modules-v0.0.2-next.4...modules-v0.0.2-next.5) (2025-08-19)
+
+
+### Features
+
+* use cause instead of inner for errors ([1f4acc4](https://github.com/twinfoundation/framework/commit/1f4acc4d7a6b71a134d9547da9bf40de1e1e49da))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.2-next.4 to 0.0.2-next.5
+    * @twin.org/nameof bumped from 0.0.2-next.4 to 0.0.2-next.5
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.2-next.4 to 0.0.2-next.5
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.2-next.4 to 0.0.2-next.5
+
 ## [0.0.2-next.4](https://github.com/twinfoundation/framework/compare/modules-v0.0.2-next.3...modules-v0.0.2-next.4) (2025-08-15)
 
 

package/docs/reference/classes/ModuleHelper.md

@@ -22,6 +22,26 @@ Runtime name for the class.
 
 ## Methods
 
+### overrideImport()
+
+> `static` **overrideImport**(`overrideImport`): `void`
+
+Override the import function for modules.
+
+#### Parameters
+
+##### overrideImport
+
+(`moduleName`) => `Promise`\<\{ `module?`: `unknown`; `useDefault`: `boolean`; \}\>
+
+The override import function.
+
+#### Returns
+
+`void`
+
+***
+
 ### getModuleEntry()
 
 > `static` **getModuleEntry**\<`T`\>(`module`, `entry`): `Promise`\<`T`\>
@@ -183,3 +203,47 @@ The result of the method execution.
 #### Throws
 
 GeneralError if executing the module entry failed.
+
+***
+
+### isLocalModule()
+
+> `static` **isLocalModule**(`name`): `boolean`
+
+Check if a module is a local module.
+
+#### Parameters
+
+##### name
+
+`string`
+
+The name of the module.
+
+#### Returns
+
+`boolean`
+
+True if the module is local, false otherwise.
+
+***
+
+### isRelativeModule()
+
+> `static` **isRelativeModule**(`name`): `boolean`
+
+Check if a module is a relative module.
+
+#### Parameters
+
+##### name
+
+`string`
+
+The name of the module.
+
+#### Returns
+
+`boolean`
+
+True if the module is relative, false otherwise.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/modules",
-	"version": "0.0.2-next.4",
+	"version": "0.0.2-next.6",
 	"description": "Helper classes for loading and executing from modules",
 	"repository": {
 		"type": "git",
@@ -14,8 +14,8 @@
 		"node": ">=20.0.0"
 	},
 	"dependencies": {
-		"@twin.org/core": "0.0.2-next.4",
-		"@twin.org/nameof": "0.0.2-next.4"
+		"@twin.org/core": "0.0.2-next.6",
+		"@twin.org/nameof": "0.0.2-next.6"
 	},
 	"main": "./dist/cjs/index.cjs",
 	"module": "./dist/esm/index.mjs",