@twin.org/modules 0.0.3-next.3 → 0.0.3-next.31

package/README.md

@@ -1,6 +1,6 @@
 # TWIN Framework Modules
 
-Helper classes for loading and executing from modules.
+This package is part of the framework workspace and provides helper classes for loading and executing from modules to support consistent development workflows across the ecosystem.
 
 ## Installation
 

package/dist/es/helpers/moduleHelper.js

@@ -70,7 +70,7 @@ export class ModuleHelper {
             }
             throw new GeneralError(ModuleHelper.CLASS_NAME, "notFunction", {
                 module,
-                entry: method
+                method
             });
         }
         const moduleEntry = await ModuleHelper.getModuleEntry(module, methodParts[0]);
@@ -79,7 +79,7 @@ export class ModuleHelper {
         }
         throw new GeneralError(ModuleHelper.CLASS_NAME, "notFunction", {
             module,
-            entry: method
+            method
         });
     }
     /**
@@ -99,78 +99,106 @@ export class ModuleHelper {
      * @param module The module.
      * @param method The method to execute from the module.
      * @param args The arguments to pass to the method.
+     * @param contextIds The context IDs.
      * @returns The result of the method execution.
      * @throws GeneralError if executing the module entry failed.
      */
-    static async execModuleMethodThread(module, method, args) {
+    static async execModuleMethodThread(module, method, args, contextIds) {
         return new Promise((resolve, reject) => {
-            const worker = new Worker(`(async () => {
-	try {
-		const { workerData, parentPort } = await import('node:worker_threads');
+            const messageModule = ModuleHelper.execModuleMethodThreadMessage(module, (resultMethod, result, err) => {
+                if (err) {
+                    reject(err);
+                }
+                else {
+                    resolve(result);
+                }
+            });
+            messageModule.executeMethod(method, args, contextIds);
+        });
+    }
+    /**
+     * Load the module and provide a messaging interface.
+     * @param module The module.
+     * @param completed Callback called when the worker thread processes a completion.
+     * @param options Optional settings.
+     * @param options.threadName The name of the thread.
+     * @returns The messaging interface.
+     * @throws GeneralError if executing the module entry failed.
+     */
+    static execModuleMethodThreadMessage(module, completed, options) {
+        const worker = new Worker(`(async () => {
+	const { workerData, parentPort } = await import('node:worker_threads');
+	const { ContextIdStore } = await import('@twin.org/context');
+	const { BaseError } = await import('@twin.org/core');
+	const { module } = workerData;
 
-		function rejectError(errorType, cause) {
-			parentPort.postMessage({ errorType, cause });
-		}
+	function rejectError(errorType, methodName, args, cause) {
+		parentPort.postMessage({ errorType, method: methodName, args, cause: BaseError.fromError(cause).toJsonObject(true) });
+	}
 
-		async function executeMethod(method) {
-			try {
+	async function executeMethod(method, methodName, args, contextIds) {
+		try {
+			await ContextIdStore.run(contextIds ?? {}, async () => {
 				const result = await method(...(args ?? []));
 
-				parentPort.postMessage({ result });
-			} catch (err) {
-				rejectError('resultError', err);
-			}
+				parentPort.postMessage({ method: methodName, result });
+			});
+		} catch (err) {
+			rejectError('resultError', methodName, args, err);
 		}
+	}
 
-		const { module, method, args } = workerData;
+	const modules = {};
 
-		const moduleInstance = await import(module);
-		const methodParts = method.split('.');
-		const moduleEntry = moduleInstance[methodParts[0]];
+	parentPort.on('message', async msg => {
+		const { method, args, contextIds } = msg;
 
-		if (moduleEntry === undefined) {
-			rejectError('entryNotFound');
-		} else if (methodParts.length === 2) {
-			const moduleMethod = moduleEntry[methodParts[1]];
-			if (typeof moduleMethod === 'function') {
-				await executeMethod(moduleMethod, args);
+		try {
+			const moduleInstance = modules[module] ?? (await import(module));
+			modules[module] = moduleInstance;
+
+			const methodParts = method.split('.');
+			const moduleEntry = moduleInstance[methodParts[0]];
+
+			if (moduleEntry === undefined) {
+				rejectError('entryNotFound', method, args);
+			} else if (methodParts.length === 2) {
+				const moduleMethod = moduleEntry[methodParts[1]];
+				if (typeof moduleMethod === 'function') {
+					await executeMethod(moduleMethod, method, args, contextIds);
+				} else {
+					rejectError('notFunction', method, args);
+				}
+			} else if (typeof moduleEntry === 'function') {
+				await executeMethod(moduleEntry, method, args, contextIds);
 			} else {
-				rejectError('notFunction');
+				rejectError('notFunction', method, args);
 			}
-		} else if (typeof moduleEntry === 'function') {
-			await executeMethod(moduleEntry, args);
-		} else {
-			rejectError('notFunction');
+		} catch (errInner) {
+				rejectError('moduleNotFound', method, args, errInner);
 		}
-	} catch (err) {
-		rejectError('moduleNotFound', err);
-	}
-})();
-			`, { 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.cause));
-                }
-                else {
-                    resolve(msg.result);
-                }
-            });
-            worker.on("error", err => {
-                reject(new GeneralError(ModuleHelper.CLASS_NAME, "workerException", {
-                    module,
-                    entry: method
-                }, err));
-            });
-            worker.on("exit", code => {
-                if (code === 1) {
-                    reject(new GeneralError(ModuleHelper.CLASS_NAME, "workerFailed", {
-                        module,
-                        entry: method,
-                        exitCode: code
-                    }));
-                }
-            });
+	});
+})();`, { eval: true, workerData: { module }, name: options?.threadName });
+        worker.on("message", msg => {
+            if (Is.stringValue(msg.errorType)) {
+                completed(msg.method, undefined, new GeneralError(ModuleHelper.CLASS_NAME, msg.errorType, { module, method: msg.method, args: msg.args }, msg.cause));
+            }
+            else {
+                completed(msg.method, msg.result);
+            }
+        });
+        worker.on("error", err => {
+            completed("error", undefined, new GeneralError(ModuleHelper.CLASS_NAME, "workerException", {
+                module
+            }, err));
+        });
+        worker.on("exit", code => {
+            completed("terminate", code);
         });
+        return {
+            executeMethod: (method, args, contextIds) => worker.postMessage({ method, args, contextIds }),
+            terminate: async () => worker.terminate()
+        };
     }
     /**
      * Check if a module is a local module.

package/dist/es/helpers/moduleHelper.js.map

@@ -1 +1 @@
-{"version":3,"file":"moduleHelper.js","sourceRoot":"","sources":["../../../src/helpers/moduleHelper.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Worker } from \"node:worker_threads\";\nimport { BaseError, GeneralError, Is, SharedStore } from \"@twin.org/core\";\nimport { nameof } from \"@twin.org/nameof\";\n\n/**\n * Helper functions for modules.\n */\nexport class ModuleHelper {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<ModuleHelper>();\n\n\t/**\n\t * Override the import function for modules.\n\t * @param overrideImport The override import function.\n\t */\n\tpublic static overrideImport(\n\t\toverrideImport: (moduleName: string) => Promise<{ module?: unknown; useDefault: boolean }>\n\t): void {\n\t\tSharedStore.set(\"overrideImport\", overrideImport);\n\t}\n\n\t/**\n\t * Get the module entry.\n\t * @param module The module.\n\t * @param entry The entry to get from the module.\n\t * @returns The entry from the module.\n\t * @throws GeneralError if getting the module entry failed.\n\t */\n\tpublic static async getModuleEntry<T>(module: string, entry: string): Promise<T> {\n\t\tlet moduleInstance;\n\n\t\ttry {\n\t\t\tlet useDefault = true;\n\n\t\t\tconst overrideImport =\n\t\t\t\tSharedStore.get<(moduleName: string) => Promise<{ module?: unknown; useDefault: boolean }>>(\n\t\t\t\t\t\"overrideImport\"\n\t\t\t\t);\n\n\t\t\tif (Is.function(overrideImport)) {\n\t\t\t\tconst overrideResult = await overrideImport(module);\n\n\t\t\t\tmoduleInstance = overrideResult.module;\n\t\t\t\tuseDefault = overrideResult.useDefault;\n\t\t\t}\n\n\t\t\tif (useDefault) {\n\t\t\t\tmoduleInstance = await import(module);\n\t\t\t}\n\t\t} catch (err) {\n\t\t\tthrow new GeneralError(\n\t\t\t\tModuleHelper.CLASS_NAME,\n\t\t\t\t\"moduleNotFound\",\n\t\t\t\t{\n\t\t\t\t\tmodule,\n\t\t\t\t\tentry\n\t\t\t\t},\n\t\t\t\tBaseError.fromError(err)\n\t\t\t);\n\t\t}\n\n\t\tconst moduleEntry = moduleInstance?.[entry];\n\n\t\tif (Is.empty(moduleEntry)) {\n\t\t\tthrow new GeneralError(ModuleHelper.CLASS_NAME, \"entryNotFound\", {\n\t\t\t\tmodule,\n\t\t\t\tentry\n\t\t\t});\n\t\t}\n\n\t\treturn moduleEntry as T;\n\t}\n\n\t/**\n\t * Get the method from a module.\n\t * @param module The module.\n\t * @param method The method to execute from the module, use dot notation to get a static class method.\n\t * @returns The result of the method execution.\n\t * @throws GeneralError if executing the module entry failed.\n\t */\n\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\tpublic static async getModuleMethod<T extends (...args: any[]) => any = (...args: any[]) => any>(\n\t\tmodule: string,\n\t\tmethod: string\n\t): Promise<T> {\n\t\tconst methodParts = method.split(\".\");\n\n\t\tif (methodParts.length === 2) {\n\t\t\tconst moduleEntry = await ModuleHelper.getModuleEntry<{\n\t\t\t\t[id: string]: T;\n\t\t\t}>(module, methodParts[0]);\n\n\t\t\tif (Is.function<T>(moduleEntry[methodParts[1]])) {\n\t\t\t\treturn moduleEntry[methodParts[1]];\n\t\t\t}\n\t\t\tthrow new GeneralError(ModuleHelper.CLASS_NAME, \"notFunction\", {\n\t\t\t\tmodule,\n\t\t\t\tentry: method\n\t\t\t});\n\t\t}\n\n\t\tconst moduleEntry = await ModuleHelper.getModuleEntry<T>(module, methodParts[0]);\n\n\t\tif (Is.function<T>(moduleEntry)) {\n\t\t\treturn moduleEntry;\n\t\t}\n\n\t\tthrow new GeneralError(ModuleHelper.CLASS_NAME, \"notFunction\", {\n\t\t\tmodule,\n\t\t\tentry: method\n\t\t});\n\t}\n\n\t/**\n\t * Execute the method in the module.\n\t * @param module The module.\n\t * @param method The method to execute from the module.\n\t * @param args The arguments to pass to the method.\n\t * @returns The result of the method execution.\n\t * @throws GeneralError if executing the module entry failed.\n\t */\n\tpublic static async execModuleMethod<T>(\n\t\tmodule: string,\n\t\tmethod: string,\n\t\targs?: unknown[]\n\t): Promise<T> {\n\t\tconst moduleMethod = await ModuleHelper.getModuleMethod<(...args: unknown[]) => T>(\n\t\t\tmodule,\n\t\t\tmethod\n\t\t);\n\n\t\treturn moduleMethod(...(args ?? []));\n\t}\n\n\t/**\n\t * Execute the method in the module in a thread.\n\t * @param module The module.\n\t * @param method The method to execute from the module.\n\t * @param args The arguments to pass to the method.\n\t * @returns The result of the method execution.\n\t * @throws GeneralError if executing the module entry failed.\n\t */\n\tpublic static async execModuleMethodThread<T>(\n\t\tmodule: string,\n\t\tmethod: string,\n\t\targs?: unknown[]\n\t): Promise<T> {\n\t\treturn new Promise((resolve, reject) => {\n\t\t\tconst worker = new Worker(\n\t\t\t\t`(async () => {\n\ttry {\n\t\tconst { workerData, parentPort } = await import('node:worker_threads');\n\n\t\tfunction rejectError(errorType, cause) {\n\t\t\tparentPort.postMessage({ errorType, cause });\n\t\t}\n\n\t\tasync function executeMethod(method) {\n\t\t\ttry {\n\t\t\t\tconst result = await method(...(args ?? []));\n\n\t\t\t\tparentPort.postMessage({ result });\n\t\t\t} catch (err) {\n\t\t\t\trejectError('resultError', err);\n\t\t\t}\n\t\t}\n\n\t\tconst { module, method, args } = workerData;\n\n\t\tconst moduleInstance = await import(module);\n\t\tconst methodParts = method.split('.');\n\t\tconst moduleEntry = moduleInstance[methodParts[0]];\n\n\t\tif (moduleEntry === undefined) {\n\t\t\trejectError('entryNotFound');\n\t\t} else if (methodParts.length === 2) {\n\t\t\tconst moduleMethod = moduleEntry[methodParts[1]];\n\t\t\tif (typeof moduleMethod === 'function') {\n\t\t\t\tawait executeMethod(moduleMethod, args);\n\t\t\t} else {\n\t\t\t\trejectError('notFunction');\n\t\t\t}\n\t\t} else if (typeof moduleEntry === 'function') {\n\t\t\tawait executeMethod(moduleEntry, args);\n\t\t} else {\n\t\t\trejectError('notFunction');\n\t\t}\n\t} catch (err) {\n\t\trejectError('moduleNotFound', err);\n\t}\n})();\n\t\t\t`,\n\t\t\t\t{ eval: true, workerData: { module, method, args: args ?? [] } }\n\t\t\t);\n\n\t\t\tworker.on(\"message\", msg => {\n\t\t\t\tif (Is.stringValue(msg.errorType)) {\n\t\t\t\t\treject(\n\t\t\t\t\t\tnew GeneralError(\n\t\t\t\t\t\t\tModuleHelper.CLASS_NAME,\n\t\t\t\t\t\t\tmsg.errorType,\n\t\t\t\t\t\t\t{ module, entry: method },\n\t\t\t\t\t\t\tmsg.cause\n\t\t\t\t\t\t)\n\t\t\t\t\t);\n\t\t\t\t} else {\n\t\t\t\t\tresolve(msg.result);\n\t\t\t\t}\n\t\t\t});\n\n\t\t\tworker.on(\"error\", err => {\n\t\t\t\treject(\n\t\t\t\t\tnew GeneralError(\n\t\t\t\t\t\tModuleHelper.CLASS_NAME,\n\t\t\t\t\t\t\"workerException\",\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tmodule,\n\t\t\t\t\t\t\tentry: method\n\t\t\t\t\t\t},\n\t\t\t\t\t\terr\n\t\t\t\t\t)\n\t\t\t\t);\n\t\t\t});\n\n\t\t\tworker.on(\"exit\", code => {\n\t\t\t\tif (code === 1) {\n\t\t\t\t\treject(\n\t\t\t\t\t\tnew GeneralError(ModuleHelper.CLASS_NAME, \"workerFailed\", {\n\t\t\t\t\t\t\tmodule,\n\t\t\t\t\t\t\tentry: method,\n\t\t\t\t\t\t\texitCode: code\n\t\t\t\t\t\t})\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t});\n\t\t});\n\t}\n\n\t/**\n\t * Check if a module is a local module.\n\t * @param name The name of the module.\n\t * @returns True if the module is local, false otherwise.\n\t */\n\tpublic static isLocalModule(name: string): boolean {\n\t\treturn name.startsWith(\".\") || name.startsWith(\"/\");\n\t}\n\n\t/**\n\t * Check if a module is a relative module.\n\t * @param name The name of the module.\n\t * @returns True if the module is relative, false otherwise.\n\t */\n\tpublic static isRelativeModule(name: string): boolean {\n\t\treturn name.startsWith(\".\");\n\t}\n}\n"]}
+{"version":3,"file":"moduleHelper.js","sourceRoot":"","sources":["../../../src/helpers/moduleHelper.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAI1E;;GAEG;AACH,MAAM,OAAO,YAAY;IACxB;;OAEG;IACI,MAAM,CAAU,UAAU,kBAAkC;IAEnE;;;OAGG;IACI,MAAM,CAAC,cAAc,CAC3B,cAA0F;QAE1F,WAAW,CAAC,GAAG,CAAC,gBAAgB,EAAE,cAAc,CAAC,CAAC;IACnD,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,KAAK,CAAC,cAAc,CAAI,MAAc,EAAE,KAAa;QAClE,IAAI,cAAc,CAAC;QAEnB,IAAI,CAAC;YACJ,IAAI,UAAU,GAAG,IAAI,CAAC;YAEtB,MAAM,cAAc,GACnB,WAAW,CAAC,GAAG,CACd,gBAAgB,CAChB,CAAC;YAEH,IAAI,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;gBACjC,MAAM,cAAc,GAAG,MAAM,cAAc,CAAC,MAAM,CAAC,CAAC;gBAEpD,cAAc,GAAG,cAAc,CAAC,MAAM,CAAC;gBACvC,UAAU,GAAG,cAAc,CAAC,UAAU,CAAC;YACxC,CAAC;YAED,IAAI,UAAU,EAAE,CAAC;gBAChB,cAAc,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;YACvC,CAAC;QACF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,MAAM,IAAI,YAAY,CACrB,YAAY,CAAC,UAAU,EACvB,gBAAgB,EAChB;gBACC,MAAM;gBACN,KAAK;aACL,EACD,SAAS,CAAC,SAAS,CAAC,GAAG,CAAC,CACxB,CAAC;QACH,CAAC;QAED,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC,KAAK,CAAC,CAAC;QAE5C,IAAI,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,YAAY,CAAC,YAAY,CAAC,UAAU,EAAE,eAAe,EAAE;gBAChE,MAAM;gBACN,KAAK;aACL,CAAC,CAAC;QACJ,CAAC;QAED,OAAO,WAAgB,CAAC;IACzB,CAAC;IAED;;;;;;OAMG;IACH,8DAA8D;IACvD,MAAM,CAAC,KAAK,CAAC,eAAe,CAClC,MAAc,EACd,MAAc;QAEd,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAEtC,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9B,MAAM,WAAW,GAAG,MAAM,YAAY,CAAC,cAAc,CAElD,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;YAE3B,IAAI,EAAE,CAAC,QAAQ,CAAI,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBACjD,OAAO,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;YACpC,CAAC;YACD,MAAM,IAAI,YAAY,CAAC,YAAY,CAAC,UAAU,EAAE,aAAa,EAAE;gBAC9D,MAAM;gBACN,MAAM;aACN,CAAC,CAAC;QACJ,CAAC;QAED,MAAM,WAAW,GAAG,MAAM,YAAY,CAAC,cAAc,CAAI,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;QAEjF,IAAI,EAAE,CAAC,QAAQ,CAAI,WAAW,CAAC,EAAE,CAAC;YACjC,OAAO,WAAW,CAAC;QACpB,CAAC;QAED,MAAM,IAAI,YAAY,CAAC,YAAY,CAAC,UAAU,EAAE,aAAa,EAAE;YAC9D,MAAM;YACN,MAAM;SACN,CAAC,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACI,MAAM,CAAC,KAAK,CAAC,gBAAgB,CACnC,MAAc,EACd,MAAc,EACd,IAAgB;QAEhB,MAAM,YAAY,GAAG,MAAM,YAAY,CAAC,eAAe,CACtD,MAAM,EACN,MAAM,CACN,CAAC;QAEF,OAAO,YAAY,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;IACtC,CAAC;IAED;;;;;;;;OAQG;IACI,MAAM,CAAC,KAAK,CAAC,sBAAsB,CACzC,MAAc,EACd,MAAc,EACd,IAAgB,EAChB,UAAwB;QAExB,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACzC,MAAM,aAAa,GAAG,YAAY,CAAC,6BAA6B,CAC/D,MAAM,EACN,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE;gBAC7B,IAAI,GAAG,EAAE,CAAC;oBACT,MAAM,CAAC,GAAG,CAAC,CAAC;gBACb,CAAC;qBAAM,CAAC;oBACP,OAAO,CAAC,MAAW,CAAC,CAAC;gBACtB,CAAC;YACF,CAAC,CACD,CAAC;YAEF,aAAa,CAAC,aAAa,CAAC,MAAM,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;QACvD,CAAC,CAAC,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACI,MAAM,CAAC,6BAA6B,CAC1C,MAAc,EACd,SAAqE,EACrE,OAEC;QAED,MAAM,MAAM,GAAG,IAAI,MAAM,CACxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAoDG,EACH,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,CACjE,CAAC;QAEF,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,CAAC,EAAE;YAC1B,IAAI,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;gBACnC,SAAS,CACR,GAAG,CAAC,MAAM,EACV,SAAS,EACT,IAAI,YAAY,CACf,YAAY,CAAC,UAAU,EACvB,GAAG,CAAC,SAAS,EACb,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,EAC9C,GAAG,CAAC,KAAK,CACT,CACD,CAAC;YACH,CAAC;iBAAM,CAAC;gBACP,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;YACnC,CAAC;QACF,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE;YACxB,SAAS,CACR,OAAO,EACP,SAAS,EACT,IAAI,YAAY,CACf,YAAY,CAAC,UAAU,EACvB,iBAAiB,EACjB;gBACC,MAAM;aACN,EACD,GAAG,CACH,CACD,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE;YACxB,SAAS,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QAC9B,CAAC,CAAC,CAAC;QAEH,OAAO;YACN,aAAa,EAAE,CAAC,MAAc,EAAE,IAAc,EAAE,UAAwB,EAAE,EAAE,CAC3E,MAAM,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;YACjD,SAAS,EAAE,KAAK,IAAI,EAAE,CAAC,MAAM,CAAC,SAAS,EAAE;SACzC,CAAC;IACH,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,aAAa,CAAC,IAAY;QACvC,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACrD,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,gBAAgB,CAAC,IAAY;QAC1C,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Worker } from \"node:worker_threads\";\nimport type { IContextIds } from \"@twin.org/context\";\nimport { BaseError, GeneralError, Is, SharedStore } from \"@twin.org/core\";\nimport { nameof } from \"@twin.org/nameof\";\nimport type { IModuleWorker } from \"../models/IModuleWorker.js\";\n\n/**\n * Helper functions for modules.\n */\nexport class ModuleHelper {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<ModuleHelper>();\n\n\t/**\n\t * Override the import function for modules.\n\t * @param overrideImport The override import function.\n\t */\n\tpublic static overrideImport(\n\t\toverrideImport: (moduleName: string) => Promise<{ module?: unknown; useDefault: boolean }>\n\t): void {\n\t\tSharedStore.set(\"overrideImport\", overrideImport);\n\t}\n\n\t/**\n\t * Get the module entry.\n\t * @param module The module.\n\t * @param entry The entry to get from the module.\n\t * @returns The entry from the module.\n\t * @throws GeneralError if getting the module entry failed.\n\t */\n\tpublic static async getModuleEntry<T>(module: string, entry: string): Promise<T> {\n\t\tlet moduleInstance;\n\n\t\ttry {\n\t\t\tlet useDefault = true;\n\n\t\t\tconst overrideImport =\n\t\t\t\tSharedStore.get<(moduleName: string) => Promise<{ module?: unknown; useDefault: boolean }>>(\n\t\t\t\t\t\"overrideImport\"\n\t\t\t\t);\n\n\t\t\tif (Is.function(overrideImport)) {\n\t\t\t\tconst overrideResult = await overrideImport(module);\n\n\t\t\t\tmoduleInstance = overrideResult.module;\n\t\t\t\tuseDefault = overrideResult.useDefault;\n\t\t\t}\n\n\t\t\tif (useDefault) {\n\t\t\t\tmoduleInstance = await import(module);\n\t\t\t}\n\t\t} catch (err) {\n\t\t\tthrow new GeneralError(\n\t\t\t\tModuleHelper.CLASS_NAME,\n\t\t\t\t\"moduleNotFound\",\n\t\t\t\t{\n\t\t\t\t\tmodule,\n\t\t\t\t\tentry\n\t\t\t\t},\n\t\t\t\tBaseError.fromError(err)\n\t\t\t);\n\t\t}\n\n\t\tconst moduleEntry = moduleInstance?.[entry];\n\n\t\tif (Is.empty(moduleEntry)) {\n\t\t\tthrow new GeneralError(ModuleHelper.CLASS_NAME, \"entryNotFound\", {\n\t\t\t\tmodule,\n\t\t\t\tentry\n\t\t\t});\n\t\t}\n\n\t\treturn moduleEntry as T;\n\t}\n\n\t/**\n\t * Get the method from a module.\n\t * @param module The module.\n\t * @param method The method to execute from the module, use dot notation to get a static class method.\n\t * @returns The result of the method execution.\n\t * @throws GeneralError if executing the module entry failed.\n\t */\n\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\tpublic static async getModuleMethod<T extends (...args: any[]) => any = (...args: any[]) => any>(\n\t\tmodule: string,\n\t\tmethod: string\n\t): Promise<T> {\n\t\tconst methodParts = method.split(\".\");\n\n\t\tif (methodParts.length === 2) {\n\t\t\tconst moduleEntry = await ModuleHelper.getModuleEntry<{\n\t\t\t\t[id: string]: T;\n\t\t\t}>(module, methodParts[0]);\n\n\t\t\tif (Is.function<T>(moduleEntry[methodParts[1]])) {\n\t\t\t\treturn moduleEntry[methodParts[1]];\n\t\t\t}\n\t\t\tthrow new GeneralError(ModuleHelper.CLASS_NAME, \"notFunction\", {\n\t\t\t\tmodule,\n\t\t\t\tmethod\n\t\t\t});\n\t\t}\n\n\t\tconst moduleEntry = await ModuleHelper.getModuleEntry<T>(module, methodParts[0]);\n\n\t\tif (Is.function<T>(moduleEntry)) {\n\t\t\treturn moduleEntry;\n\t\t}\n\n\t\tthrow new GeneralError(ModuleHelper.CLASS_NAME, \"notFunction\", {\n\t\t\tmodule,\n\t\t\tmethod\n\t\t});\n\t}\n\n\t/**\n\t * Execute the method in the module.\n\t * @param module The module.\n\t * @param method The method to execute from the module.\n\t * @param args The arguments to pass to the method.\n\t * @returns The result of the method execution.\n\t * @throws GeneralError if executing the module entry failed.\n\t */\n\tpublic static async execModuleMethod<T>(\n\t\tmodule: string,\n\t\tmethod: string,\n\t\targs?: unknown[]\n\t): Promise<T> {\n\t\tconst moduleMethod = await ModuleHelper.getModuleMethod<(...args: unknown[]) => T>(\n\t\t\tmodule,\n\t\t\tmethod\n\t\t);\n\n\t\treturn moduleMethod(...(args ?? []));\n\t}\n\n\t/**\n\t * Execute the method in the module in a thread.\n\t * @param module The module.\n\t * @param method The method to execute from the module.\n\t * @param args The arguments to pass to the method.\n\t * @param contextIds The context IDs.\n\t * @returns The result of the method execution.\n\t * @throws GeneralError if executing the module entry failed.\n\t */\n\tpublic static async execModuleMethodThread<T>(\n\t\tmodule: string,\n\t\tmethod: string,\n\t\targs?: unknown[],\n\t\tcontextIds?: IContextIds\n\t): Promise<T> {\n\t\treturn new Promise<T>((resolve, reject) => {\n\t\t\tconst messageModule = ModuleHelper.execModuleMethodThreadMessage(\n\t\t\t\tmodule,\n\t\t\t\t(resultMethod, result, err) => {\n\t\t\t\t\tif (err) {\n\t\t\t\t\t\treject(err);\n\t\t\t\t\t} else {\n\t\t\t\t\t\tresolve(result as T);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t);\n\n\t\t\tmessageModule.executeMethod(method, args, contextIds);\n\t\t});\n\t}\n\n\t/**\n\t * Load the module and provide a messaging interface.\n\t * @param module The module.\n\t * @param completed Callback called when the worker thread processes a completion.\n\t * @param options Optional settings.\n\t * @param options.threadName The name of the thread.\n\t * @returns The messaging interface.\n\t * @throws GeneralError if executing the module entry failed.\n\t */\n\tpublic static execModuleMethodThreadMessage(\n\t\tmodule: string,\n\t\tcompleted: (operation: string, result?: unknown, err?: Error) => void,\n\t\toptions?: {\n\t\t\tthreadName?: string;\n\t\t}\n\t): IModuleWorker {\n\t\tconst worker = new Worker(\n\t\t\t`(async () => {\n\tconst { workerData, parentPort } = await import('node:worker_threads');\n\tconst { ContextIdStore } = await import('@twin.org/context');\n\tconst { BaseError } = await import('@twin.org/core');\n\tconst { module } = workerData;\n\n\tfunction rejectError(errorType, methodName, args, cause) {\n\t\tparentPort.postMessage({ errorType, method: methodName, args, cause: BaseError.fromError(cause).toJsonObject(true) });\n\t}\n\n\tasync function executeMethod(method, methodName, args, contextIds) {\n\t\ttry {\n\t\t\tawait ContextIdStore.run(contextIds ?? {}, async () => {\n\t\t\t\tconst result = await method(...(args ?? []));\n\n\t\t\t\tparentPort.postMessage({ method: methodName, result });\n\t\t\t});\n\t\t} catch (err) {\n\t\t\trejectError('resultError', methodName, args, err);\n\t\t}\n\t}\n\n\tconst modules = {};\n\n\tparentPort.on('message', async msg => {\n\t\tconst { method, args, contextIds } = msg;\n\n\t\ttry {\n\t\t\tconst moduleInstance = modules[module] ?? (await import(module));\n\t\t\tmodules[module] = moduleInstance;\n\n\t\t\tconst methodParts = method.split('.');\n\t\t\tconst moduleEntry = moduleInstance[methodParts[0]];\n\n\t\t\tif (moduleEntry === undefined) {\n\t\t\t\trejectError('entryNotFound', method, args);\n\t\t\t} else if (methodParts.length === 2) {\n\t\t\t\tconst moduleMethod = moduleEntry[methodParts[1]];\n\t\t\t\tif (typeof moduleMethod === 'function') {\n\t\t\t\t\tawait executeMethod(moduleMethod, method, args, contextIds);\n\t\t\t\t} else {\n\t\t\t\t\trejectError('notFunction', method, args);\n\t\t\t\t}\n\t\t\t} else if (typeof moduleEntry === 'function') {\n\t\t\t\tawait executeMethod(moduleEntry, method, args, contextIds);\n\t\t\t} else {\n\t\t\t\trejectError('notFunction', method, args);\n\t\t\t}\n\t\t} catch (errInner) {\n\t\t\t\trejectError('moduleNotFound', method, args, errInner);\n\t\t}\n\t});\n})();`,\n\t\t\t{ eval: true, workerData: { module }, name: options?.threadName }\n\t\t);\n\n\t\tworker.on(\"message\", msg => {\n\t\t\tif (Is.stringValue(msg.errorType)) {\n\t\t\t\tcompleted(\n\t\t\t\t\tmsg.method,\n\t\t\t\t\tundefined,\n\t\t\t\t\tnew GeneralError(\n\t\t\t\t\t\tModuleHelper.CLASS_NAME,\n\t\t\t\t\t\tmsg.errorType,\n\t\t\t\t\t\t{ module, method: msg.method, args: msg.args },\n\t\t\t\t\t\tmsg.cause\n\t\t\t\t\t)\n\t\t\t\t);\n\t\t\t} else {\n\t\t\t\tcompleted(msg.method, msg.result);\n\t\t\t}\n\t\t});\n\n\t\tworker.on(\"error\", err => {\n\t\t\tcompleted(\n\t\t\t\t\"error\",\n\t\t\t\tundefined,\n\t\t\t\tnew GeneralError(\n\t\t\t\t\tModuleHelper.CLASS_NAME,\n\t\t\t\t\t\"workerException\",\n\t\t\t\t\t{\n\t\t\t\t\t\tmodule\n\t\t\t\t\t},\n\t\t\t\t\terr\n\t\t\t\t)\n\t\t\t);\n\t\t});\n\n\t\tworker.on(\"exit\", code => {\n\t\t\tcompleted(\"terminate\", code);\n\t\t});\n\n\t\treturn {\n\t\t\texecuteMethod: (method: string, args?: unknown, contextIds?: IContextIds) =>\n\t\t\t\tworker.postMessage({ method, args, contextIds }),\n\t\t\tterminate: async () => worker.terminate()\n\t\t};\n\t}\n\n\t/**\n\t * Check if a module is a local module.\n\t * @param name The name of the module.\n\t * @returns True if the module is local, false otherwise.\n\t */\n\tpublic static isLocalModule(name: string): boolean {\n\t\treturn name.startsWith(\".\") || name.startsWith(\"/\");\n\t}\n\n\t/**\n\t * Check if a module is a relative module.\n\t * @param name The name of the module.\n\t * @returns True if the module is relative, false otherwise.\n\t */\n\tpublic static isRelativeModule(name: string): boolean {\n\t\treturn name.startsWith(\".\");\n\t}\n}\n"]}

package/dist/es/index.js

@@ -1,4 +1,5 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
 export * from "./helpers/moduleHelper.js";
+export * from "./models/IModuleWorker.js";
 //# sourceMappingURL=index.js.map

package/dist/es/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,2BAA2B,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./helpers/moduleHelper.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./helpers/moduleHelper.js\";\nexport * from \"./models/IModuleWorker.js\";\n"]}

package/dist/es/models/IModuleWorker.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IModuleWorker.js.map

package/dist/es/models/IModuleWorker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IModuleWorker.js","sourceRoot":"","sources":["../../../src/models/IModuleWorker.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IContextIds } from \"@twin.org/context\";\n\n/**\n * Worker definition for modules.\n */\nexport interface IModuleWorker {\n\t/**\n\t * Execute a method in the module.\n\t * @param method The method to execute.\n\t * @param args The arguments for the method.\n\t * @param contextIds The context IDs.\n\t * @returns The result of the method.\n\t */\n\texecuteMethod(method: string, args?: unknown, contextIds?: IContextIds): void;\n\n\t/**\n\t * Terminate the worker.\n\t * @returns A promise that resolves when the worker is terminated including the exit code.\n\t */\n\tterminate(): Promise<number>;\n}\n"]}

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

@@ -1,3 +1,5 @@
+import type { IContextIds } from "@twin.org/context";
+import type { IModuleWorker } from "../models/IModuleWorker.js";
 /**
  * Helper functions for modules.
  */
@@ -44,10 +46,23 @@ export declare class ModuleHelper {
      * @param module The module.
      * @param method The method to execute from the module.
      * @param args The arguments to pass to the method.
+     * @param contextIds The context IDs.
      * @returns The result of the method execution.
      * @throws GeneralError if executing the module entry failed.
      */
-    static execModuleMethodThread<T>(module: string, method: string, args?: unknown[]): Promise<T>;
+    static execModuleMethodThread<T>(module: string, method: string, args?: unknown[], contextIds?: IContextIds): Promise<T>;
+    /**
+     * Load the module and provide a messaging interface.
+     * @param module The module.
+     * @param completed Callback called when the worker thread processes a completion.
+     * @param options Optional settings.
+     * @param options.threadName The name of the thread.
+     * @returns The messaging interface.
+     * @throws GeneralError if executing the module entry failed.
+     */
+    static execModuleMethodThreadMessage(module: string, completed: (operation: string, result?: unknown, err?: Error) => void, options?: {
+        threadName?: string;
+    }): IModuleWorker;
     /**
      * Check if a module is a local module.
      * @param name The name of the module.

package/dist/types/index.d.ts

@@ -1 +1,2 @@
 export * from "./helpers/moduleHelper.js";
+export * from "./models/IModuleWorker.js";

package/dist/types/models/IModuleWorker.d.ts

@@ -0,0 +1,19 @@
+import type { IContextIds } from "@twin.org/context";
+/**
+ * Worker definition for modules.
+ */
+export interface IModuleWorker {
+    /**
+     * Execute a method in the module.
+     * @param method The method to execute.
+     * @param args The arguments for the method.
+     * @param contextIds The context IDs.
+     * @returns The result of the method.
+     */
+    executeMethod(method: string, args?: unknown, contextIds?: IContextIds): void;
+    /**
+     * Terminate the worker.
+     * @returns A promise that resolves when the worker is terminated including the exit code.
+     */
+    terminate(): Promise<number>;
+}

package/docs/changelog.md

@@ -1,4 +1,587 @@
-# @twin.org/modules - Changelog
+# Changelog
+
+## [0.0.3-next.31](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.30...modules-v0.0.3-next.31) (2026-04-14)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.30 to 0.0.3-next.31
+    * @twin.org/context bumped from 0.0.3-next.30 to 0.0.3-next.31
+    * @twin.org/nameof bumped from 0.0.3-next.30 to 0.0.3-next.31
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.30 to 0.0.3-next.31
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.30 to 0.0.3-next.31
+    * @twin.org/validate-locales bumped from 0.0.3-next.30 to 0.0.3-next.31
+
+## [0.0.3-next.30](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.29...modules-v0.0.3-next.30) (2026-04-14)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.29 to 0.0.3-next.30
+    * @twin.org/context bumped from 0.0.3-next.29 to 0.0.3-next.30
+    * @twin.org/nameof bumped from 0.0.3-next.29 to 0.0.3-next.30
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.29 to 0.0.3-next.30
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.29 to 0.0.3-next.30
+    * @twin.org/validate-locales bumped from 0.0.3-next.29 to 0.0.3-next.30
+
+## [0.0.3-next.29](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.28...modules-v0.0.3-next.29) (2026-04-14)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.28 to 0.0.3-next.29
+    * @twin.org/context bumped from 0.0.3-next.28 to 0.0.3-next.29
+    * @twin.org/nameof bumped from 0.0.3-next.28 to 0.0.3-next.29
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.28 to 0.0.3-next.29
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.28 to 0.0.3-next.29
+    * @twin.org/validate-locales bumped from 0.0.3-next.28 to 0.0.3-next.29
+
+## [0.0.3-next.28](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.27...modules-v0.0.3-next.28) (2026-03-27)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.27 to 0.0.3-next.28
+    * @twin.org/context bumped from 0.0.3-next.27 to 0.0.3-next.28
+    * @twin.org/nameof bumped from 0.0.3-next.27 to 0.0.3-next.28
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.27 to 0.0.3-next.28
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.27 to 0.0.3-next.28
+    * @twin.org/validate-locales bumped from 0.0.3-next.27 to 0.0.3-next.28
+
+## [0.0.3-next.27](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.26...modules-v0.0.3-next.27) (2026-03-27)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.26 to 0.0.3-next.27
+    * @twin.org/context bumped from 0.0.3-next.26 to 0.0.3-next.27
+    * @twin.org/nameof bumped from 0.0.3-next.26 to 0.0.3-next.27
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.26 to 0.0.3-next.27
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.26 to 0.0.3-next.27
+    * @twin.org/validate-locales bumped from 0.0.3-next.26 to 0.0.3-next.27
+
+## [0.0.3-next.26](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.25...modules-v0.0.3-next.26) (2026-03-24)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.25 to 0.0.3-next.26
+    * @twin.org/context bumped from 0.0.3-next.25 to 0.0.3-next.26
+    * @twin.org/nameof bumped from 0.0.3-next.25 to 0.0.3-next.26
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.25 to 0.0.3-next.26
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.25 to 0.0.3-next.26
+    * @twin.org/validate-locales bumped from 0.0.3-next.25 to 0.0.3-next.26
+
+## [0.0.3-next.25](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.24...modules-v0.0.3-next.25) (2026-03-23)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.24 to 0.0.3-next.25
+    * @twin.org/context bumped from 0.0.3-next.24 to 0.0.3-next.25
+    * @twin.org/nameof bumped from 0.0.3-next.24 to 0.0.3-next.25
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.24 to 0.0.3-next.25
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.24 to 0.0.3-next.25
+    * @twin.org/validate-locales bumped from 0.0.3-next.24 to 0.0.3-next.25
+
+## [0.0.3-next.24](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.23...modules-v0.0.3-next.24) (2026-03-19)
+
+
+### Bug Fixes
+
+* ensure __decorate is defined for decorators ([103a563](https://github.com/twinfoundation/framework/commit/103a563ce01ebdef6240d2e590e7b026e8692684))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.23 to 0.0.3-next.24
+    * @twin.org/context bumped from 0.0.3-next.23 to 0.0.3-next.24
+    * @twin.org/nameof bumped from 0.0.3-next.23 to 0.0.3-next.24
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.23 to 0.0.3-next.24
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.23 to 0.0.3-next.24
+    * @twin.org/validate-locales bumped from 0.0.3-next.23 to 0.0.3-next.24
+
+## [0.0.3-next.23](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.22...modules-v0.0.3-next.23) (2026-03-17)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.22 to 0.0.3-next.23
+    * @twin.org/context bumped from 0.0.3-next.22 to 0.0.3-next.23
+    * @twin.org/nameof bumped from 0.0.3-next.22 to 0.0.3-next.23
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.22 to 0.0.3-next.23
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.22 to 0.0.3-next.23
+    * @twin.org/validate-locales bumped from 0.0.3-next.22 to 0.0.3-next.23
+
+## [0.0.3-next.22](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.21...modules-v0.0.3-next.22) (2026-02-26)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.21 to 0.0.3-next.22
+    * @twin.org/context bumped from 0.0.3-next.21 to 0.0.3-next.22
+    * @twin.org/nameof bumped from 0.0.3-next.21 to 0.0.3-next.22
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.21 to 0.0.3-next.22
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.21 to 0.0.3-next.22
+    * @twin.org/validate-locales bumped from 0.0.3-next.21 to 0.0.3-next.22
+
+## [0.0.3-next.21](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.20...modules-v0.0.3-next.21) (2026-02-26)
+
+
+### Features
+
+* add context id features ([#206](https://github.com/twinfoundation/framework/issues/206)) ([ef0d4ee](https://github.com/twinfoundation/framework/commit/ef0d4ee11a4f5fc6cc6f52a4958ce905c04ee13b))
+* add guards arrayEndsWith and arrayStartsWith ([95d875e](https://github.com/twinfoundation/framework/commit/95d875ec8ccb4713c145fdde941d4cfedcec2ed3))
+* eslint migration to flat config ([74427d7](https://github.com/twinfoundation/framework/commit/74427d78d342167f7850e49ab87269326355befe))
+* improve async pattern and error handling ([aaa1f68](https://github.com/twinfoundation/framework/commit/aaa1f6879d60adf04b78b0c1bbbec50f2873f020))
+* improve Is.function and ModuleHelper.getModuleMethod signatures ([ecf968b](https://github.com/twinfoundation/framework/commit/ecf968b02934b3676be4bf7cd2d1e7f8e7af6ce2))
+* locales validation ([#197](https://github.com/twinfoundation/framework/issues/197)) ([55fdadb](https://github.com/twinfoundation/framework/commit/55fdadb13595ce0047f787bd1d4135d429a99f12))
+* module helper can now handle long running threads with messaging ([4ecbb9a](https://github.com/twinfoundation/framework/commit/4ecbb9a526927d462d4fb3f95ba2a44889202753))
+* nodeIdentity optional in IComponent methods ([c78dc17](https://github.com/twinfoundation/framework/commit/c78dc17f4357d3e1ae40e415f468d3eae13e81f4))
+* provide module helper override ([e998a64](https://github.com/twinfoundation/framework/commit/e998a64842cfd18693a14444be33b084fef2bb90))
+* relocate core packages from tools ([bcab8f3](https://github.com/twinfoundation/framework/commit/bcab8f3160442ea4fcaf442947462504f3d6a17d))
+* retain detail in Errors from background threads ([52bdeef](https://github.com/twinfoundation/framework/commit/52bdeef7a75fd462ed118073b9dc7612304e038d))
+* update dependencies ([f3bd015](https://github.com/twinfoundation/framework/commit/f3bd015efd169196b7e0335f5cab876ba6ca1d75))
+* use cause instead of inner for errors ([1f4acc4](https://github.com/twinfoundation/framework/commit/1f4acc4d7a6b71a134d9547da9bf40de1e1e49da))
+* use new shared store mechanism ([#131](https://github.com/twinfoundation/framework/issues/131)) ([934385b](https://github.com/twinfoundation/framework/commit/934385b2fbaf9f5c00a505ebf9d093bd5a425f55))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.20 to 0.0.3-next.21
+    * @twin.org/context bumped from 0.0.3-next.20 to 0.0.3-next.21
+    * @twin.org/nameof bumped from 0.0.3-next.20 to 0.0.3-next.21
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.20 to 0.0.3-next.21
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.20 to 0.0.3-next.21
+    * @twin.org/validate-locales bumped from 0.0.3-next.20 to 0.0.3-next.21
+
+## [0.0.3-next.20](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.19...modules-v0.0.3-next.20) (2026-02-26)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.19 to 0.0.3-next.20
+    * @twin.org/context bumped from 0.0.3-next.19 to 0.0.3-next.20
+    * @twin.org/nameof bumped from 0.0.3-next.19 to 0.0.3-next.20
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.19 to 0.0.3-next.20
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.19 to 0.0.3-next.20
+    * @twin.org/validate-locales bumped from 0.0.3-next.19 to 0.0.3-next.20
+
+## [0.0.3-next.19](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.18...modules-v0.0.3-next.19) (2026-02-26)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.18 to 0.0.3-next.19
+    * @twin.org/context bumped from 0.0.3-next.18 to 0.0.3-next.19
+    * @twin.org/nameof bumped from 0.0.3-next.18 to 0.0.3-next.19
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.18 to 0.0.3-next.19
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.18 to 0.0.3-next.19
+    * @twin.org/validate-locales bumped from 0.0.3-next.18 to 0.0.3-next.19
+
+## [0.0.3-next.18](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.17...modules-v0.0.3-next.18) (2026-02-23)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.17 to 0.0.3-next.18
+    * @twin.org/context bumped from 0.0.3-next.17 to 0.0.3-next.18
+    * @twin.org/nameof bumped from 0.0.3-next.17 to 0.0.3-next.18
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.17 to 0.0.3-next.18
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.17 to 0.0.3-next.18
+    * @twin.org/validate-locales bumped from 0.0.3-next.17 to 0.0.3-next.18
+
+## [0.0.3-next.17](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.16...modules-v0.0.3-next.17) (2026-02-09)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.16 to 0.0.3-next.17
+    * @twin.org/context bumped from 0.0.3-next.16 to 0.0.3-next.17
+    * @twin.org/nameof bumped from 0.0.3-next.16 to 0.0.3-next.17
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.16 to 0.0.3-next.17
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.16 to 0.0.3-next.17
+    * @twin.org/validate-locales bumped from 0.0.3-next.16 to 0.0.3-next.17
+
+## [0.0.3-next.16](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.15...modules-v0.0.3-next.16) (2026-02-06)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.15 to 0.0.3-next.16
+    * @twin.org/context bumped from 0.0.3-next.15 to 0.0.3-next.16
+    * @twin.org/nameof bumped from 0.0.3-next.15 to 0.0.3-next.16
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.15 to 0.0.3-next.16
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.15 to 0.0.3-next.16
+    * @twin.org/validate-locales bumped from 0.0.3-next.15 to 0.0.3-next.16
+
+## [0.0.3-next.15](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.14...modules-v0.0.3-next.15) (2026-01-29)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.14 to 0.0.3-next.15
+    * @twin.org/context bumped from 0.0.3-next.14 to 0.0.3-next.15
+    * @twin.org/nameof bumped from 0.0.3-next.14 to 0.0.3-next.15
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.14 to 0.0.3-next.15
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.14 to 0.0.3-next.15
+    * @twin.org/validate-locales bumped from 0.0.3-next.14 to 0.0.3-next.15
+
+## [0.0.3-next.14](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.13...modules-v0.0.3-next.14) (2026-01-22)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.13 to 0.0.3-next.14
+    * @twin.org/context bumped from 0.0.3-next.13 to 0.0.3-next.14
+    * @twin.org/nameof bumped from 0.0.3-next.13 to 0.0.3-next.14
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.13 to 0.0.3-next.14
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.13 to 0.0.3-next.14
+    * @twin.org/validate-locales bumped from 0.0.3-next.13 to 0.0.3-next.14
+
+## [0.0.3-next.13](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.12...modules-v0.0.3-next.13) (2026-01-08)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.12 to 0.0.3-next.13
+    * @twin.org/context bumped from 0.0.3-next.12 to 0.0.3-next.13
+    * @twin.org/nameof bumped from 0.0.3-next.12 to 0.0.3-next.13
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.12 to 0.0.3-next.13
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.12 to 0.0.3-next.13
+    * @twin.org/validate-locales bumped from 0.0.3-next.12 to 0.0.3-next.13
+
+## [0.0.3-next.12](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.11...modules-v0.0.3-next.12) (2026-01-08)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.11 to 0.0.3-next.12
+    * @twin.org/context bumped from 0.0.3-next.11 to 0.0.3-next.12
+    * @twin.org/nameof bumped from 0.0.3-next.11 to 0.0.3-next.12
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.11 to 0.0.3-next.12
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.11 to 0.0.3-next.12
+    * @twin.org/validate-locales bumped from 0.0.3-next.11 to 0.0.3-next.12
+
+## [0.0.3-next.11](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.10...modules-v0.0.3-next.11) (2026-01-07)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.10 to 0.0.3-next.11
+    * @twin.org/context bumped from 0.0.3-next.10 to 0.0.3-next.11
+    * @twin.org/nameof bumped from 0.0.3-next.10 to 0.0.3-next.11
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.10 to 0.0.3-next.11
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.10 to 0.0.3-next.11
+    * @twin.org/validate-locales bumped from 0.0.3-next.10 to 0.0.3-next.11
+
+## [0.0.3-next.10](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.9...modules-v0.0.3-next.10) (2026-01-07)
+
+
+### Features
+
+* retain detail in Errors from background threads ([52bdeef](https://github.com/twinfoundation/framework/commit/52bdeef7a75fd462ed118073b9dc7612304e038d))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.9 to 0.0.3-next.10
+    * @twin.org/context bumped from 0.0.3-next.9 to 0.0.3-next.10
+    * @twin.org/nameof bumped from 0.0.3-next.9 to 0.0.3-next.10
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.9 to 0.0.3-next.10
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.9 to 0.0.3-next.10
+    * @twin.org/validate-locales bumped from 0.0.3-next.9 to 0.0.3-next.10
+
+## [0.0.3-next.9](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.8...modules-v0.0.3-next.9) (2026-01-05)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.8 to 0.0.3-next.9
+    * @twin.org/context bumped from 0.0.3-next.8 to 0.0.3-next.9
+    * @twin.org/nameof bumped from 0.0.3-next.8 to 0.0.3-next.9
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.8 to 0.0.3-next.9
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.8 to 0.0.3-next.9
+    * @twin.org/validate-locales bumped from 0.0.3-next.8 to 0.0.3-next.9
+
+## [0.0.3-next.8](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.7...modules-v0.0.3-next.8) (2025-11-26)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.7 to 0.0.3-next.8
+    * @twin.org/context bumped from 0.0.3-next.7 to 0.0.3-next.8
+    * @twin.org/nameof bumped from 0.0.3-next.7 to 0.0.3-next.8
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.7 to 0.0.3-next.8
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.7 to 0.0.3-next.8
+    * @twin.org/validate-locales bumped from 0.0.3-next.7 to 0.0.3-next.8
+
+## [0.0.3-next.7](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.6...modules-v0.0.3-next.7) (2025-11-25)
+
+
+### Features
+
+* add context id features ([#206](https://github.com/twinfoundation/framework/issues/206)) ([ef0d4ee](https://github.com/twinfoundation/framework/commit/ef0d4ee11a4f5fc6cc6f52a4958ce905c04ee13b))
+* add guards arrayEndsWith and arrayStartsWith ([95d875e](https://github.com/twinfoundation/framework/commit/95d875ec8ccb4713c145fdde941d4cfedcec2ed3))
+* eslint migration to flat config ([74427d7](https://github.com/twinfoundation/framework/commit/74427d78d342167f7850e49ab87269326355befe))
+* improve async pattern and error handling ([aaa1f68](https://github.com/twinfoundation/framework/commit/aaa1f6879d60adf04b78b0c1bbbec50f2873f020))
+* improve Is.function and ModuleHelper.getModuleMethod signatures ([ecf968b](https://github.com/twinfoundation/framework/commit/ecf968b02934b3676be4bf7cd2d1e7f8e7af6ce2))
+* locales validation ([#197](https://github.com/twinfoundation/framework/issues/197)) ([55fdadb](https://github.com/twinfoundation/framework/commit/55fdadb13595ce0047f787bd1d4135d429a99f12))
+* module helper can now handle long running threads with messaging ([4ecbb9a](https://github.com/twinfoundation/framework/commit/4ecbb9a526927d462d4fb3f95ba2a44889202753))
+* nodeIdentity optional in IComponent methods ([c78dc17](https://github.com/twinfoundation/framework/commit/c78dc17f4357d3e1ae40e415f468d3eae13e81f4))
+* provide module helper override ([e998a64](https://github.com/twinfoundation/framework/commit/e998a64842cfd18693a14444be33b084fef2bb90))
+* relocate core packages from tools ([bcab8f3](https://github.com/twinfoundation/framework/commit/bcab8f3160442ea4fcaf442947462504f3d6a17d))
+* update dependencies ([f3bd015](https://github.com/twinfoundation/framework/commit/f3bd015efd169196b7e0335f5cab876ba6ca1d75))
+* use cause instead of inner for errors ([1f4acc4](https://github.com/twinfoundation/framework/commit/1f4acc4d7a6b71a134d9547da9bf40de1e1e49da))
+* use new shared store mechanism ([#131](https://github.com/twinfoundation/framework/issues/131)) ([934385b](https://github.com/twinfoundation/framework/commit/934385b2fbaf9f5c00a505ebf9d093bd5a425f55))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.6 to 0.0.3-next.7
+    * @twin.org/context bumped from 0.0.3-next.6 to 0.0.3-next.7
+    * @twin.org/nameof bumped from 0.0.3-next.6 to 0.0.3-next.7
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.6 to 0.0.3-next.7
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.6 to 0.0.3-next.7
+    * @twin.org/validate-locales bumped from 0.0.3-next.6 to 0.0.3-next.7
+
+## [0.0.3-next.6](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.5...modules-v0.0.3-next.6) (2025-11-25)
+
+
+### Features
+
+* module helper can now handle long running threads with messaging ([4ecbb9a](https://github.com/twinfoundation/framework/commit/4ecbb9a526927d462d4fb3f95ba2a44889202753))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.5 to 0.0.3-next.6
+    * @twin.org/context bumped from 0.0.3-next.5 to 0.0.3-next.6
+    * @twin.org/nameof bumped from 0.0.3-next.5 to 0.0.3-next.6
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.5 to 0.0.3-next.6
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.5 to 0.0.3-next.6
+    * @twin.org/validate-locales bumped from 0.0.3-next.5 to 0.0.3-next.6
+
+## [0.0.3-next.5](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.4...modules-v0.0.3-next.5) (2025-11-20)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.4 to 0.0.3-next.5
+    * @twin.org/nameof bumped from 0.0.3-next.4 to 0.0.3-next.5
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.4 to 0.0.3-next.5
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.4 to 0.0.3-next.5
+    * @twin.org/validate-locales bumped from 0.0.3-next.4 to 0.0.3-next.5
+
+## [0.0.3-next.4](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.3...modules-v0.0.3-next.4) (2025-11-13)
+
+
+### Miscellaneous Chores
+
+* **modules:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.3-next.3 to 0.0.3-next.4
+    * @twin.org/nameof bumped from 0.0.3-next.3 to 0.0.3-next.4
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.0.3-next.3 to 0.0.3-next.4
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.3-next.3 to 0.0.3-next.4
+    * @twin.org/validate-locales bumped from 0.0.3-next.3 to 0.0.3-next.4
 
 ## [0.0.3-next.3](https://github.com/twinfoundation/framework/compare/modules-v0.0.3-next.2...modules-v0.0.3-next.3) (2025-11-12)
 

package/docs/examples.md

@@ -1 +1,110 @@
-# @twin.org/modules - Examples
+# Modules Examples
+
+Use these snippets for dynamic module loading patterns at runtime extension points.
+
+## ModuleHelper
+
+```typescript
+import { ModuleHelper } from '@twin.org/modules';
+
+console.log(ModuleHelper.isRelativeModule('./workers/sendEmail.js')); // true
+console.log(ModuleHelper.isLocalModule('./workers/sendEmail.js')); // true
+console.log(ModuleHelper.isLocalModule('@twin.org/core')); // false
+```
+
+```typescript
+import { ModuleHelper } from '@twin.org/modules';
+
+const convertToFahrenheit = await ModuleHelper.getModuleMethod<(celsius: number) => number>(
+  './workers/temperature.js',
+  'convertToFahrenheit'
+);
+
+console.log(convertToFahrenheit(18)); // 64.4
+```
+
+```typescript
+import { ModuleHelper } from '@twin.org/modules';
+
+const sum = await ModuleHelper.getModuleEntry<(left: number, right: number) => number>(
+  './workers/math.js',
+  'sum'
+);
+
+console.log(sum(7, 5)); // 12
+```
+
+```typescript
+import { ModuleHelper } from '@twin.org/modules';
+
+const result = await ModuleHelper.execModuleMethod<number>(
+  './workers/temperature.js',
+  'convertToFahrenheit',
+  [18]
+);
+
+console.log(result); // 64.4
+```
+
+```typescript
+import { ModuleHelper } from '@twin.org/modules';
+
+ModuleHelper.overrideImport(async moduleName => {
+  if (moduleName === './workers/math.js') {
+    return {
+      module: {
+        sum: (left: number, right: number) => left + right
+      },
+      useDefault: false
+    };
+  }
+
+  return {
+    useDefault: true
+  };
+});
+
+const sum = await ModuleHelper.execModuleMethod<number>('./workers/math.js', 'sum', [3, 4]);
+
+console.log(sum); // 7
+```
+
+```typescript
+import { ModuleHelper } from '@twin.org/modules';
+
+const threaded = await ModuleHelper.execModuleMethodThread<number>(
+  './workers/temperature.js',
+  'convertToFahrenheit',
+  [18],
+  {
+    traceId: 'trc-01',
+    spanId: 'spn-02'
+  }
+);
+
+console.log(threaded); // 64.4
+```
+
+```typescript
+import { ModuleHelper } from '@twin.org/modules';
+
+const worker = ModuleHelper.execModuleMethodThreadMessage(
+  './workers/temperature.js',
+  (operation, result, err) => {
+    if (err) {
+      console.log(err.message); // resultError
+      return;
+    }
+
+    if (operation === 'convertToFahrenheit') {
+      console.log(result); // 64.4
+    }
+  },
+  {
+    threadName: 'temperature-worker'
+  }
+);
+
+worker.executeMethod('convertToFahrenheit', [18]);
+await worker.terminate();
+```

package/docs/reference/classes/ModuleHelper.md

@@ -14,7 +14,7 @@ Helper functions for modules.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -22,7 +22,7 @@ Runtime name for the class.
 
 ## Methods
 
-### overrideImport()
+### overrideImport() {#overrideimport}
 
 > `static` **overrideImport**(`overrideImport`): `void`
 
@@ -42,7 +42,7 @@ The override import function.
 
 ***
 
-### getModuleEntry()
+### getModuleEntry() {#getmoduleentry}
 
 > `static` **getModuleEntry**\<`T`\>(`module`, `entry`): `Promise`\<`T`\>
 
@@ -80,7 +80,7 @@ GeneralError if getting the module entry failed.
 
 ***
 
-### getModuleMethod()
+### getModuleMethod() {#getmodulemethod}
 
 > `static` **getModuleMethod**\<`T`\>(`module`, `method`): `Promise`\<`T`\>
 
@@ -118,7 +118,7 @@ GeneralError if executing the module entry failed.
 
 ***
 
-### execModuleMethod()
+### execModuleMethod() {#execmodulemethod}
 
 > `static` **execModuleMethod**\<`T`\>(`module`, `method`, `args?`): `Promise`\<`T`\>
 
@@ -162,9 +162,9 @@ GeneralError if executing the module entry failed.
 
 ***
 
-### execModuleMethodThread()
+### execModuleMethodThread() {#execmodulemethodthread}
 
-> `static` **execModuleMethodThread**\<`T`\>(`module`, `method`, `args?`): `Promise`\<`T`\>
+> `static` **execModuleMethodThread**\<`T`\>(`module`, `method`, `args?`, `contextIds?`): `Promise`\<`T`\>
 
 Execute the method in the module in a thread.
 
@@ -194,6 +194,12 @@ The method to execute from the module.
 
 The arguments to pass to the method.
 
+##### contextIds?
+
+`IContextIds`
+
+The context IDs.
+
 #### Returns
 
 `Promise`\<`T`\>
@@ -206,7 +212,49 @@ GeneralError if executing the module entry failed.
 
 ***
 
-### isLocalModule()
+### execModuleMethodThreadMessage() {#execmodulemethodthreadmessage}
+
+> `static` **execModuleMethodThreadMessage**(`module`, `completed`, `options?`): [`IModuleWorker`](../interfaces/IModuleWorker.md)
+
+Load the module and provide a messaging interface.
+
+#### Parameters
+
+##### module
+
+`string`
+
+The module.
+
+##### completed
+
+(`operation`, `result?`, `err?`) => `void`
+
+Callback called when the worker thread processes a completion.
+
+##### options?
+
+Optional settings.
+
+###### threadName?
+
+`string`
+
+The name of the thread.
+
+#### Returns
+
+[`IModuleWorker`](../interfaces/IModuleWorker.md)
+
+The messaging interface.
+
+#### Throws
+
+GeneralError if executing the module entry failed.
+
+***
+
+### isLocalModule() {#islocalmodule}
 
 > `static` **isLocalModule**(`name`): `boolean`
 
@@ -228,7 +276,7 @@ True if the module is local, false otherwise.
 
 ***
 
-### isRelativeModule()
+### isRelativeModule() {#isrelativemodule}
 
 > `static` **isRelativeModule**(`name`): `boolean`
 

package/docs/reference/index.md

@@ -3,3 +3,7 @@
 ## Classes
 
 - [ModuleHelper](classes/ModuleHelper.md)
+
+## Interfaces
+
+- [IModuleWorker](interfaces/IModuleWorker.md)

package/docs/reference/interfaces/IModuleWorker.md

@@ -0,0 +1,51 @@
+# Interface: IModuleWorker
+
+Worker definition for modules.
+
+## Methods
+
+### executeMethod() {#executemethod}
+
+> **executeMethod**(`method`, `args?`, `contextIds?`): `void`
+
+Execute a method in the module.
+
+#### Parameters
+
+##### method
+
+`string`
+
+The method to execute.
+
+##### args?
+
+`unknown`
+
+The arguments for the method.
+
+##### contextIds?
+
+`IContextIds`
+
+The context IDs.
+
+#### Returns
+
+`void`
+
+The result of the method.
+
+***
+
+### terminate() {#terminate}
+
+> **terminate**(): `Promise`\<`number`\>
+
+Terminate the worker.
+
+#### Returns
+
+`Promise`\<`number`\>
+
+A promise that resolves when the worker is terminated including the exit code.

package/locales/en.json

@@ -3,9 +3,8 @@
 		"moduleHelper": {
 			"moduleNotFound": "Failed to load module \"{module}\"",
 			"entryNotFound": "Failed to load entry \"{entry}\" from module \"{module}\"",
-			"notFunction": "The entry \"{entry}\" in module \"{module}\" is not a function",
-			"workerFailed": "The thread worker failed for \"{entry}\" in module \"{module}\" with exit code \"{exitCode}\"",
-			"workerException": "The thread worker failed with an exception \"{entry}\" in module \"{module}\""
+			"notFunction": "The entry \"{method}\" in module \"{module}\" is not a function",
+			"workerException": "The thread worker failed with an exception in module \"{module}\""
 		}
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/modules",
-	"version": "0.0.3-next.3",
+	"version": "0.0.3-next.31",
 	"description": "Helper classes for loading and executing from modules",
 	"repository": {
 		"type": "git",
@@ -14,8 +14,9 @@
 		"node": ">=20.0.0"
 	},
 	"dependencies": {
-		"@twin.org/core": "0.0.3-next.3",
-		"@twin.org/nameof": "0.0.3-next.3"
+		"@twin.org/context": "0.0.3-next.31",
+		"@twin.org/core": "0.0.3-next.31",
+		"@twin.org/nameof": "0.0.3-next.31"
 	},
 	"main": "./dist/es/index.js",
 	"types": "./dist/types/index.d.ts",