@teqfw/di 0.35.0 → 0.36.0

package/README.md

@@ -124,7 +124,7 @@ const app = await container.get('App_Main$');
 
 ## Test Mode Support
 
-`@teqfw/di` supports a dedicated **test mode** to help with unit testing and dependency mocking.
+`@teqfw/di` supports a dedicated **test mode** to facilitate unit testing and dependency mocking.
 
 When test mode is enabled via `container.enableTestMode()`, you can manually register singleton dependencies using the
 `register(depId, obj)` method:
@@ -134,9 +134,31 @@ container.enableTestMode();
 container.register('App_Service_Customer$', mockCustomerService);
 ```
 
-This makes it easy to substitute real implementations with mocks or stubs during tests, without affecting production
-logic. Test mode safeguards this capability, ensuring that manual overrides are only permitted in designated test
-environments.
+This makes it easy to substitute real implementations with mocks or stubs during tests, without altering production
+logic. Overrides are allowed only in test mode, ensuring clean separation of concerns.
+
+### Mocking Node.js Built-in Modules
+
+A powerful feature of `@teqfw/di` is the ability to mock **Node.js built-in libraries** such as `fs`, `path`, or
+`process`. This is useful for isolating side effects and simulating system behavior:
+
+```js
+container.register('node:fs', {
+    existsSync: (path) => path.endsWith('.html'),
+});
+```
+
+You can also register mocks for custom logic or environment-specific behavior:
+
+```js
+container.register('node:path', {
+    join: (...args) => args.join('/'),
+    resolve: (p) => `/abs/${p}`,
+});
+```
+
+These mocks are injected transparently wherever such modules are used as dependencies, making it possible to write pure,
+isolated, and deterministic unit tests — even for logic that relies on the filesystem or path resolution.
 
 ---
 

package/RELEASE.md

@@ -1,5 +1,12 @@
 # @teqfw/di releases
 
+## 0.36.0 – New Preprocessor for Dynamic Dependency Rewriting
+
+- Introduced `TeqFw_Di_Pre_Replace`, a new preprocessor allowing runtime substitution of dependency identifiers before
+  object creation, enabling advanced customization scenarios.
+- Improved documentation (`README.md`): added concrete examples of mocking native Node.js modules during testing, better
+  illustrating the power of test mode and late binding.
+
 ## 0.35.0 – Support for Node.js Module Mocking in Test Mode
 
 - DI container (test mode): extended support to register not only singleton instances but also mock implementations of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teqfw/di",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "Dependency Injection container for ES6 modules that works in both browser and Node.js apps.",
   "keywords": [
     "dependency injection",

package/src/Pre/Replace.js

@@ -0,0 +1,80 @@
+/**
+ * Pre-processor chunk that replaces module addresses during dependency resolution.
+ *
+ * This chunk allows dynamically overriding the module namespace used to resolve source code
+ * for a given dependency ID. Only the `moduleName` field of the `depId` is modified.
+ * All other metadata (such as lifestyle, export type, etc.) remains unchanged.
+ *
+ * This mechanism enables redirecting from one module implementation to another
+ * without changing aliases or component registration.
+ *
+ * Example:
+ *     Replace module path 'Fl32_Cms_Back_Api_Adapter' with 'App_Cms_Adapter_Custom',
+ *     while keeping the lifestyle and export configuration intact.
+ *
+ * @implements {TeqFw_Di_Api_Container_PreProcessor_Chunk}
+ */
+export default class TeqFw_Di_Pre_Replace {
+
+    constructor() {
+        // VARS
+
+        /**
+         * Mapping of source module namespaces to their replacements.
+         * Keys and values are strings without export/lifestyle suffixes.
+         *
+         * Example:
+         * {
+         *   'Fl32_Cms_Back_Api_Adapter': 'App_Cms_Adapter_Custom'
+         * }
+         *
+         * This means: when resolving a module with `moduleName === 'Fl32_Cms_Back_Api_Adapter'`,
+         * use source code from `'App_Cms_Adapter_Custom'` instead.
+         *
+         * @type {Object<string, string>}
+         */
+        const map = {};
+
+        // INSTANCE METHODS
+
+        /**
+         * Register a single module address replacement.
+         *
+         * @param {string} orig - Original module namespace (e.g. 'X_Y_Z')
+         * @param {string} alter - Replacement module namespace (e.g. 'A_B_C')
+         */
+        this.add = function (orig, alter) {
+            map[orig] = alter;
+        };
+
+        /* eslint-disable no-unused-vars */
+        /**
+         * Replace the `moduleName` of the dependency ID if a mapping exists.
+         *
+         * This function does not alter any other part of the `depId` (e.g. lifestyle, export kind).
+         *
+         * @param {TeqFw_Di_DepId} depId - Dependency ID after previous transformations.
+         * @param {TeqFw_Di_DepId} originalId - Original dependency ID before any processing.
+         * @param {string[]} stack - Stack of parent dependency IDs (for trace/debug).
+         * @returns {TeqFw_Di_DepId} - Transformed `depId` with updated `moduleName` if replaced.
+         */
+        this.modify = function (depId, originalId, stack) {
+            let module = depId.moduleName;
+            const seen = new Set();
+
+            while (map[module] && !seen.has(module)) {
+                seen.add(module);
+                module = map[module];
+            }
+
+            if (module !== depId.moduleName) {
+                return {
+                    ...depId,
+                    moduleName: module,
+                };
+            }
+
+            return depId;
+        };
+    }
+}