@teqfw/di 0.34.0 → 0.36.0

package/PHILOSOPHY.md

@@ -0,0 +1,175 @@
+# Philosophy of the TeqFW Platform
+
+**The philosophy of Tequila Framework (TeqFW)** is my personal approach to organizing web application development. I,
+Alex Gusev, have shaped this approach based on my own experience, which focuses on **modular monoliths** with a single
+database. This document reflects that specific context and does not aim to be universal.
+
+Some of the principles presented may be applicable more broadly, while others may be irrelevant (or even
+counterproductive) outside monolithic architectures. It is important to keep this limitation in mind when interpreting
+the material.
+
+The document is intended to provide cognitive context for both human and artificial intelligences. It addresses both
+specific aspects of web development and more general software architecture issues, emphasizing the reduction of
+excessive complexity, improved structuring, and adaptability to changes.
+
+**Tequila Framework (TeqFW)** is not a finished product but an evolving experimental platform. It serves as a testbed
+for the principles outlined here and is actively used in development.
+
+## Core Principles of TeqFW
+
+1. **Use a Unified Development Language:** JavaScript (ES6+) is used on both the client and server sides, ensuring code
+   integrity, reducing duplication, and lowering cognitive load.
+
+2. **Enable Late Binding for Flexibility:** Dynamic dependency management through an object container and ES6 module
+   namespaces. This reduces tight coupling between modules, simplifies system expansion, and makes the code more
+   adaptable.
+
+3. **Design for Evolutionary Code Resilience:** Code is designed with inevitable changes in mind to minimize adaptation
+   costs and facilitate expansion without modifying existing components.
+
+4. **Separate Data and Logic Functionally:** Isolation of data structures (DTO) and logic handlers. This approach makes
+   code easier to test, maintain, and reuse.
+
+5. **Use Namespaces for Structure and Isolation:** Each type of entity—npm packages, ES6 modules, database tables, CLI
+   commands, or configurations—has its own namespace. This ensures clear project structure, reduces conflicts, and
+   simplifies code navigation.
+
+6. **Favor Pure JavaScript Without Compilation:** Using modern JavaScript (ES6+) without TypeScript or version
+   downgrading. The code remains transparent and accessible, simplifying maintenance, library integration, and speeding
+   up development.
+
+7. **Optimize Code and Docs for LLMs:** Code and documentation are organized to be easily analyzed and supplemented by
+   language models. Clear structure, standardized templates, and predictable conventions simplify automation and code
+   generation.
+
+## Principles in Detail
+
+### Use a Unified Development Language
+
+Using modern JavaScript (ES6+) at all application levels eliminates the need to switch between different languages and
+simplifies knowledge sharing among developers. This is especially important in small teams and projects with limited
+resources, where minimizing cognitive load accelerates work.
+
+Browsers support only JavaScript (among high-level languages), and thanks to Node.js, it has become widespread in server
+development. This enables writing **isomorphic code** that can be reused on both client and server sides, reducing logic
+duplication.
+
+A unified language simplifies code maintenance and accelerates the onboarding of new developers into the project.
+
+### Enable Late Binding for Flexibility
+
+Late binding ensures architectural flexibility by allowing dynamic dependency management without tight coupling between
+modules. Instead of direct imports, ES6 module namespaces and an object container are used to handle instantiation and
+component replacement at runtime.
+
+This approach reduces the risk of application "breakage" due to changes, simplifies system expansion, and makes the code
+more adaptable. Components can be replaced without deep refactoring, and the dependency mechanism remains transparent
+and predictable.
+
+Late binding also improves testability: modules can be replaced with stubs or alternative implementations, making it
+easier to isolate tests. In team development, this simplifies understanding of complex dependencies and makes system
+maintenance more manageable.
+
+### Design for Evolutionary Code Resilience
+
+Code is designed to adapt to inevitable changes in requirements, APIs, and data with minimal overhead. This is achieved
+through approaches that allow **expanding functionality without significant modifications to existing code**.
+
+Key techniques:
+
+- **Flexible input data processing.** Using function argument destructuring and the "ignore unknown attributes"
+  principle in data structures allows adding new parameters and properties without modifying existing handlers.
+- **Clear interaction contracts.** Separating interfaces from implementations reduces the impact of changes while
+  maintaining system predictability.
+- **Late binding.** Components depend on abstractions rather than specific implementations, enabling code adaptation
+  without directly modifying dependencies (see **Enable Late Binding for Flexibility** principle).
+
+These methods make the code less fragile and allow the system to evolve while reducing complexity and refactoring
+volume.
+
+### Separate Data and Logic Functionally
+
+Code is divided into **data structures (DTO) and logic handlers**, eliminating state within handlers and making them
+independent of data. DTOs contain all necessary information and are passed between handlers that perform operations on
+them.
+
+This approach offers several key advantages:
+
+- **Handlers can be singletons.** Since they do not store state, they are execution-context-independent and can be
+  shared across the entire application.
+- **The program consists of data processing nodes.** The code is structured as a set of functions that receive data,
+  process it, and pass it on.
+- **Changeability through pure logic.** Logic remains separate from data structures, allowing modifications without
+  affecting handlers and vice versa.
+- **Minimized side effects.** Handlers do not depend on global state, making the system more predictable.
+
+### Use Namespaces for Structure and Isolation
+
+Namespaces ensure a clear project structure and prevent conflicts by allowing each entity to reserve its name and build
+its own hierarchy. This principle applies at all levels:
+
+- **Packages and modules.** npm packages and ES6 modules are organized into predictable namespaces, avoiding dependency
+  conflicts.
+- **Files and classes.** File and class names reflect their purpose and relationships with other components, simplifying
+  project navigation and structure.
+- **Database tables.** Table names are structured to avoid collisions and logically group data.
+- **Endpoints and APIs.** Namespaces are used in routing and APIs, ensuring consistent addressing.
+- **Configurations and CLI commands.** Settings and commands are organized hierarchically to prevent duplication.
+
+Code is designed to operate in an environment with other code. Each unit within its namespace reserves a name and builds
+a downward hierarchy, creating a predictable interaction structure.
+
+### Favor Pure JavaScript Without Compilation
+
+Tequila Framework uses modern JavaScript (ES6+) without version downgrading or strict TypeScript typing. The code
+remains in its original form, making it transparent, accessible, and easy to maintain.
+
+Key characteristics:
+
+- **No compilation.** Developers work with pure JavaScript without intermediate transformations, speeding up debugging
+  and simplifying maintenance.
+- **JSDoc instead of TypeScript.** JSDoc annotations allow IDEs to understand data structures and provide
+  autocompletion, maintaining flexibility without strict typing.
+- **Maximum compatibility.** The code easily integrates with any libraries and tools, as it does not require adaptation
+  to strict type contracts.
+- **Fast development.** Changes are immediately reflected in the code without requiring a rebuild, increasing
+  development speed.
+
+### Optimize Code and Docs for LLMs
+
+Architecture, code, and documentation are designed for easy analysis and use by language models (LLM). This improves the
+efficiency of **automatic code completion, generation of template solutions, and integration with AI tools**.
+
+For this, the following practices are applied:
+
+- **Predictable project structure.** Clear file organization, logical naming, and standardized conventions.
+- **Unified code templates.** Repetitive structures and a predictable format help models understand and supplement the
+  code.
+- **Optimized abstraction depth.** Code is organized to maintain modularity while avoiding excessive nesting.
+- **Automated annotations.** JSDoc and standardized comments ensure precise code generation and documentation.
+
+This approach allows LLM agents to:
+
+- Quickly analyze code and suggest corrections.
+- Automatically supplement documentation and comment code.
+- Generate new modules according to the project's architectural standards.
+- Simplify CI/CD integration by checking code compliance with style and conventions.
+
+LLMs become part of the development process, helping not only with writing code but also keeping it up to date, reducing
+developers' routine workload.
+
+## Conclusion
+
+The principles outlined in this document form an approach to **modular monolith** development, focused on
+predictability, structure, and adaptability. They enable building architectures where code remains flexible,
+transparent, and easily extensible.
+
+These ideas do not require complex theoretical justifications or significant time investments for validation. They aim
+to simplify integration, reduce unnecessary complexity, and enhance the potential for automation. **Standardized
+structures, predictable namespaces, and development without transpilation** create an environment where the code is
+understandable both for developers and language models (LLM).
+
+The **Tequila Framework (TeqFW)** platform demonstrates these principles in action. While still evolving, it already
+supports real-world development. This approach may serve not only as a foundation for proprietary tools, but also as
+inspiration for rethinking conventional software architecture, prioritizing clarity, modularity, and adaptability over
+unnecessary complexity.

