@teqfw/di 0.30.0 → 0.30.2

package/README.md

@@ -1,16 +1,69 @@
 # @teqfw/di
 
-A Dependency Injection container for regular JavaScript is provided, which can be used in both browser and Node.js
-applications with JS, and in Node.js only with TS.
+![npms.io](https://img.shields.io/npm/dm/@teqfw/di)
+![jsdelivr](https://img.shields.io/jsdelivr/npm/hm/@teqfw/di)
 
-**This library exclusively supports ES6 modules.**
+`@teqfw/di` is a lightweight dependency injection container for standard JavaScript, enabling late binding of code
+objects with minimal manual configuration. It integrates smoothly in both browser and Node.js environments, supporting
+flexibility, modularity, and easier testing for your applications.
 
-The primary objective of this library is the late binding for code objects with minimal manual configuration for the
-object container. All linking instructions are encapsulated within the dependency identifiers and used in constructors
-or factory functions (the constructor injection scheme):
+Unlike typical object containers, `@teqfw/di` requires no manual registration of objects, instead mapping dependency IDs
+directly to their source paths for greater simplicity.
 
-```js
-export default class App_Main {
+**This library is specifically optimized for ES6 modules, ensuring top performance and compatibility. It does not
+support CommonJS, AMD, UMD, or other module formats.**
+
+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.
+
+## Samples
+
+Explore `@teqfw/di` in action through the following demo applications:
+
+- [demo-di-app](https://flancer64.github.io/demo-di-app/): A simple demonstration of dependency injection with
+  `@teqfw/di`.
+- [demo-wa-esm-openai](https://github.com/flancer64/demo-wa-esm-openai): Integrates OpenAI with ES6 modules.
+- [pwa-wallet](https://github.com/flancer64/pwa-wallet): A progressive web application wallet showcasing the library's
+  modularity.
+- [spa-remote-console](https://github.com/flancer64/spa-remote-console): Demonstrates remote console functionality in a
+  single-page application.
+- [demo-webauthn-pubkey](https://github.com/flancer64/demo-webauthn-pubkey): Uses Web Authentication (WebAuthn) with
+  public key credentials.
+- [tg-bot-habr-demo-grammy](https://github.com/flancer64/tg-bot-habr-demo-grammy): A Telegram bot demo built with the
+  grammY library.
+
+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,
+configuring the container, and finally retrieving the main object with injected dependencies.
+
+### Step 1: Organize File Structure
+
+Here’s an example of how files might be organized in a project. This structure can vary depending on your project needs,
+as the container can be configured to work with any layout (e.g., within `/home/user/project/`):
+
+  ```
+  ./src/
+      ./Service/
+          ./Customer.js
+          ./Sale.js
+      ./Config.js
+      ./Logger.js
+      ./Main.js
+  ```
+
+### Step 2: Declare Dependencies
+
+In your code, declare dependencies by defining 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.
+
+  ```js
+  export default class App_Main {
     constructor(
         {
             App_Config$: config,
@@ -18,91 +71,175 @@ export default class App_Main {
             App_Service_Customer$: servCustomer,
             App_Service_Sale$: servSale,
         }
-    ) { ... }
-
+    ) { /* ... */ }
 }
-```
+  ```
 
-The files corresponded to this case:
+### Step 3: Configure the Container
 
-```
-./src/
-    ./Service/
-        ./Customer.js
-        ./Sale.js
-    ./Config.js
-    ./Logger.js
-    ./Main.js
-```
+Next, set up the container and configure it to use the correct namespace and path for your dependencies:
 
-Just set up a mapping rules for the container:
-
-```js
-import Container from '@teqfw/di';
+  ```js
+  import Container from '@teqfw/di';
 
+// Create a new instance of the container
 const container = new Container();
+
+// Get the resolver from the container
 const resolver = container.getResolver();
-resolver.addNamespaceRoot('App_', '/path/to/src'); // or 'https://cdn.jsdelivr.net/npm/@vendor/pkg@latest/src'
+
+// Define the namespace root for dependencies, allowing the container to resolve identifiers like 'App_*'
+resolver.addNamespaceRoot('App_', '/home/user/project/src'); 
+  ```
+
+### Step 4: Retrieve the Main Object with Dependencies
+
+Finally, retrieve your main application instance. The container automatically injects all declared dependencies:
+
+  ```js
+  // Retrieve the main application instance as a singleton asynchronously
 const app = await container.get('App_Main$');
-```
+  ```
+
+## Key Benefits
+
+`@teqfw/di` offers the core functionality of any object container — creating objects and injecting dependencies — with
+extensive flexibility and configurability. This allows the library to adapt seamlessly to a wide range of project needs.
+Here’s what makes it stand out:
+
+- **Automatic Dependency Resolution**: The library simplifies managing complex objects and their dependencies by
+  automatically resolving and injecting them based on container configuration. This basic functionality works out of the
+  box but can be fully customized if needed.
+
+- **Flexible Dependency ID Configuration**: With customizable parsers and chunks, you can define unique ID schemes for
+  dependencies, making it easy to adapt the library to specific naming conventions or custom mapping rules.
+
+- **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.
+
+- **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
+  to suit more precise needs.
 
-That's all.
+- **Interfaces and Dependencies Without TypeScript**: `@teqfw/di` allows you to define interfaces using standard
+  JavaScript files with JSDoc annotations. The container supports configuring dependencies to replace interfaces with
+  project-specific implementations, offering flexibility without requiring TypeScript.
 
-## The main benefits
+- **Postprocessing for Object Customization**: Use postprocessing to add wrappers or extend created objects. This can be
+  valuable for adding factories, logging, or other behavior, tailored to each project’s requirements.
 
-* **Late Binding**: Enjoy all the typical advantages of late binding during runtime, including flexibility, testability,
-  modularity, manageability, and clear separation of concerns.
-* **Integration with ES6 Modules**: Seamlessly integrate singletons and instances based on ES6 module exports.
-* **Interface Usage in Vanilla JS**: Utilize "interfaces" in standard JavaScript, along with dependency substitution (
-  preprocessing).
-* **Object Wrapping**: Add wrappers to created objects (postprocessing) for enhanced functionality.
+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
 
-NodeJS:
+### For Node.js
 
-```shell
-$ npm i --save @teqfw/di
-```
+To install `@teqfw/di` in a Node.js environment, use the following command:
+
+  ```shell
+  $ npm install @teqfw/di
+  ```
+
+Then, import and initialize the container:
 
-Web as ESM (~5Kb):
+  ```js
+  import Container from '@teqfw/di';
+
+/** @type {TeqFw_Di_Container} */
+const container = new Container();
+  ```
 
-```html
+### For the Browser (ESM Module)
+
+To use `@teqfw/di` in a browser environment with ES modules, include it as follows (~5KB):
+
+  ```html
 
 <script type="module">
-    import {default as Container} from 'https://cdn.jsdelivr.net/npm/@teqfw/di@latest/+esm';
+    import Container from 'https://cdn.jsdelivr.net/npm/@teqfw/di@latest/+esm';
 
     /** @type {TeqFw_Di_Container} */
     const container = new Container();
-    ...
 </script>
-```
+  ```
+
+### For the Browser (UMD Module)
 
-Web as UMD (~5Kb):
+Alternatively, you can use the UMD version in the browser (~5KB):
 
-```html
+  ```html
 
 <script src="https://cdn.jsdelivr.net/npm/@teqfw/di@latest/dist/umd.js"></script>
 <script>
     const {default: Container} = window.TeqFw_Di_Container;
     /** @type {TeqFw_Di_Container} */
     const container = new Container();
-    ...
 </script>
-```
+  ```
+
+---
+
+## Using the Container
+
+### In Node.js
+
+1. **Configure Dependency Mapping**: Configure the resolver to detect the platform environment. Then, set up namespace
+   roots to map dependency IDs to their source paths.
+
+    ```js
+    import { platform } from 'node:process';
+
+    const resolver = container.getResolver();
+    resolver.setWindowsEnv(platform === 'win32'); // Adjusts for Windows environment if needed
+    resolver.addNamespaceRoot('App_', '/path/to/src');
+    ```
+
+2. **Retrieve Singleton Instances**: Retrieve the main application instance as a singleton asynchronously:
 
-## Types of Dependency ID
+    ```js
+    const app = await container.get('App_Main$');
+    ```
 
-* `App_Service`=> `import * as Service from './App/Service.js'` as ES Module
-* `App_Service.default` => `import {default} from './App/Service.js'` default export as-is
-* `App_Service.name` => `import {name} from './App/Service.js'` named export as-is
-* `App_Service$` => `import {default} from './App/Service.js'; return res ?? (res = default({...}));` as singleton for
-  container
-* `App_Service$$` => `import {default} from './App/Service.js'; return new default({...})` as instance for every
-  dep
-* `App_Service.name$` => `import {name} from './App/Service.js'; return res ?? (res = name({...}));` as singleton
-* `App_Service.name$$` => `import {name} from './App/Service.js'; const res = new name({...})` as instance
-* `...(proxy,factory,...)`: add custom wrappers on postprocessing
+### In the Browser
+
+1. **Configure Dependency Mapping**: Set up namespace roots to map dependency IDs to their source paths, using URLs as
+   needed.
+
+    ```js
+    const resolver = container.getResolver();
+    resolver.addNamespaceRoot('App_', 'https://cdn.jsdelivr.net/npm/@flancer64/demo-di-app@0.2/src'); 
+    ```
+
+2. **Retrieve Singleton Instances**: Retrieve the main application instance as a singleton asynchronously:
+
+    ```js
+    const app = await container.get('App_Main$');
+    ```
+
+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
+quick reference:
+
+| Dependency ID               | Import Style                                           | Description                                                                                           |
+|-----------------------------|--------------------------------------------------------|-------------------------------------------------------------------------------------------------------|
+| `App_Service`               | `import * as Service from './App/Service.js';`         | Imports the entire module as an ES module.                                                            |
+| `App_Service.default`       | `import {default} from './App/Service.js';`            | Imports the default export as-is.                                                                     |
+| `App_Service.name`          | `import {name} from './App/Service.js';`               | Imports a named export as-is.                                                                         |
+| `App_Service$`              | `import {default as Factory} from './App/Service.js';` | Uses default export as a singleton for the container.                                                 |
+| `App_Service$$`             | `import {default as Factory} from './App/Service.js';` | Creates a new instance from the default export for each dependency.                                   |
+| `App_Service.name$`         | `import {name} from './App/Service.js';`               | Uses a named export as a singleton.                                                                   |
+| `App_Service.name$$`        | `import {name} from './App/Service.js';`               | Creates a new instance from a named export for each dependency.                                       |
+| `App_Service.name$$(proxy)` | `import {name} from './App/Service.js';`               | Applies a custom wrapper to the created object in postprocessing, using a handler function `proxy()`. |
+
+### Example Usage
+
+Here’s an example showing a class with multiple dependencies, each using different dependency IDs:
 
 ```js
 export default class App_Main {
@@ -118,16 +255,27 @@ export default class App_Main {
             'App_Service.name(factory)': factoryToCreateInstancesFromNamedExport,
         }
     ) {
-        const {default as SrvDef, name as SrvName} = EsModule; // deconstruct the module and access the exports 
+        const {default: SrvDef, name: SrvName} = EsModule; // Deconstruct the module and access the exports 
     }
-
 }
 ```
 
-## Resume
+## Summary
+
+`@teqfw/di` is a versatile and lightweight dependency injection container tailored for modern JavaScript applications.
+With its flexible dependency mapping, customizable ID configurations, and support for dynamic object creation,
+`@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.
+
+For any questions, feedback, or collaboration opportunities, please feel free to reach out through the following
+channels:
+
+- **Website**: [wiredgeese.com](https://wiredgeese.com)
+- **LinkedIn**: [LinkedIn Profile](https://www.linkedin.com/in/aleksandrs-gusevs-011ba928/)
+
+You can also leave suggestions, feedback, and feature requests directly on GitHub by opening an issue in the repository.
 
-`@teqfw/di` offers Dependency Injection for regular JavaScript with minimal manual configuration, supporting both
-browser and Node.js environments. Its use of late binding and an object container in JavaScript applications, along with
-the ability to modify the behavior of created objects (via pseudo-interfaces and wrappers), allows you to apply
-architectural solutions from other languages (such as Java, PHP, C#) and fully harness the capabilities of npm packages
-and ES6 modules in JavaScript applications, particularly in the Node.js environment.
+Happy coding!ges and ES6 modules in JavaScript applications, especially within the Node.js environment.

package/RELEASE.md

@@ -1,5 +1,14 @@
 # @teqfw/di releases
 
+## 0.30.2
+
+* Enhanced the README with updates from ChatGPT.
+* Unified JSDoc annotations.
+
+## 0.30.1
+
+* Improve the README.
+
 ## 0.30.0
 
 * New format of the depId for default parser (`Ns_Module.export$$(post)`).

package/dist/esm.js

@@ -1 +1 @@
-var e={COMP_A:"A",COMP_F:"F",ID:"container",ID_FQN:"TeqFw_Di_Container$",LIFE_I:"I",LIFE_S:"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 s(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 n(n){return"function"==typeof n?e.isClass(n)?function(e){const t=[],n=e.toString(),r=o.exec(n);return r&&t.push(...s(r[1])),t}(n):function(e){const o=[],n=e.toString(),r=t.exec(n);return r&&o.push(...s(r[2])),o}(n):[]}class r{constructor(){let t=!1;this.create=async function(o,s,r,i){if(r.includes(o.value))throw new Error(`Circular dependency for '${o.value}'. Parents are: ${JSON.stringify(r)}`);if(o.exportName){const a=[...r,o.value],{[o.exportName]:u}=s;if(o.composition===e.COMP_F){if("function"==typeof u){const s=n(u);s.length&&(c=`Deps for object '${o.value}' are: ${JSON.stringify(s)}`,t&&console.log(c));const r={};for(const e of s)r[e]=await i.compose(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 s;var c},this.setDebug=function(e){t=e}}}class i{exportName;composition;life;moduleName;value;wrappers=[]}const c=/^((([A-Z])[A-Za-z0-9_]*)((\.)?([A-Za-z0-9_]*)((\$)?(\$)?)?)?(\(([A-Za-z0-9_,]*)\))?)$/;class a{canParse(e){return!0}parse(t){const o=new i;o.value=t;const s=c.exec(t);if(s&&(o.moduleName=s[2],"."===s[5]?"$"===s[7]||"$$"===s[7]?(o.composition=e.COMP_F,o.exportName=s[6],o.life="$"===s[7]?e.LIFE_S:e.LIFE_I):(o.composition=e.COMP_A,o.life=e.LIFE_S,o.exportName=""!==s[6]?s[6]:"default"):"$"===s[7]||"$$"===s[7]?(o.composition=e.COMP_F,o.exportName="default",o.life="$"===s[7]?e.LIFE_S:e.LIFE_I):(o.composition=void 0,o.exportName=void 0,o.life=void 0),s[11]&&(o.wrappers=s[11].split(","))),o.composition===e.COMP_A&&o.life===e.LIFE_I)throw new Error(`Export is not a function and should be used as a singleton only: '${o.value}'.`);return o}}class u{constructor(){let e=new a;const t=[];this.addChunk=function(e){t.push(e)},this.parse=function(o){let s;for(const e of t)if(e.canParse(o)){s=e.parse(o);break}return s||(s=e?.parse(o)),s},this.setDefaultChunk=function(t){e=t}}}class l{constructor(){const e=[];this.addChunk=function(t){e.push(t)},this.modify=function(t,o){let s=t;for(const n of e)s=n.modify(s,t,o);return s}}}class f{constructor(){const e=[];this.addChunk=function(t){e.push(t)},this.modify=async function(t,o,s){let n=t;for(const t of e)n=t.modify(n,o,s),n instanceof Promise&&(n=await n);return n}}}const p="ext",m="ns",d="root";class h{constructor(){const e={};let t=!1,o=[],s="/";this.addNamespaceRoot=function(s,n,r){const i=(t?n.replace(/^\\/,""):n).replace(/\\/g,"/"),c=t?`file://${i}`:i;e[s]={[p]:r??"js",[m]:s,[d]:c},o=Object.keys(e).sort(((e,t)=>t.localeCompare(e)))},this.resolve=function(t){let n,r,i;for(i of o)if(t.startsWith(i)){n=e[i][d],r=e[i].ext;break}if(n&&r){let e=t.replace(i,"");0===e.indexOf("_")&&(e=e.replace("_",""));const o=e.replaceAll("_",s);return`${n}${s}${o}.${r}`}return t},this.setWindowsEnv=function(e=!0){t=e,s=e?"\\":"/"}}}function $(e){return`${e.moduleName}#${e.exportName}`}class w{constructor(){let t=new r,o=!1,s=new u,n=new l,i=new f;const c={},a={};let p=new h;function m(){o&&console.log(...arguments)}this.get=async function(e){return this.compose(e,[])},this.compose=async function(o,r=[]){if(m(`Object '${o}' is requested.`),o===e.ID||o===e.ID_FQN)return m("Container itself is returned."),a[e.ID];const u=s.parse(o),l=n.modify(u,r);if(l.life===e.LIFE_S){const e=$(l);if(a[e])return m(`Existing singleton '${e}' is returned.`),a[e]}let f;c[l.moduleName]||(m(`ES6 module '${l.moduleName}' is not resolved yet`),c[l.moduleName]=p.resolve(l.moduleName));const d=c[l.moduleName];try{f=await import(d),m(`ES6 module '${l.moduleName}' is loaded from '${d}'.`)}catch(e){throw console.error(e?.message,`Object key: "${o}".`,`Path: "${d}".`,`Stack: ${JSON.stringify(r)}`),e}let h=await t.create(l,f,r,this);if(h=await i.modify(h,l,r),m(`Object '${o}' is created.`),l.life===e.LIFE_S){const e=$(l);a[e]=h,m(`Object '${o}' is saved as singleton.`)}return h},this.getParser=()=>s,this.getPreProcessor=()=>n,this.getPostProcessor=()=>i,this.getResolver=()=>p,this.setDebug=function(e){o=e,t.setDebug(e)},this.setParser=e=>s=e,this.setPreProcessor=e=>n=e,this.setPostProcessor=e=>i=e,this.setResolver=e=>p=e,a[e.ID]=this}}export{w as default};
+var e={COMP_A:"A",COMP_F:"F",ID:"container",ID_FQN:"TeqFw_Di_Container$",LIFE_I:"I",LIFE_S:"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 s(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 n(n){return"function"==typeof n?e.isClass(n)?function(e){const t=[],n=e.toString(),r=o.exec(n);return r&&t.push(...s(r[1])),t}(n):function(e){const o=[],n=e.toString(),r=t.exec(n);return r&&o.push(...s(r[2])),o}(n):[]}class r{constructor(){let t=!1;this.create=async function(o,s,r,i){if(r.includes(o.value))throw new Error(`Circular dependency for '${o.value}'. Parents are: ${JSON.stringify(r)}`);if(o.exportName){const a=[...r,o.value],{[o.exportName]:u}=s;if(o.composition===e.COMP_F){if("function"==typeof u){const s=n(u);s.length&&(c=`Deps for object '${o.value}' are: ${JSON.stringify(s)}`,t&&console.log(c));const r={};for(const e of s)r[e]=await i.compose(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 s;var c},this.setDebug=function(e){t=e}}}class i{exportName;composition;life;moduleName;value;wrappers=[]}const c=/^((([A-Z])[A-Za-z0-9_]*)((\.)?([A-Za-z0-9_]*)((\$)?(\$)?)?)?(\(([A-Za-z0-9_,]*)\))?)$/;class a{canParse(e){return!0}parse(t){const o=new i;o.value=t;const s=c.exec(t);if(s&&(o.moduleName=s[2],"."===s[5]?"$"===s[7]||"$$"===s[7]?(o.composition=e.COMP_F,o.exportName=s[6],o.life="$"===s[7]?e.LIFE_S:e.LIFE_I):(o.composition=e.COMP_A,o.life=e.LIFE_S,o.exportName=""!==s[6]?s[6]:"default"):"$"===s[7]||"$$"===s[7]?(o.composition=e.COMP_F,o.exportName="default",o.life="$"===s[7]?e.LIFE_S:e.LIFE_I):(o.composition=void 0,o.exportName=void 0,o.life=void 0),s[11]&&(o.wrappers=s[11].split(","))),o.composition===e.COMP_A&&o.life===e.LIFE_I)throw new Error(`Export is not a function and should be used as a singleton only: '${o.value}'.`);return o}}class u{constructor(){let e=new a;const t=[];this.addChunk=function(e){t.push(e)},this.parse=function(o){let s;for(const e of t)if(e.canParse(o)){s=e.parse(o);break}return s||(s=e?.parse(o)),s},this.setDefaultChunk=function(t){e=t}}}class l{constructor(){const e=[];this.addChunk=function(t){e.push(t)},this.modify=function(t,o){let s=t;for(const n of e)s=n.modify(s,t,o);return s}}}class f{constructor(){const e=[];this.addChunk=function(t){e.push(t)},this.modify=async function(t,o,s){let n=t;for(const t of e)n=t.modify(n,o,s),n instanceof Promise&&(n=await n);return n}}}const p="root";class m{constructor(){const e={};let t=!1,o=[],s="/";this.addNamespaceRoot=function(s,n,r){const i=(t?n.replace(/^\\/,""):n).replace(/\\/g,"/"),c=t?`file://${i}`:i;e[s]={ext:r??"js",ns:s,[p]:c},o=Object.keys(e).sort(((e,t)=>t.localeCompare(e)))},this.resolve=function(t){let n,r,i;for(i of o)if(t.startsWith(i)){n=e[i][p],r=e[i].ext;break}if(n&&r){let e=t.replace(i,"");0===e.indexOf("_")&&(e=e.replace("_",""));const o=e.replaceAll("_",s);return`${n}${s}${o}.${r}`}return t},this.setWindowsEnv=function(e=!0){t=e,s=e?"\\":"/"}}}function d(e){return`${e.moduleName}#${e.exportName}`}class h{constructor(){let t=new r,o=!1,s=new u,n=new l,i=new f;const c={},a={};let p=new m;function h(){o&&console.log(...arguments)}this.get=async function(e){return this.compose(e,[])},this.compose=async function(o,r=[]){if(h(`Object '${o}' is requested.`),o===e.ID||o===e.ID_FQN)return h("Container itself is returned."),a[e.ID];const u=s.parse(o),l=n.modify(u,r);if(l.life===e.LIFE_S){const e=d(l);if(a[e])return h(`Existing singleton '${e}' is returned.`),a[e]}let f;c[l.moduleName]||(h(`ES6 module '${l.moduleName}' is not resolved yet`),c[l.moduleName]=p.resolve(l.moduleName));const m=c[l.moduleName];try{f=await import(m),h(`ES6 module '${l.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(l,f,r,this);if($=await i.modify($,l,r),h(`Object '${o}' is created.`),l.life===e.LIFE_S){const e=d(l);a[e]=$,h(`Object '${o}' is saved as singleton.`)}return $},this.getParser=()=>s,this.getPreProcessor=()=>n,this.getPostProcessor=()=>i,this.getResolver=()=>p,this.setDebug=function(e){o=e,t.setDebug(e)},this.setParser=e=>s=e,this.setPreProcessor=e=>n=e,this.setPostProcessor=e=>i=e,this.setResolver=e=>p=e,a[e.ID]=this}}export{h 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={COMP_A:"A",COMP_F:"F",ID:"container",ID_FQN:"TeqFw_Di_Container$",LIFE_I:"I",LIFE_S:"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.value))throw new Error(`Circular dependency for '${o.value}'. Parents are: ${JSON.stringify(r)}`);if(o.exportName){const a=[...r,o.value],{[o.exportName]:u}=n;if(o.composition===e.COMP_F){if("function"==typeof u){const n=s(u);n.length&&(c=`Deps for object '${o.value}' are: ${JSON.stringify(n)}`,t&&console.log(c));const r={};for(const e of n)r[e]=await i.compose(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;value;wrappers=[]}const c=/^((([A-Z])[A-Za-z0-9_]*)((\.)?([A-Za-z0-9_]*)((\$)?(\$)?)?)?(\(([A-Za-z0-9_,]*)\))?)$/;class a{canParse(e){return!0}parse(t){const o=new i;o.value=t;const n=c.exec(t);if(n&&(o.moduleName=n[2],"."===n[5]?"$"===n[7]||"$$"===n[7]?(o.composition=e.COMP_F,o.exportName=n[6],o.life="$"===n[7]?e.LIFE_S:e.LIFE_I):(o.composition=e.COMP_A,o.life=e.LIFE_S,o.exportName=""!==n[6]?n[6]:"default"):"$"===n[7]||"$$"===n[7]?(o.composition=e.COMP_F,o.exportName="default",o.life="$"===n[7]?e.LIFE_S:e.LIFE_I):(o.composition=void 0,o.exportName=void 0,o.life=void 0),n[11]&&(o.wrappers=n[11].split(","))),o.composition===e.COMP_A&&o.life===e.LIFE_I)throw new Error(`Export is not a function and should be used as a singleton only: '${o.value}'.`);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 p="ext",d="ns",m="root";class h{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]={[p]:r??"js",[d]:n,[m]: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][m],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}`}return class{constructor(){let t=new r,o=!1,n=new u,s=new l,i=new f;const c={},a={};let p=new h;function d(){o&&console.log(...arguments)}this.get=async function(e){return this.compose(e,[])},this.compose=async function(o,r=[]){if(d(`Object '${o}' is requested.`),o===e.ID||o===e.ID_FQN)return d("Container itself is returned."),a[e.ID];const u=n.parse(o),l=s.modify(u,r);if(l.life===e.LIFE_S){const e=$(l);if(a[e])return d(`Existing singleton '${e}' is returned.`),a[e]}let f;c[l.moduleName]||(d(`ES6 module '${l.moduleName}' is not resolved yet`),c[l.moduleName]=p.resolve(l.moduleName));const m=c[l.moduleName];try{f=await import(m),d(`ES6 module '${l.moduleName}' is loaded from '${m}'.`)}catch(e){throw console.error(e?.message,`Object key: "${o}".`,`Path: "${m}".`,`Stack: ${JSON.stringify(r)}`),e}let h=await t.create(l,f,r,this);if(h=await i.modify(h,l,r),d(`Object '${o}' is created.`),l.life===e.LIFE_S){const e=$(l);a[e]=h,d(`Object '${o}' is saved as singleton.`)}return h},this.getParser=()=>n,this.getPreProcessor=()=>s,this.getPostProcessor=()=>i,this.getResolver=()=>p,this.setDebug=function(e){o=e,t.setDebug(e)},this.setParser=e=>n=e,this.setPreProcessor=e=>s=e,this.setPostProcessor=e=>i=e,this.setResolver=e=>p=e,a[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={COMP_A:"A",COMP_F:"F",ID:"container",ID_FQN:"TeqFw_Di_Container$",LIFE_I:"I",LIFE_S:"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.value))throw new Error(`Circular dependency for '${o.value}'. Parents are: ${JSON.stringify(r)}`);if(o.exportName){const a=[...r,o.value],{[o.exportName]:u}=n;if(o.composition===e.COMP_F){if("function"==typeof u){const n=s(u);n.length&&(c=`Deps for object '${o.value}' are: ${JSON.stringify(n)}`,t&&console.log(c));const r={};for(const e of n)r[e]=await i.compose(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;value;wrappers=[]}const c=/^((([A-Z])[A-Za-z0-9_]*)((\.)?([A-Za-z0-9_]*)((\$)?(\$)?)?)?(\(([A-Za-z0-9_,]*)\))?)$/;class a{canParse(e){return!0}parse(t){const o=new i;o.value=t;const n=c.exec(t);if(n&&(o.moduleName=n[2],"."===n[5]?"$"===n[7]||"$$"===n[7]?(o.composition=e.COMP_F,o.exportName=n[6],o.life="$"===n[7]?e.LIFE_S:e.LIFE_I):(o.composition=e.COMP_A,o.life=e.LIFE_S,o.exportName=""!==n[6]?n[6]:"default"):"$"===n[7]||"$$"===n[7]?(o.composition=e.COMP_F,o.exportName="default",o.life="$"===n[7]?e.LIFE_S:e.LIFE_I):(o.composition=void 0,o.exportName=void 0,o.life=void 0),n[11]&&(o.wrappers=n[11].split(","))),o.composition===e.COMP_A&&o.life===e.LIFE_I)throw new Error(`Export is not a function and should be used as a singleton only: '${o.value}'.`);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 p="root";class d{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]={ext:r??"js",ns:n,[p]: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][p],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 m(e){return`${e.moduleName}#${e.exportName}`}return class{constructor(){let t=new r,o=!1,n=new u,s=new l,i=new f;const c={},a={};let p=new d;function h(){o&&console.log(...arguments)}this.get=async function(e){return this.compose(e,[])},this.compose=async function(o,r=[]){if(h(`Object '${o}' is requested.`),o===e.ID||o===e.ID_FQN)return h("Container itself is returned."),a[e.ID];const u=n.parse(o),l=s.modify(u,r);if(l.life===e.LIFE_S){const e=m(l);if(a[e])return h(`Existing singleton '${e}' is returned.`),a[e]}let f;c[l.moduleName]||(h(`ES6 module '${l.moduleName}' is not resolved yet`),c[l.moduleName]=p.resolve(l.moduleName));const d=c[l.moduleName];try{f=await import(d),h(`ES6 module '${l.moduleName}' is loaded from '${d}'.`)}catch(e){throw console.error(e?.message,`Object key: "${o}".`,`Path: "${d}".`,`Stack: ${JSON.stringify(r)}`),e}let $=await t.create(l,f,r,this);if($=await i.modify($,l,r),h(`Object '${o}' is created.`),l.life===e.LIFE_S){const e=m(l);a[e]=$,h(`Object '${o}' is saved as singleton.`)}return $},this.getParser=()=>n,this.getPreProcessor=()=>s,this.getPostProcessor=()=>i,this.getResolver=()=>p,this.setDebug=function(e){o=e,t.setDebug(e)},this.setParser=e=>n=e,this.setPreProcessor=e=>s=e,this.setPostProcessor=e=>i=e,this.setResolver=e=>p=e,a[e.ID]=this}}}));

package/package.json

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

package/src/Api/Container/Parser/Chunk.js

@@ -10,14 +10,14 @@ export default class TeqFw_Di_Api_Container_Parser_Chunk {
      * Returns 'true' if this chunk can parse the given dependency ID.
      *
      * @param {string} depId
-     * @return {boolean}
+     * @returns {boolean}
      */
     canParse(depId) {};
 
     /**
      * Parses a string ID for a runtime dependency and returns structured data (DTO).
      * @param {string} depId
-     * @return {TeqFw_Di_DepId}
+     * @returns {TeqFw_Di_DepId}
      */
     parse(depId) {}
 };

package/src/Api/Container/Parser.js

@@ -15,7 +15,7 @@ export default class TeqFw_Di_Api_Container_Parser {
     /**
      * Parse given dependency ID and return structured data as DTO.
      * @param {string} depId
-     * @return {TeqFw_Di_DepId}
+     * @returns {TeqFw_Di_DepId}
      */
     parse(depId) {}
 

package/src/Api/Container/PostProcessor/Chunk.js

@@ -11,7 +11,7 @@ export default class TeqFw_Di_Api_Container_PostProcessor_Chunk {
      * @param {*} obj - created object
      * @param {TeqFw_Di_DepId} originalId - original `depId` DTO
      * @param {string[]} stack - stack of parents depIds
-     * @return {*} modified object
+     * @returns {*} modified object
      */
     modify(obj, originalId, stack) {}
 };

package/src/Api/Container/PostProcessor.js

@@ -18,7 +18,7 @@ export default class TeqFw_Di_Api_Container_PostProcessor {
      * @param {*} obj - The result object to be modified.
      * @param {TeqFw_Di_DepId} depId - The original depID DTO.
      * @param {string[]} - The stack of parent IDs.
-     * @return {Promise<*>}
+     * @returns {Promise<*>}
      */
     modify(obj, depId, stack) {}
 

package/src/Api/Container/PreProcessor/Chunk.js

@@ -11,7 +11,7 @@ export default class TeqFw_Di_Api_Container_PreProcessor_Chunk {
      * @param {TeqFw_Di_DepId} depId - `depId` DTO after all previous pre-processing steps
      * @param {TeqFw_Di_DepId} originalId - original `depId` DTO
      * @param {string[]} stack - stack of parents depIds
-     * @return {TeqFw_Di_DepId}
+     * @returns {TeqFw_Di_DepId}
      */
     modify(depId, originalId, stack) {}
 };

package/src/Api/Container/PreProcessor.js

@@ -16,7 +16,7 @@ export default class TeqFw_Di_Api_Container_PreProcessor {
      * Modify parsed depID and return it.
      * @param {TeqFw_Di_DepId} depId - The depID as DTO.
      * @param {string[]} stack - The stack of parent IDs.
-     * @return {TeqFw_Di_DepId} -
+     * @returns {TeqFw_Di_DepId} -
      */
     modify(depId, stack) {}
 

package/src/Api/Container/Resolver.js

@@ -9,7 +9,7 @@ export default class TeqFw_Di_Api_Container_Resolver {
     /**
      * Convert the module name to the path of the source files .
      * @param {string} moduleName 'Vendor_Package_Module'
-     * @return {string} '/home/user/app/node_modules/@vendor/package/src/Module.js'
+     * @returns {string} '/home/user/app/node_modules/@vendor/package/src/Module.js'
      */
     resolve(moduleName) {}
 

package/src/Api/Container.js

@@ -9,27 +9,27 @@ export default class TeqFw_Di_Api_Container {
      * Gets or creates a runtime object by ID.
      *
      * @param {string} runtimeDepId - The ID of the runtime object.
-     * @return {Promise<*>} - A promise that resolves to the runtime object.
+     * @returns {Promise<*>} - A promise that resolves to the runtime object.
      */
     get(runtimeDepId) {};
 
     /**
-     * @return {TeqFw_Di_Api_Container_Parser}
+     * @returns {TeqFw_Di_Api_Container_Parser}
      */
     getParser() {};
 
     /**
-     * @return {TeqFw_Di_Api_Container_PreProcessor}
+     * @returns {TeqFw_Di_Api_Container_PreProcessor}
      */
     getPreProcessor() {};
 
     /**
-     * @return {TeqFw_Di_Api_Container_PostProcessor}
+     * @returns {TeqFw_Di_Api_Container_PostProcessor}
      */
     getPostProcessor() {};
 
     /**
-     * @return {TeqFw_Di_Container_Resolver} - the default resolver
+     * @returns {TeqFw_Di_Container_Resolver} - the default resolver
      */
     getResolver() {};
 

package/src/Container/A/Composer/A/SpecParser.js

@@ -17,7 +17,7 @@ const CLASS = /constructor\s*\(\s*\{([^\}]*)\}/s;
  * Internal function to analyze extracted parameters.
  *
  * @param {string} params
- * @return {string[]}
+ * @returns {string[]}
  * @private
  */
 function _analyze(params) {
@@ -41,7 +41,7 @@ function _analyze(params) {
 
 /**
  * @param {Function|Object} exp
- * @return {string[]}
+ * @returns {string[]}
  */
 function _analyzeClass(exp) {
     const res = [];
@@ -56,7 +56,7 @@ function _analyzeClass(exp) {
 
 /**
  * @param {Function|Object} exp
- * @return {string[]}
+ * @returns {string[]}
  */
 function _analyzeFunc(exp) {
     const res = [];
@@ -72,7 +72,7 @@ function _analyzeFunc(exp) {
 // MAIN
 /**
  * @param {Function|Object} exp
- * @return {string[]}
+ * @returns {string[]}
  */
 export default function (exp) {
     if (typeof exp === 'function') {

package/src/Container/A/Composer.js

@@ -26,7 +26,7 @@ export default class TeqFw_Di_Container_A_Composer {
          * @param {Object} module - imported es6 module
          * @param {string[]} stack - array of the parent objects IDs to prevent dependency loop
          * @param {TeqFw_Di_Container} container - to create dependencies for requested object
-         * @return {Promise<*>}
+         * @returns {Promise<*>}
          */
         this.create = async function (depId, module, stack, container) {
             if (stack.includes(depId.value))

package/src/Container/Resolver.js

@@ -49,7 +49,7 @@ export default class TeqFw_Di_Container_Resolver {
         /**
          * Convert the module name to the path of the source files .
          * @param {string} moduleName 'Vendor_Package_Module'
-         * @return {string} '/home/user/app/node_modules/@vendor/package/src/Module.js'
+         * @returns {string} '/home/user/app/node_modules/@vendor/package/src/Module.js'
          */
         this.resolve = function (moduleName) {
             let root, ext, ns;

package/src/Container.js

@@ -13,7 +13,7 @@ import Resolver from './Container/Resolver.js';
 /**
  * ID to store singletons in the internal registry.
  * @param {TeqFw_Di_DepId} key
- * @return {string}
+ * @returns {string}
  */
 function getSingletonId(key) {
     return `${key.moduleName}#${key.exportName}`;
@@ -63,7 +63,7 @@ export default class TeqFw_Di_Container {
          *
          * @param {string} depId runtime dependency ID
          * @param {string[]} stack set of the depId to detect circular dependencies
-         * @return {Promise<*>}
+         * @returns {Promise<*>}
          */
         this.compose = async function (depId, stack = []) {
             log(`Object '${depId}' is requested.`);

package/src/Defs.js

@@ -15,7 +15,7 @@ export default {
      * See: https://stackoverflow.com/a/29094018/4073821
      *
      * @param {function} fn
-     * @return {boolean}
+     * @returns {boolean}
      */
     isClass(fn) {
         const proto = Object.getOwnPropertyDescriptor(fn, 'prototype');