@teqfw/di 0.20.0 → 0.21.0

package/src/Container/A/Composer.js

@@ -0,0 +1,70 @@
+/**
+ * The composer creates requested objects. It uses the container to create dependencies.
+ *
+ * @namespace TeqFw_Di_Container_A_Composer
+ */
+import Defs from '../../Defs.js';
+import specParser from './Composer/A/SpecParser.js';
+
+export default class TeqFw_Di_Container_A_Composer {
+
+    constructor() {
+        // VARS
+        let _debug = false;
+
+        // FUNCS
+        function log(msg) {
+            if (_debug) console.log(msg);
+        }
+
+        // INSTANCE METHODS
+
+        /**
+         * Returns or creates and returns the requested object.
+         *
+         * @param {TeqFw_Di_DepId} depId
+         * @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<*>}
+         */
+        this.create = async function (depId, module, stack, container) {
+            if (stack.includes(depId.value))
+                throw new Error(`Circular dependency for '${depId.value}'. Parents are: ${JSON.stringify(stack)}`);
+            if (depId.exportName) {
+                // use export from the es6-module
+                const stackNew = [...stack, depId.value];
+                const {[depId.exportName]: exp} = module;
+                if (depId.composition === Defs.COMPOSE_FACTORY) {
+                    if (typeof exp === 'function') {
+                        // create deps for factory function
+                        const deps = specParser(exp);
+                        if (deps.length) log(`Deps for object '${depId.value}' are: ${JSON.stringify(deps)}`);
+                        const spec = {};
+                        for (const dep of deps)
+                            spec[dep] = await container.compose(dep, stackNew);
+                        // create a new object with the factory function
+                        const res = (Defs.isClass(exp)) ? new exp(spec) : exp(spec);
+                        if (res instanceof Promise)
+                            return await res;
+                        else
+                            return res;
+                    } else
+                        // just clone the export
+                        return Object.assign({}, exp);
+                } else
+                    // just return the export (w/o factory function)
+                    return exp;
+            } else {
+                // TODO: this is almost useless option
+                return module;
+            }
+        };
+
+        this.setDebug = function (data) {
+            _debug = data;
+        };
+
+        // MAIN
+    }
+};

package/src/Container/A/Parser/Chunk/Def.js