package/README.md

@@ -8,16 +8,33 @@ objects with minimal manual configuration. It integrates smoothly in both browse
 flexibility, modularity, and easier testing for your applications.
 
 Unlike typical object containers, `@teqfw/di` requires no manual registration of objects, instead mapping dependency IDs
-directly to their source paths for greater simplicity.
+directly to their source paths for greater simplicity. However, for advanced use cases—such as unit testing—it is
+possible to explicitly register singleton objects using the `register(depId, obj)` method (available only in test mode).
+This allows controlled substitution of dependencies without altering the main codebase.
 
 **This library is specifically optimized for ES6 modules, ensuring top performance and compatibility. It does not
 support CommonJS, AMD, UMD, or other module formats.**
 
+To increase robustness, all instances created by the container are automatically **frozen** using `Object.freeze()`.
+This guarantees immutability of the returned objects, helping prevent accidental modifications and ensuring predictable
+behavior at runtime.
+
 While this library is primarily designed for JavaScript, it is also fully compatible with TypeScript. Developers can use
 TypeScript to compose dependency identifiers in the same way as in JavaScript. It is important to ensure that TypeScript
 transpiles the source code to ES6 modules for proper functionality. With this setup, TypeScript users can effectively
 leverage the benefits of this library without any additional configuration.
 
+---
+
+## Design Philosophy
+
+This library is a component of the **TeqFW platform**, an experimental framework grounded in the principles of modular
+monolith design, long-term maintainability, late binding, and immutability-first logic composition.
+
+To explore the conceptual background, see: **[TeqFW Philosophy](./PHILOSOPHY.md)**.
+
+---
+
 ## Samples
 
 Explore `@teqfw/di` in action through the following demo applications:
@@ -36,6 +53,8 @@ Explore `@teqfw/di` in action through the following demo applications:
 
 These projects offer practical examples and insights into using `@teqfw/di` effectively!
 
+---
+
 ## Example of Typical Usage
 
 Using `@teqfw/di` typically involves a few simple steps: organizing the file structure, declaring dependencies,