@@ -0,0 +1,70 @@
+/**
+ * Default parser for object keys in format:
+ *   - Vnd_Pkg_Prj_Mod$FA
+ *
+ * @namespace TeqFw_Di_Container_A_Parser_Chunk_Def
+ */
+import Dto from '../../../../DepId.js';
+import Defs from '../../../../Defs.js';
+
+// VARS
+/** @type {RegExp} expression for default object key (Ns_Module[.|#]export$[F|A][S|I]) */
+const REGEXP = /^((([A-Z])[A-Za-z0-9_]*)((#|\.)?([A-Za-z0-9]*)((\$)([F|A])?([S|I])?)?)?)$/;
+
+/**
+ * @implements TeqFw_Di_Api_Container_Parser_Chunk
+ */
+export default class TeqFw_Di_Container_A_Parser_Chunk_Def {
+
+    canParse(depId) {
+        // default parser always trys to parse the depId
+        return true;
+    }
+
+    parse(objectKey) {
+        const res = new Dto();
+        res.value = objectKey;
+        const parts = REGEXP.exec(objectKey);
+        if (parts) {
+            res.moduleName = parts[2];
+            if (parts[5] === '.') {
+                // App_Service.export...
+                if (parts[8] === '$') {
+                    // App_Service.export$...
+                    res.composition = Defs.COMPOSE_FACTORY;
+                    res.exportName = parts[6];
+                    res.life = (parts[10] === Defs.LIFE_INSTANCE)
+                        ? Defs.LIFE_INSTANCE : Defs.LIFE_SINGLETON;
+                } else {
+                    res.composition = ((parts[8] === undefined) || (parts[8] === Defs.COMPOSE_AS_IS))
+                        ? Defs.COMPOSE_AS_IS : Defs.COMPOSE_FACTORY;
+                    res.exportName = parts[6];
+                    res.life = ((parts[8] === undefined) || (parts[10] === Defs.LIFE_SINGLETON))
+                        ? Defs.LIFE_SINGLETON : Defs.LIFE_INSTANCE;
+                }
+
+
+            } else if (parts[8] === '$') {
+                // App_Logger$FS
+                res.composition = ((parts[9] === undefined) || (parts[9] === Defs.COMPOSE_FACTORY))
+                    ? Defs.COMPOSE_FACTORY : Defs.COMPOSE_AS_IS;
+                res.exportName = 'default';
+                if (parts[10]) {
+                    res.life = (parts[10] === Defs.LIFE_SINGLETON) ? Defs.LIFE_SINGLETON : Defs.LIFE_INSTANCE;
+                } else {
+                    res.life = (res.composition === Defs.COMPOSE_FACTORY) ? Defs.LIFE_SINGLETON : Defs.LIFE_INSTANCE;
+                }
+            } else {
+                // App_Service
+                res.composition = Defs.COMPOSE_AS_IS;
+                res.exportName = 'default';
+                res.life = Defs.LIFE_SINGLETON;
+            }
+        }
+
+        // we should always use singletons for as-is exports
+        if ((res.composition === Defs.COMPOSE_AS_IS) && (res.life === Defs.LIFE_INSTANCE))
+            throw new Error(`Export is not a function and should be used as a singleton only: '${res.value}'.`);
+        return res;
+    }
+}

package/src/Container/Parser.js

@@ -0,0 +1,48 @@
+/**
+ * The parser for the runtime dependency ID contains multiple chunks. Each npm package can have its own format for
+ * a `depId`. The parser calls the chunks one by one to parse the string ID as a structure and returns the first result.
+ * If none of the chunks processed the `depId`, the parser calls the default chunk.
+ */
+import DefChunk from './A/Parser/Chunk/Def.js';
+
+/**
+ * @implements TeqFw_Di_Api_Container_Parser
+ */
+export default class TeqFw_Di_Container_Parser {
+    constructor() {
+        // VARS
+        /**
+         * The default chunk to parse the depId if no other chunks have parsed this depId.
+         *
+         * @type {TeqFw_Di_Api_Container_Parser_Chunk}
+         */
+        let _defaultChunk = new DefChunk();
+        /**
+         * The array of the chunks to parse dependency IDs.
+         * @type {TeqFw_Di_Api_Container_Parser_Chunk[]}
+         */
+        const _chunks = [];
+
+        // INSTANCE METHODS
+
+        this.addChunk = function (chunk) {
+            _chunks.push(chunk);
+        };
+
+        this.parse = function (depId) {
+            let res;
+            for (const one of _chunks)
+                if (one.canParse(depId)) {
+                    res = one.parse(depId);
+                    break;
+                }
+            if (!res)
+                res = _defaultChunk?.parse(depId);
+            return res;
+        };
+
+        this.setDefaultChunk = function (chunk) {
+            _defaultChunk = chunk;
+        };
+    }
+};

package/src/Container/PostProcessor.js

@@ -0,0 +1,32 @@
+/**
+ * The post-processor handles the result object after composition and before returning.
+ *
+ *  @implements TeqFw_Di_Api_Container_PostProcessor
+ */
+export default class TeqFw_Di_Container_PostProcessor {
+
+    constructor() {
+        // VARS
+
+        /**
+         * The array of the chunks to modify dependency IDs.
+         * @type {TeqFw_Di_Api_Container_PostProcessor_Chunk[]}
+         */
+        const _chunks = [];
+
+        // INSTANCE METHODS
+
+        this.addChunk = function (chunk) {
+            _chunks.push(chunk);
+        };
+
+        this.modify = async function (obj, depId, stack) {
+            let res = obj;
+            for (const one of _chunks) {
+                res = one.modify(res, depId, stack);
+                if (res instanceof Promise) res = await res;
+            }
+            return res;
+        };
+    }
+};

package/src/Container/PreProcessor.js

@@ -0,0 +1,34 @@
+/**
+ * The preprocessor handles object keys after the parsing but before creating any objects.
+ * A replacement rules can be implemented here.
+ * Every handler is a function with 2 arguments:
+ *  - objectKey: current key after processing with other handlers;
+ *  - originalKey: the key before any processing;
+ *
+ *  @implements TeqFw_Di_Api_Container_PreProcessor
+ */
+export default class TeqFw_Di_Container_PreProcessor {
+
+    constructor() {
+        // VARS
+
+        /**
+         * The array of the chunks to modify dependency IDs.
+         * @type {TeqFw_Di_Api_Container_PreProcessor_Chunk[]}
+         */
+        const _chunks = [];
+
+        // INSTANCE METHODS
+
+        this.addChunk = function (chunk) {
+            _chunks.push(chunk);
+        };
+
+        this.modify = function (depId, stack) {
+            let res = depId;
+            for (const one of _chunks)
+                res = one.modify(res, depId, stack);
+            return res;
+        };
+    }
+};

package/src/{Resolver.js → Container/Resolver.js}

@@ -7,7 +7,7 @@
  *  - every package has sources with the same extensions (*.js, *.mjs, *.es6, ...)
  *  - namespaces can be nested (App_Web_ => ./@app/web/..., App_Web_Api_ => ./@app/web_api/...)
  */
-import Defs from './Defs.js';
+import Defs from '../Defs.js';
 
 // VARS
 const KEY_EXT = 'ext';
@@ -21,7 +21,7 @@ const KEY_PATH = 'root';
 const NSS = '_';
 
 // MAIN
-export default class TeqFw_Di_Resolver {
+export default class TeqFw_Di_Container_Resolver {
 
     constructor() {
         // VARS
@@ -55,7 +55,8 @@ export default class TeqFw_Di_Resolver {
                 }
             }
             if (root && ext) {
-                const tail = moduleName.replace(ns, '');
+                let tail = moduleName.replace(ns, '');
+                if (tail.indexOf(NSS) === 0) tail = tail.replace(NSS, '');
                 const file = tail.replaceAll(NSS, _ps);
                 return `${root}${_ps}${file}.${ext}`;
             } else return moduleName;

package/src/Container.js

@@ -1,19 +1,18 @@
 /**
  * The Object Container (composition root).
+ * @namespace TeqFw_Di_Container
  */
-import Composer from './Composer.js';
+import Composer from './Container/A/Composer.js';
 import Defs from './Defs.js';
-import Parser from './Parser.js';
-import PreProcessor from './PreProcessor.js';
-import NewReplace from './PreProcessor/Replace.js';
-import Resolver from './Resolver.js';
-
-// VARS
+import Parser from './Container/Parser.js';
+import PreProcessor from './Container/PreProcessor.js';
+import PostProcessor from './Container/PostProcessor.js';
+import Resolver from './Container/Resolver.js';
 
 // FUNCS
 /**
  * ID to store singletons in the internal registry.
- * @param {TeqFw_Di_Api_ObjectKey} key
+ * @param {TeqFw_Di_DepId} key
  * @return {string}
  */
 function getSingletonId(key) {
@@ -21,6 +20,9 @@ function getSingletonId(key) {
 }
 
 // MAIN
+/**
+ * @implements TeqFw_Di_Api_Container
+ */
 export default class TeqFw_Di_Container {
 
     constructor() {
@@ -29,13 +31,14 @@ export default class TeqFw_Di_Container {
         let _debug = false;
         let _parser = new Parser();
         let _preProcessor = new PreProcessor();
-        _preProcessor.addHandler(NewReplace()); // create new instance of the replacement handler
+        let _postProcessor = new PostProcessor();
 
         /**
-         * Registry for loaded es6 modules.
-         * @type {Object<string, Module>}
+         * Registry for paths for loaded es6 modules.
+         *
+         * @type {Object<string, string>}
          */
-        const _regModules = {};
+        const _regPaths = {};
         /**
          * Registry to store singletons.
          * @type {Object<string, *>}
@@ -44,31 +47,38 @@ export default class TeqFw_Di_Container {
         let _resolver = new Resolver();
 
         // FUNCS
-        function error() {
-            console.error(...arguments);
-        }
 
         function log() {
             if (_debug) console.log(...arguments);
         }
 
-
         // INSTANCE METHODS
 
-        this.get = async function (objectKey, stack = []) {
-            log(`Object '${objectKey}' is requested.`);
+        this.get = async function (runtimeDepId) {
+            return this.compose(runtimeDepId, []);
+        };
+
+        /**
+         * This method is 'private' for the npm package. It is used in the Composer only.
+         *
+         * @param {string} depId runtime dependency ID
+         * @param {string[]} stack set of the depId to detect circular dependencies
+         * @return {Promise<*>}
+         */
+        this.compose = async function (depId, stack = []) {
+            log(`Object '${depId}' is requested.`);
             // return container itself if requested
             if (
-                (objectKey === Defs.KEY_CONTAINER) ||
-                (objectKey === Defs.KEY_CONTAINER_NS)
+                (depId === Defs.KEY_CONTAINER) ||
+                (depId === Defs.KEY_CONTAINER_NS)
             ) {
                 log(`Container itself is returned.`);
                 return _regSingles[Defs.KEY_CONTAINER];
             }
             // parse the `objectKey` and get the structured DTO
-            const parsed = _parser.parse(objectKey);
+            const parsed = _parser.parse(depId);
             // modify original key according to some rules (replacements, etc.)
-            const key = _preProcessor.process(parsed);
+            const key = _preProcessor.modify(parsed, stack);
             // return existing singleton
             if (key.life === Defs.LIFE_SINGLETON) {
                 const singleId = getSingletonId(key);
@@ -77,52 +87,47 @@ export default class TeqFw_Di_Container {
                     return _regSingles[singleId];
                 }
             }
-            // load es6 module if not loaded before
-            if (!_regModules[key.moduleName]) {
-                log(`ES6 module '${key.moduleName}' is not loaded yet`);
+            // resolve path to es6 module if not resolved before
+            if (!_regPaths[key.moduleName]) {
+                log(`ES6 module '${key.moduleName}' is not resolved yet`);
                 // convert module name to the path to es6-module file with a sources
-                const path = _resolver.resolve(key.moduleName);
-                try {
-                    _regModules[key.moduleName] = await import(path);
-                    log(`ES6 module '${key.moduleName}' is loaded from '${path}'.`);
-                } catch (e) {
-                    console.error(
-                        e?.message,
-                        `Object key: "${objectKey}".`,
-                        `Path: "${path}".`,
-                        `Stack: ${JSON.stringify(stack)}`
-                    );
-                    throw e;
-                }
-
+                _regPaths[key.moduleName] = _resolver.resolve(key.moduleName);
             }
-            // create object using the composer
-            let res = await _composer.create(key, _regModules[key.moduleName], stack, this);
-            log(`Object '${objectKey}' is created.`);
-
-            // TODO: refactor this code to use wrappers w/o hardcode
-            if (key.wrappers.includes(Defs.WRAP_PROXY)) {
-                const me = this;
-                res = new Proxy({dep: undefined, objectKey}, {
-                    get: async function (base, name) {
-                        if (name === 'create') base.dep = await me.get(base.objectKey);
-                        return base.dep;
-                    }
-                });
+
+            // load es6 module
+            let module;
+            const path = _regPaths[key.moduleName];
+            try {
+                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)}`
+                );
+                throw e;
             }
+            // create object using the composer then modify it in post-processor
+            let res = await _composer.create(key, module, stack, this);
+            res = await _postProcessor.modify(res, key, stack);
+            log(`Object '${depId}' is created.`);
 
+            // save singletons
             if (key.life === Defs.LIFE_SINGLETON) {
                 const singleId = getSingletonId(key);
                 _regSingles[singleId] = res;
-                log(`Object '${objectKey}' is saved as singleton.`);
+                log(`Object '${depId}' is saved as singleton.`);
             }
             return res;
         };
 
         this.getParser = () => _parser;
 
-        this.getPreProcessor = () => _preProcessor
-        ;
+        this.getPreProcessor = () => _preProcessor;
+
+        this.getPostProcessor = () => _postProcessor;
         this.getResolver = () => _resolver;
 
         this.setDebug = function (data) {
@@ -134,6 +139,8 @@ export default class TeqFw_Di_Container {
 
         this.setPreProcessor = (data) => _preProcessor = data;
 
+        this.setPostProcessor = (data) => _postProcessor = data;
+
         this.setResolver = (data) => _resolver = data;
 
         // MAIN

package/src/Defs.js

@@ -1,5 +1,6 @@
 /**
- * Hardcoded constants for the package.
+ * Hardcoded constants and useful utilities for the package.
+ * @namespace TeqFw_Di_Defs
  */
 export default {
     COMPOSE_AS_IS: 'A',
@@ -9,6 +10,9 @@ export default {
     KEY_CONTAINER_NS: 'TeqFw_Di_Container$',
     LIFE_INSTANCE: 'I',
     LIFE_SINGLETON: 'S',
+    /**
+     * @deprecated use TeqFw_Core_Shared_Defaults.DI_WRAP_PROXY
+     */
     WRAP_PROXY: 'proxy',
 
     /**

package/src/{Api/ObjectKey.js → DepId.js}

@@ -1,7 +1,8 @@
 /**
  * This is a DTO that represents the structure of an ID for a runtime dependency.
+ * @namespace TeqFw_Di_DepId
  */
-export default class TeqFw_Di_Api_ObjectKey {
+export default class TeqFw_Di_DepId {
     /**
      * The name of an export of the module.
      * @type {string}

package/teqfw.json

@@ -0,0 +1,9 @@
+{
+  "@teqfw/di": {
+    "autoload": {
+      "ns": "TeqFw_Di",
+      "path": "./src",
+      "ext": "js"
+    }
+  }
+}

package/src/Composer.js

@@ -1,68 +0,0 @@
-/**
- *
- */
-import Defs from './Defs.js';
-import specAnalyser from './SpecAnalyser.js';
-
-// FUNCS
-
-// MAIN
-export default class TeqFw_Di_Composer {
-
-    constructor() {
-        // VARS
-        let _debug = false;
-
-        // FUNCS
-        function log(msg) {
-            if (_debug) console.log(msg);
-        }
-
-        // INSTANCE METHODS
-
-        /**
-         *
-         * @param {TeqFw_Di_Api_ObjectKey} key
-         * @param {Object} module
-         * @param {string[]} stack array of the parent objects to prevent dependency loop
-         * @param {TeqFw_Di_Container} container
-         * @return {Promise<*>}
-         */
-        this.create = async function (key, module, stack, container) {
-            if (stack.includes(key.value))
-                throw new Error(`Circular dependency for '${key.value}'. Parents are: ${JSON.stringify(stack)}`);
-            if (key.exportName) {
-                // use export from the es6-module
-                const stackNew = [...stack, key.value];
-                const {[key.exportName]: exp} = module;
-                if (key.composition === Defs.COMPOSE_FACTORY) {
-                    if (typeof exp === 'function') {
-                        // create deps for factory function
-                        const deps = specAnalyser(exp);
-                        if (deps.length) log(`Deps for object '${key.value}' are: ${JSON.stringify(deps)}`);
-                        const spec = {};
-                        for (const dep of deps)
-                            spec[dep] = await container.get(dep, stackNew);
-                        // create a new object with the factory function
-                        const res = (Defs.isClass(exp)) ? new exp(spec) : exp(spec);
-                        if (res instanceof Promise)
-                            return await res;
-                        else
-                            return res;
-                    } else
-                        // just clone the export
-                        return Object.assign({}, exp);
-                } else
-                    return exp;
-            } else {
-                return module;
-            }
-        };
-
-        this.setDebug = function (data) {
-            _debug = data;
-        };
-
-        // MAIN
-    }
-};

package/src/DepId/Parser.mjs

@@ -1,68 +0,0 @@
-/**
- * This is default parser that converts dependency ID to the `depId` DTO.
- * @namespace ObjectKey.Parser
- */
-// IMPORTS
-import {ObjectKey} from '../Api/ObjectKey.mjs';
-
-// VARS
-/** @type {RegExp} expression for depId (Ns_Module.export$$#adapter) */
-const TMPL = /^(([A-Z])[A-Za-z0-9_]*)((.)([A-Za-z0-9_]*)?((\$|\$\$)?((#)([A-Za-z0-9_]*)?)?)?)?$/;
-
-// FUNCS
-/**
- * @param {string} depId
- * @return {Api.ObjectKey}
- */
-export default function (depId) {
-    let res;
-    const parts = TMPL.exec(depId);
-    if (parts) {
-        const nameMod = parts[1];
-        const sepMod = parts[4]; // after-module separator
-        const sepExp = parts[6]; // after-export separator
-        const sepLife = parts[9]; // after-life separator
-
-        res = new ObjectKey();
-        // always presents
-        res.nameModule = nameMod;
-        if (sepLife === '#') {
-            // the longest form of the ID (Mod.exp$#adp)
-            res.adapter = parts[10] ?? 'default';
-            res.isExport = true;
-            res.isFactory = parts[7] !== undefined;
-            if (parts[7] === '$') res.isSingleton = true;
-            else if (parts[7] === '$$') res.isSingleton = false;
-            res.nameExport = parts[5];
-        } else if (sepMod === '#') {
-            // Mod#adp
-            res.adapter = parts[5] ?? 'default';
-            res.isExport = true;
-            res.isFactory = false;
-            res.nameExport = 'default';
-        } else if ((sepExp === '$') || (sepExp === '$$')) {
-            if (sepMod === '.') {
-                // Mod.exp$$
-                res.isExport = true;
-                res.isFactory = true;
-                if (parts[7] === '$') res.isSingleton = true;
-                else if (parts[7] === '$$') res.isSingleton = false;
-                res.nameExport = parts[5];
-            } else if (sepMod === '$') {
-                // Mod$$
-                res.isExport = true;
-                res.isFactory = true;
-                if (parts[3] === '$') res.isSingleton = true;
-                else if (parts[3] === '$$') res.isSingleton = false;
-                res.nameExport = 'default';
-            }
-        } else {
-            // Mod.exp
-            res.isFactory = false;
-            res.isExport = (sepMod === '.');
-            // define the name of the export
-            if (res.isExport) res.nameExport = parts[5] ?? 'default';
-        }
-    }
-    return res;
-}