@@ -58,7 +77,7 @@ as the container can be configured to work with any layout (e.g., within `/home/
 
 ### Step 2: Declare Dependencies
 
-In your code, declare dependencies by defining them as keys in the constructor. Dependency identifiers here follow a
+In your code, declare dependencies by specifying them as keys in the constructor. Dependency identifiers here follow a
 namespace style similar to PHP Zend 1, which is used by default in this library. You can also implement a custom parser
 if you prefer a different naming convention or mapping strategy.
 
@@ -101,6 +120,48 @@ Finally, retrieve your main application instance. The container automatically in
 const app = await container.get('App_Main$');
   ```
 
+---
+
+## Test Mode Support
+
+`@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:
+
+```js
+container.enableTestMode();
+container.register('App_Service_Customer$', mockCustomerService);
+```
+
+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.
+
+---
+
 ## Key Benefits
 
 `@teqfw/di` offers the core functionality of any object container — creating objects and injecting dependencies — with
@@ -117,6 +178,10 @@ Here’s what makes it stand out:
 - **Mapping IDs to Source Modules via Resolvers**: Thanks to resolvers, `@teqfw/di` lets you map dependency IDs to their
   source locations effortlessly. This makes the library adaptable to any project structure or file layout.
 
+- **Immutable Objects for Safer Runtime**: All objects created by the container are frozen by default. This ensures that
+  dependencies cannot be modified once instantiated, eliminating unintended mutations and reinforcing modular,
+  predictable application behavior.
+
 - **Preprocessing for Enhanced Control**: Built-in preprocessing allows modifying dependencies at the time of creation,
   enabling local overrides or adjustments in functionality. This is especially useful for larger projects, where
   different teams may tailor dependencies to their specific requirements. The default preprocessing can also be replaced
@@ -132,6 +197,8 @@ Here’s what makes it stand out:
 These features make `@teqfw/di` a powerful, adaptable DI container that not only provides ready-to-use solutions but can
 be easily customized to meet unique project demands.
 
+---
+
 ## Installation
 
 ### For Node.js
@@ -220,6 +287,8 @@ Alternatively, you can use the UMD version in the browser (~5KB):
 With these steps, the container is configured to automatically resolve and inject dependencies based on your setup,
 whether in Node.js or in a browser environment.
 
+---
+
 ## Dependency ID Types
 
 `@teqfw/di` supports various dependency ID formats to match different import styles and object requirements. Here’s a
@@ -259,6 +328,8 @@ export default class App_Main {
 }
 ```
 
+---
+
 ## Summary
 
 `@teqfw/di` is a versatile and lightweight dependency injection container tailored for modern JavaScript applications.
@@ -266,8 +337,8 @@ With its flexible dependency mapping, customizable ID configurations, and suppor
 `@teqfw/di` empowers developers to build modular, testable, and scalable codebases.
 
 Whether you’re working in Node.js or a browser environment, `@teqfw/di` provides a solid foundation with built-in
-functionality that you can further adapt to fit your project’s unique requirements. You are encouraged to explore and
-extend this library as needed to create your ideal development environment.
+functionality that you can further adapt to fit your project’s unique requirements. Feel free to explore and extend the
+library as needed to create your ideal development environment.
 
 For any questions, feedback, or collaboration opportunities, please feel free to reach out through the following
 channels:

package/RELEASE.md

@@ -1,5 +1,21 @@
 # @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
+  native Node.js modules, enabling more flexible and robust unit testing.
+- Added missing property `TeqFw_Di_DepId.isNodeModule` to properly identify Node.js modules in the dependency resolution
+  process.
+- Improved documentation (`README.md` and `PHILOSOPHY.md`) to clarify the design philosophy of TeqFW and explain the
+  immutability and test mode features in greater detail.
+
 ## 0.34.0 – Strict Mode and Test Support
 
 - Removed outdated interface `TeqFw_Di_Api_Container` and associated documentation.

package/dist/esm.js

@@ -1 +1 @@
-var e={CA:"A",CF:"F",ID:"container",ID_FQN:"TeqFw_Di_Container$",LI:"I",LS:"S",isClass(e){const t=Object.getOwnPropertyDescriptor(e,"prototype");return t&&!t.writable}};const t=/(function)*\s*\w*\s*\(\s*\{([^}]*)}/s,o=/constructor\s*\(\s*\{([^}]*)}/s;function n(e){const t=[];try{const o=new Function(`{${e}}`,"return");o(new Proxy({},{get:(e,o)=>t.push(o)}))}catch(t){throw new Error(`Cannot analyze the deps specification:${e}\n\nPlease, be sure that spec does not contain extra ')' in a comments.\n\nError: ${t}`)}return t}function s(s){return"function"==typeof s?e.isClass(s)?function(e){const t=[],s=e.toString(),r=o.exec(s);return r&&t.push(...n(r[1])),t}(s):function(e){const o=[],s=e.toString(),r=t.exec(s);return r&&o.push(...n(r[2])),o}(s):[]}class r{constructor(){let t=!1;this.create=async function(o,n,r,i){if(r.includes(o.origin))throw new Error(`Circular dependency for '${o.origin}'. Parents are: ${JSON.stringify(r)}`);if(o.exportName){const a=[...r,o.origin],{[o.exportName]:l}=n;if(o.composition===e.CF){if("function"==typeof l){const n=s(l);n.length&&(c=`Deps for object '${o.origin}' are: ${JSON.stringify(n)}`,t&&console.log(c));const r={};for(const e of n)r[e]=await i.get(e,a);const u=e.isClass(l)?new l(r):l(r);return u instanceof Promise?await u:u}return Object.assign({},l)}return l}return n;var c},this.setDebug=function(e){t=e}}}class i{exportName;composition;life;moduleName;origin;wrappers=[]}const c=/^(node:)?(@?[A-Za-z0-9_-]+\/?[A-Za-z0-9_-]*)(([.#])?([A-Za-z0-9_]*)((\$)?(\$)?)?)?(\(([A-Za-z0-9_,]*)\))?$/;class a{canParse(){return!0}parse(t){const o=new i;o.origin=t;const n=c.exec(t);if(n&&(o.isNodeModule=Boolean(n[1]),o.moduleName=n[2].replace(/^node:/,""),"."===n[4]||"#"===n[4]?"$"===n[6]||"$$"===n[6]?(o.composition=e.CF,o.exportName=n[5],o.life="$"===n[6]?e.LS:e.LI):(o.composition=e.CA,o.life=e.LS,o.exportName=""!==n[5]?n[5]:"default"):"$"===n[6]||"$$"===n[6]?(o.composition=e.CF,o.exportName="default",o.life="$"===n[6]?e.LS:e.LI):(o.composition=void 0,o.exportName=void 0,o.life=void 0),n[10]&&(o.wrappers=n[10].split(","))),o.composition===e.CA&&o.life===e.LI)throw new Error(`Export is not a function and should be used as a singleton only: '${o.origin}'.`);return o}}class l{constructor(){let e=new a;const t=[];this.addChunk=function(e){t.push(e)},this.parse=function(o){let n;for(const e of t)if(e.canParse(o)){n=e.parse(o);break}return n||(n=e?.parse(o)),n},this.setDefaultChunk=function(t){e=t}}}class u{constructor(){const e=[];this.addChunk=function(t){e.push(t)},this.modify=function(t,o){let n=t;for(const s of e)n=s.modify(n,t,o);return n}}}class f{constructor(){const e=[];this.addChunk=function(t){e.push(t)},this.modify=async function(t,o,n){let s=t;for(const t of e)s=t.modify(s,o,n),s instanceof Promise&&(s=await s);return s}}}const d="ext",p="ns",h="root";class m{constructor(){const e={};let t=!1,o=[],n="/";this.addNamespaceRoot=function(n,s,r){const i=(t?s.replace(/^\\/,""):s).replace(/\\/g,"/"),c=t?`file://${i}`:i;e[n]={[d]:r??"js",[p]:n,[h]:c},o=Object.keys(e).sort(((e,t)=>t.localeCompare(e)))},this.resolve=function(t){let s,r,i;for(i of o)if(t.startsWith(i)){s=e[i][h],r=e[i].ext;break}if(s&&r){let e=t.replace(i,"");0===e.indexOf("_")&&(e=e.replace("_",""));const o=e.replaceAll("_",n);return`${s}${n}${o}.${r}`}return t},this.setWindowsEnv=function(e=!0){t=e,n=e?"\\":"/"}}}function $(e){return`${e.moduleName}#${e.exportName}`}class g{constructor(){let t=new r,o=!1,n=new l,s=new f,i=new u,c=!1;const a={},d={};let p=new m;function h(){o&&console.log(...arguments)}this.get=async function(o,r=[]){if(h(`Object '${o}' is requested.`),o===e.ID||o===e.ID_FQN)return h("Container itself is returned."),d[e.ID];const c=n.parse(o),l=i.modify(c,r);if(l.life===e.LS){const e=$(l);if(d[e])return h(`Existing singleton '${e}' is returned.`),d[e]}let u;a[l.moduleName]||(h(`ES6 module '${l.moduleName}' is not resolved yet`),a[l.moduleName]=p.resolve(l.moduleName));const f=a[l.moduleName];try{u=await import(f),h(`ES6 module '${l.moduleName}' is loaded from '${f}'.`)}catch(e){throw console.error(e?.message,`Object key: "${o}".`,`Path: "${f}".`,`Stack: ${JSON.stringify(r)}`),e}let m=await t.create(l,u,r,this);var g;if(null===(g=m)||"object"!=typeof g&&"function"!=typeof g||"[object Module]"===Object.prototype.toString.call(g)||Object.isFrozen(g)||Object.freeze(m),m=await s.modify(m,l,r),h(`Object '${o}' is created.`),l.life===e.LS){const e=$(l);d[e]=m,h(`Object '${o}' is saved as singleton.`)}return m},this.enableTestMode=function(){c=!0,h("Test mode enabled")},this.getParser=()=>n,this.getPreProcessor=()=>i,this.getPostProcessor=()=>s,this.getResolver=()=>p,this.register=function(t,o){if(!c)throw new Error("Use enableTestMode() to allow it");if(!t||!o)throw new Error("Both params are required");const s=n.parse(t);if(s.life!==e.LS)throw new Error(`Only singletons can be registered: '${t}'`);const r=$(s);if(d[r])throw new Error(`'${t}' is already registered`);d[r]=o,h(`'${t}' is registered`)},this.setDebug=function(e){o=e,t.setDebug(e)},this.setParser=e=>n=e,this.setPreProcessor=e=>i=e,this.setPostProcessor=e=>s=e,this.setResolver=e=>p=e,d[e.ID]=this}}export{g as default};
+var e={CA:"A",CF:"F",ID:"container",ID_FQN:"TeqFw_Di_Container$",LI:"I",LS:"S",isClass(e){const t=Object.getOwnPropertyDescriptor(e,"prototype");return t&&!t.writable}};const t=/(function)*\s*\w*\s*\(\s*\{([^}]*)}/s,o=/constructor\s*\(\s*\{([^}]*)}/s;function n(e){const t=[];try{const o=new Function(`{${e}}`,"return");o(new Proxy({},{get:(e,o)=>t.push(o)}))}catch(t){throw new Error(`Cannot analyze the deps specification:${e}\n\nPlease, be sure that spec does not contain extra ')' in a comments.\n\nError: ${t}`)}return t}function s(s){return"function"==typeof s?e.isClass(s)?function(e){const t=[],s=e.toString(),r=o.exec(s);return r&&t.push(...n(r[1])),t}(s):function(e){const o=[],s=e.toString(),r=t.exec(s);return r&&o.push(...n(r[2])),o}(s):[]}class r{constructor(){let t=!1;this.create=async function(o,n,r,i){if(r.includes(o.origin))throw new Error(`Circular dependency for '${o.origin}'. Parents are: ${JSON.stringify(r)}`);if(o.exportName){const a=[...r,o.origin],{[o.exportName]:l}=n;if(o.composition===e.CF){if("function"==typeof l){const n=s(l);n.length&&(c=`Deps for object '${o.origin}' are: ${JSON.stringify(n)}`,t&&console.log(c));const r={};for(const e of n)r[e]=await i.get(e,a);const u=e.isClass(l)?new l(r):l(r);return u instanceof Promise?await u:u}return Object.assign({},l)}return l}return n;var c},this.setDebug=function(e){t=e}}}class i{exportName;composition;isNodeModule;life;moduleName;origin;wrappers=[]}const c=/^(node:)?(@?[A-Za-z0-9_-]+\/?[A-Za-z0-9_-]*)(([.#])?([A-Za-z0-9_]*)((\$)?(\$)?)?)?(\(([A-Za-z0-9_,]*)\))?$/;class a{canParse(){return!0}parse(t){const o=new i;o.origin=t;const n=c.exec(t);if(n&&(o.isNodeModule=Boolean(n[1]),o.moduleName=n[2].replace(/^node:/,""),"."===n[4]||"#"===n[4]?"$"===n[6]||"$$"===n[6]?(o.composition=e.CF,o.exportName=n[5],o.life="$"===n[6]?e.LS:e.LI):(o.composition=e.CA,o.life=e.LS,o.exportName=""!==n[5]?n[5]:"default"):"$"===n[6]||"$$"===n[6]?(o.composition=e.CF,o.exportName="default",o.life="$"===n[6]?e.LS:e.LI):(o.composition=void 0,o.exportName=void 0,o.life=void 0),n[10]&&(o.wrappers=n[10].split(","))),o.composition===e.CA&&o.life===e.LI)throw new Error(`Export is not a function and should be used as a singleton only: '${o.origin}'.`);return o}}class l{constructor(){let e=new a;const t=[];this.addChunk=function(e){t.push(e)},this.parse=function(o){let n;for(const e of t)if(e.canParse(o)){n=e.parse(o);break}return n||(n=e?.parse(o)),n},this.setDefaultChunk=function(t){e=t}}}class u{constructor(){const e=[];this.addChunk=function(t){e.push(t)},this.modify=function(t,o){let n=t;for(const s of e)n=s.modify(n,t,o);return n}}}class f{constructor(){const e=[];this.addChunk=function(t){e.push(t)},this.modify=async function(t,o,n){let s=t;for(const t of e)s=t.modify(s,o,n),s instanceof Promise&&(s=await s);return s}}}const d="ext",p="ns",h="root";class m{constructor(){const e={};let t=!1,o=[],n="/";this.addNamespaceRoot=function(n,s,r){const i=(t?s.replace(/^\\/,""):s).replace(/\\/g,"/"),c=t?`file://${i}`:i;e[n]={[d]:r??"js",[p]:n,[h]:c},o=Object.keys(e).sort(((e,t)=>t.localeCompare(e)))},this.resolve=function(t){let s,r,i;for(i of o)if(t.startsWith(i)){s=e[i][h],r=e[i].ext;break}if(s&&r){let e=t.replace(i,"");0===e.indexOf("_")&&(e=e.replace("_",""));const o=e.replaceAll("_",n);return`${s}${n}${o}.${r}`}return t},this.setWindowsEnv=function(e=!0){t=e,n=e?"\\":"/"}}}function g(e){return`${e.moduleName}#${e.exportName}`}class ${constructor(){let t=new r,o=!1,n=new l,s=new f,i=new u,c=!1;const a={},d={},p={};let h=new m;function $(){o&&console.log(...arguments)}this.get=async function(o,r=[]){if($(`Object '${o}' is requested.`),o===e.ID||o===e.ID_FQN)return $("Container itself is returned."),d[e.ID];const l=n.parse(o),u=i.modify(l,r);if(u.life===e.LS){const e=g(u);if(d[e])return $(`Existing singleton '${e}' is returned.`),d[e]}if(u.isNodeModule&&c){const e=u.origin;if(p[e])return $(`Existing nodejs lib '${e}' is returned.`),p[e]}let f;a[u.moduleName]||($(`ES6 module '${u.moduleName}' is not resolved yet`),a[u.moduleName]=h.resolve(u.moduleName));const m=a[u.moduleName];try{f=await import(m),$(`ES6 module '${u.moduleName}' is loaded from '${m}'.`)}catch(e){throw console.error(e?.message,`Object key: "${o}".`,`Path: "${m}".`,`Stack: ${JSON.stringify(r)}`),e}let w=await t.create(u,f,r,this);var y;if(null===(y=w)||"object"!=typeof y&&"function"!=typeof y||"[object Module]"===Object.prototype.toString.call(y)||Object.isFrozen(y)||Object.freeze(w),w=await s.modify(w,u,r),$(`Object '${o}' is created.`),u.life===e.LS){const e=g(u);d[e]=w,$(`Object '${o}' is saved as singleton.`)}return w},this.enableTestMode=function(){c=!0,$("Test mode enabled")},this.getParser=()=>n,this.getPreProcessor=()=>i,this.getPostProcessor=()=>s,this.getResolver=()=>h,this.register=function(t,o){if(!c)throw new Error("Use enableTestMode() to allow it");if(!t||!o)throw new Error("Both params are required");const s=n.parse(t);if(s.life!==e.LS&&!s.isNodeModule)throw new Error(`Only node modules & singletons can be registered: '${t}'`);if(s.life===e.LS){const e=g(s);if(d[e])throw new Error(`'${t}' is already registered`);d[e]=o}else if(s.isNodeModule){const e=s.origin;if(p[e])throw new Error(`'${t}' is already registered`);p[e]=o}$(`'${t}' is registered`)},this.setDebug=function(e){o=e,t.setDebug(e)},this.setParser=e=>n=e,this.setPreProcessor=e=>i=e,this.setPostProcessor=e=>s=e,this.setResolver=e=>h=e,d[e.ID]=this}}export{$ as default};

package/dist/umd.js

@@ -1 +1 @@
-!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?module.exports=t():"function"==typeof define&&define.amd?define(t):(e="undefined"!=typeof globalThis?globalThis:e||self).TeqFw_Di_Container=t()}(this,(function(){"use strict";var e={CA:"A",CF:"F",ID:"container",ID_FQN:"TeqFw_Di_Container$",LI:"I",LS:"S",isClass(e){const t=Object.getOwnPropertyDescriptor(e,"prototype");return t&&!t.writable}};const t=/(function)*\s*\w*\s*\(\s*\{([^}]*)}/s,o=/constructor\s*\(\s*\{([^}]*)}/s;function n(e){const t=[];try{const o=new Function(`{${e}}`,"return");o(new Proxy({},{get:(e,o)=>t.push(o)}))}catch(t){throw new Error(`Cannot analyze the deps specification:${e}\n\nPlease, be sure that spec does not contain extra ')' in a comments.\n\nError: ${t}`)}return t}function s(s){return"function"==typeof s?e.isClass(s)?function(e){const t=[],s=e.toString(),r=o.exec(s);return r&&t.push(...n(r[1])),t}(s):function(e){const o=[],s=e.toString(),r=t.exec(s);return r&&o.push(...n(r[2])),o}(s):[]}class r{constructor(){let t=!1;this.create=async function(o,n,r,i){if(r.includes(o.origin))throw new Error(`Circular dependency for '${o.origin}'. Parents are: ${JSON.stringify(r)}`);if(o.exportName){const a=[...r,o.origin],{[o.exportName]:u}=n;if(o.composition===e.CF){if("function"==typeof u){const n=s(u);n.length&&(c=`Deps for object '${o.origin}' are: ${JSON.stringify(n)}`,t&&console.log(c));const r={};for(const e of n)r[e]=await i.get(e,a);const l=e.isClass(u)?new u(r):u(r);return l instanceof Promise?await l:l}return Object.assign({},u)}return u}return n;var c},this.setDebug=function(e){t=e}}}class i{exportName;composition;life;moduleName;origin;wrappers=[]}const c=/^(node:)?(@?[A-Za-z0-9_-]+\/?[A-Za-z0-9_-]*)(([.#])?([A-Za-z0-9_]*)((\$)?(\$)?)?)?(\(([A-Za-z0-9_,]*)\))?$/;class a{canParse(){return!0}parse(t){const o=new i;o.origin=t;const n=c.exec(t);if(n&&(o.isNodeModule=Boolean(n[1]),o.moduleName=n[2].replace(/^node:/,""),"."===n[4]||"#"===n[4]?"$"===n[6]||"$$"===n[6]?(o.composition=e.CF,o.exportName=n[5],o.life="$"===n[6]?e.LS:e.LI):(o.composition=e.CA,o.life=e.LS,o.exportName=""!==n[5]?n[5]:"default"):"$"===n[6]||"$$"===n[6]?(o.composition=e.CF,o.exportName="default",o.life="$"===n[6]?e.LS:e.LI):(o.composition=void 0,o.exportName=void 0,o.life=void 0),n[10]&&(o.wrappers=n[10].split(","))),o.composition===e.CA&&o.life===e.LI)throw new Error(`Export is not a function and should be used as a singleton only: '${o.origin}'.`);return o}}class u{constructor(){let e=new a;const t=[];this.addChunk=function(e){t.push(e)},this.parse=function(o){let n;for(const e of t)if(e.canParse(o)){n=e.parse(o);break}return n||(n=e?.parse(o)),n},this.setDefaultChunk=function(t){e=t}}}class l{constructor(){const e=[];this.addChunk=function(t){e.push(t)},this.modify=function(t,o){let n=t;for(const s of e)n=s.modify(n,t,o);return n}}}class f{constructor(){const e=[];this.addChunk=function(t){e.push(t)},this.modify=async function(t,o,n){let s=t;for(const t of e)s=t.modify(s,o,n),s instanceof Promise&&(s=await s);return s}}}const d="ext",p="ns",h="root";class m{constructor(){const e={};let t=!1,o=[],n="/";this.addNamespaceRoot=function(n,s,r){const i=(t?s.replace(/^\\/,""):s).replace(/\\/g,"/"),c=t?`file://${i}`:i;e[n]={[d]:r??"js",[p]:n,[h]:c},o=Object.keys(e).sort(((e,t)=>t.localeCompare(e)))},this.resolve=function(t){let s,r,i;for(i of o)if(t.startsWith(i)){s=e[i][h],r=e[i].ext;break}if(s&&r){let e=t.replace(i,"");0===e.indexOf("_")&&(e=e.replace("_",""));const o=e.replaceAll("_",n);return`${s}${n}${o}.${r}`}return t},this.setWindowsEnv=function(e=!0){t=e,n=e?"\\":"/"}}}function g(e){return`${e.moduleName}#${e.exportName}`}return class{constructor(){let t=new r,o=!1,n=new u,s=new f,i=new l,c=!1;const a={},d={};let p=new m;function h(){o&&console.log(...arguments)}this.get=async function(o,r=[]){if(h(`Object '${o}' is requested.`),o===e.ID||o===e.ID_FQN)return h("Container itself is returned."),d[e.ID];const c=n.parse(o),u=i.modify(c,r);if(u.life===e.LS){const e=g(u);if(d[e])return h(`Existing singleton '${e}' is returned.`),d[e]}let l;a[u.moduleName]||(h(`ES6 module '${u.moduleName}' is not resolved yet`),a[u.moduleName]=p.resolve(u.moduleName));const f=a[u.moduleName];try{l=await import(f),h(`ES6 module '${u.moduleName}' is loaded from '${f}'.`)}catch(e){throw console.error(e?.message,`Object key: "${o}".`,`Path: "${f}".`,`Stack: ${JSON.stringify(r)}`),e}let m=await t.create(u,l,r,this);var w;if(null===(w=m)||"object"!=typeof w&&"function"!=typeof w||"[object Module]"===Object.prototype.toString.call(w)||Object.isFrozen(w)||Object.freeze(m),m=await s.modify(m,u,r),h(`Object '${o}' is created.`),u.life===e.LS){const e=g(u);d[e]=m,h(`Object '${o}' is saved as singleton.`)}return m},this.enableTestMode=function(){c=!0,h("Test mode enabled")},this.getParser=()=>n,this.getPreProcessor=()=>i,this.getPostProcessor=()=>s,this.getResolver=()=>p,this.register=function(t,o){if(!c)throw new Error("Use enableTestMode() to allow it");if(!t||!o)throw new Error("Both params are required");const s=n.parse(t);if(s.life!==e.LS)throw new Error(`Only singletons can be registered: '${t}'`);const r=g(s);if(d[r])throw new Error(`'${t}' is already registered`);d[r]=o,h(`'${t}' is registered`)},this.setDebug=function(e){o=e,t.setDebug(e)},this.setParser=e=>n=e,this.setPreProcessor=e=>i=e,this.setPostProcessor=e=>s=e,this.setResolver=e=>p=e,d[e.ID]=this}}}));
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?module.exports=t():"function"==typeof define&&define.amd?define(t):(e="undefined"!=typeof globalThis?globalThis:e||self).TeqFw_Di_Container=t()}(this,(function(){"use strict";var e={CA:"A",CF:"F",ID:"container",ID_FQN:"TeqFw_Di_Container$",LI:"I",LS:"S",isClass(e){const t=Object.getOwnPropertyDescriptor(e,"prototype");return t&&!t.writable}};const t=/(function)*\s*\w*\s*\(\s*\{([^}]*)}/s,o=/constructor\s*\(\s*\{([^}]*)}/s;function n(e){const t=[];try{const o=new Function(`{${e}}`,"return");o(new Proxy({},{get:(e,o)=>t.push(o)}))}catch(t){throw new Error(`Cannot analyze the deps specification:${e}\n\nPlease, be sure that spec does not contain extra ')' in a comments.\n\nError: ${t}`)}return t}function s(s){return"function"==typeof s?e.isClass(s)?function(e){const t=[],s=e.toString(),r=o.exec(s);return r&&t.push(...n(r[1])),t}(s):function(e){const o=[],s=e.toString(),r=t.exec(s);return r&&o.push(...n(r[2])),o}(s):[]}class r{constructor(){let t=!1;this.create=async function(o,n,r,i){if(r.includes(o.origin))throw new Error(`Circular dependency for '${o.origin}'. Parents are: ${JSON.stringify(r)}`);if(o.exportName){const a=[...r,o.origin],{[o.exportName]:l}=n;if(o.composition===e.CF){if("function"==typeof l){const n=s(l);n.length&&(c=`Deps for object '${o.origin}' are: ${JSON.stringify(n)}`,t&&console.log(c));const r={};for(const e of n)r[e]=await i.get(e,a);const u=e.isClass(l)?new l(r):l(r);return u instanceof Promise?await u:u}return Object.assign({},l)}return l}return n;var c},this.setDebug=function(e){t=e}}}class i{exportName;composition;isNodeModule;life;moduleName;origin;wrappers=[]}const c=/^(node:)?(@?[A-Za-z0-9_-]+\/?[A-Za-z0-9_-]*)(([.#])?([A-Za-z0-9_]*)((\$)?(\$)?)?)?(\(([A-Za-z0-9_,]*)\))?$/;class a{canParse(){return!0}parse(t){const o=new i;o.origin=t;const n=c.exec(t);if(n&&(o.isNodeModule=Boolean(n[1]),o.moduleName=n[2].replace(/^node:/,""),"."===n[4]||"#"===n[4]?"$"===n[6]||"$$"===n[6]?(o.composition=e.CF,o.exportName=n[5],o.life="$"===n[6]?e.LS:e.LI):(o.composition=e.CA,o.life=e.LS,o.exportName=""!==n[5]?n[5]:"default"):"$"===n[6]||"$$"===n[6]?(o.composition=e.CF,o.exportName="default",o.life="$"===n[6]?e.LS:e.LI):(o.composition=void 0,o.exportName=void 0,o.life=void 0),n[10]&&(o.wrappers=n[10].split(","))),o.composition===e.CA&&o.life===e.LI)throw new Error(`Export is not a function and should be used as a singleton only: '${o.origin}'.`);return o}}class l{constructor(){let e=new a;const t=[];this.addChunk=function(e){t.push(e)},this.parse=function(o){let n;for(const e of t)if(e.canParse(o)){n=e.parse(o);break}return n||(n=e?.parse(o)),n},this.setDefaultChunk=function(t){e=t}}}class u{constructor(){const e=[];this.addChunk=function(t){e.push(t)},this.modify=function(t,o){let n=t;for(const s of e)n=s.modify(n,t,o);return n}}}class f{constructor(){const e=[];this.addChunk=function(t){e.push(t)},this.modify=async function(t,o,n){let s=t;for(const t of e)s=t.modify(s,o,n),s instanceof Promise&&(s=await s);return s}}}const d="ext",p="ns",h="root";class m{constructor(){const e={};let t=!1,o=[],n="/";this.addNamespaceRoot=function(n,s,r){const i=(t?s.replace(/^\\/,""):s).replace(/\\/g,"/"),c=t?`file://${i}`:i;e[n]={[d]:r??"js",[p]:n,[h]:c},o=Object.keys(e).sort(((e,t)=>t.localeCompare(e)))},this.resolve=function(t){let s,r,i;for(i of o)if(t.startsWith(i)){s=e[i][h],r=e[i].ext;break}if(s&&r){let e=t.replace(i,"");0===e.indexOf("_")&&(e=e.replace("_",""));const o=e.replaceAll("_",n);return`${s}${n}${o}.${r}`}return t},this.setWindowsEnv=function(e=!0){t=e,n=e?"\\":"/"}}}function g(e){return`${e.moduleName}#${e.exportName}`}return class{constructor(){let t=new r,o=!1,n=new l,s=new f,i=new u,c=!1;const a={},d={},p={};let h=new m;function w(){o&&console.log(...arguments)}this.get=async function(o,r=[]){if(w(`Object '${o}' is requested.`),o===e.ID||o===e.ID_FQN)return w("Container itself is returned."),d[e.ID];const l=n.parse(o),u=i.modify(l,r);if(u.life===e.LS){const e=g(u);if(d[e])return w(`Existing singleton '${e}' is returned.`),d[e]}if(u.isNodeModule&&c){const e=u.origin;if(p[e])return w(`Existing nodejs lib '${e}' is returned.`),p[e]}let f;a[u.moduleName]||(w(`ES6 module '${u.moduleName}' is not resolved yet`),a[u.moduleName]=h.resolve(u.moduleName));const m=a[u.moduleName];try{f=await import(m),w(`ES6 module '${u.moduleName}' is loaded from '${m}'.`)}catch(e){throw console.error(e?.message,`Object key: "${o}".`,`Path: "${m}".`,`Stack: ${JSON.stringify(r)}`),e}let $=await t.create(u,f,r,this);var y;if(null===(y=$)||"object"!=typeof y&&"function"!=typeof y||"[object Module]"===Object.prototype.toString.call(y)||Object.isFrozen(y)||Object.freeze($),$=await s.modify($,u,r),w(`Object '${o}' is created.`),u.life===e.LS){const e=g(u);d[e]=$,w(`Object '${o}' is saved as singleton.`)}return $},this.enableTestMode=function(){c=!0,w("Test mode enabled")},this.getParser=()=>n,this.getPreProcessor=()=>i,this.getPostProcessor=()=>s,this.getResolver=()=>h,this.register=function(t,o){if(!c)throw new Error("Use enableTestMode() to allow it");if(!t||!o)throw new Error("Both params are required");const s=n.parse(t);if(s.life!==e.LS&&!s.isNodeModule)throw new Error(`Only node modules & singletons can be registered: '${t}'`);if(s.life===e.LS){const e=g(s);if(d[e])throw new Error(`'${t}' is already registered`);d[e]=o}else if(s.isNodeModule){const e=s.origin;if(p[e])throw new Error(`'${t}' is already registered`);p[e]=o}w(`'${t}' is registered`)},this.setDebug=function(e){o=e,t.setDebug(e)},this.setParser=e=>n=e,this.setPreProcessor=e=>i=e,this.setPostProcessor=e=>s=e,this.setResolver=e=>h=e,d[e.ID]=this}}}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teqfw/di",
-  "version": "0.34.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/Container.js

@@ -58,6 +58,12 @@ export default class TeqFw_Di_Container {
          * @type {Object<string, object>}
          */
         const _regSingles = {};
+        /**
+         * Registry to store mocks for Node.js libs in the Test mode.
+         * @type {Object<string, object>}
+         */
+        const _regTestNodeLibs = {};
+
         let _resolver = new Resolver();
 
         // FUNCS
@@ -71,10 +77,7 @@ export default class TeqFw_Di_Container {
         this.get = async function (depId, stack = []) {
             log(`Object '${depId}' is requested.`);
             // return the container itself if requested
-            if (
-                (depId === Defs.ID) ||
-                (depId === Defs.ID_FQN)
-            ) {
+            if ((depId === Defs.ID) || (depId === Defs.ID_FQN)) {
                 log('Container itself is returned.');
                 return _regSingles[Defs.ID];
             }
@@ -90,6 +93,14 @@ export default class TeqFw_Di_Container {
                     return _regSingles[singleId];
                 }
             }
+            // return existing node lib in the Test mode
+            if (key.isNodeModule && _testMode) {
+                const nodeId = key.origin;
+                if (_regTestNodeLibs[nodeId]) {
+                    log(`Existing nodejs lib '${nodeId}' is returned.`);
+                    return _regTestNodeLibs[nodeId];
+                }
+            }
             // resolve a path to es6 module if not resolved before
             if (!_regPaths[key.moduleName]) {
                 log(`ES6 module '${key.moduleName}' is not resolved yet`);
@@ -104,12 +115,7 @@ export default class TeqFw_Di_Container {
                 module = await import(path);
                 log(`ES6 module '${key.moduleName}' is loaded from '${path}'.`);
             } catch (e) {
-                console.error(
-                    e?.message,
-                    `Object key: "${depId}".`,
-                    `Path: "${path}".`,
-                    `Stack: ${JSON.stringify(stack)}`
-                );
+                console.error(e?.message, `Object key: "${depId}".`, `Path: "${path}".`, `Stack: ${JSON.stringify(stack)}`);
                 throw e;
             }
             // create an object using the composer, then modify it in post-processor
@@ -151,21 +157,22 @@ export default class TeqFw_Di_Container {
          * @param {object} obj - The object to register.
          */
         this.register = function (depId, obj) {
-            if (!_testMode)
-                throw new Error('Use enableTestMode() to allow it');
+            if (!_testMode) throw new Error('Use enableTestMode() to allow it');
 
-            if (!depId || !obj)
-                throw new Error('Both params are required');
+            if (!depId || !obj) throw new Error('Both params are required');
 
             const key = _parser.parse(depId);
-            if (key.life !== Defs.LS)
-                throw new Error(`Only singletons can be registered: '${depId}'`);
-
-            const singleId = getSingletonId(key);
-            if (_regSingles[singleId])
-                throw new Error(`'${depId}' is already registered`);
+            if ((key.life !== Defs.LS) && !key.isNodeModule) throw new Error(`Only node modules & singletons can be registered: '${depId}'`);
+            if (key.life === Defs.LS) {
+                const singleId = getSingletonId(key);
+                if (_regSingles[singleId]) throw new Error(`'${depId}' is already registered`);
+                _regSingles[singleId] = obj;
+            } else if (key.isNodeModule) {
+                const nodeId = key.origin;
+                if (_regTestNodeLibs[nodeId]) throw new Error(`'${depId}' is already registered`);
+                _regTestNodeLibs[nodeId] = obj;
+            }
 
-            _regSingles[singleId] = obj;
             log(`'${depId}' is registered`);
         };
 

package/src/DepId.js

@@ -17,6 +17,11 @@ export default class TeqFw_Di_DepId {
      * @type {string}
      */
     composition;
+    /**
+     * Defines if the dependency is a Node.js module.
+     * @type {boolean}
+     */
+    isNodeModule;
     /**
      * Defines the lifecycle of the resolved dependency:
      * - 'S' (Singleton): A single instance is created and reused.

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;
+        };
+    }
+}