@teqfw/di 0.12.1 → 0.20.1

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@teqfw/di",
-  "version": "0.12.1",
+  "version": "0.20.1",
   "description": "Dependency Injection container based on logical namespaces for ES6 modules.",
   "keywords": [
     "dependency injection",
     "di",
     "dynamic import",
-    "ecmascript 2015",
-    "es6+",
+    "es6 modules",
     "teqfw",
     "tequila framework"
   ],
@@ -21,10 +20,21 @@
     "email": "alex@flancer64.com",
     "url": "https://github.com/flancer64"
   },
-  "main": "src/Shared/Container.mjs",
+  "main": "src/Container.js",
   "type": "module",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/teqfw/di.git"
+  },
+  "scripts": {
+    "build": "rm -fr ./dist/ && webpack build"
+  },
+  "devDependencies": {
+    "babel-eslint": "*",
+    "eslint": "*",
+    "esm": "*",
+    "mocha": "*",
+    "webpack": "^5.88.1",
+    "webpack-cli": "^5.1.4"
   }
 }

package/src/Api/ObjectKey.js

@@ -0,0 +1,35 @@
+/**
+ * This is a DTO that represents the structure of an ID for a runtime dependency.
+ */
+export default class TeqFw_Di_Api_ObjectKey {
+    /**
+     * The name of an export of the module.
+     * @type {string}
+     */
+    exportName;
+    /**
+     * Composition type (see Defs.COMPOSE_): use the export as Factory (F) or return as-is (A).
+     * @type {string}
+     */
+    composition;
+    /**
+     * Lifestyle type (see Defs.LIFE_): singleton (S) or instance (I).
+     * @type {string}
+     */
+    life;
+    /**
+     * The code for ES6 module that can be converted to the path to this es6 module.
+     * @type {string}
+     */
+    moduleName;
+    /**
+     * Object key value.
+     * @type {string}
+     */
+    value;
+    /**
+     * List of wrappers to decorate the result.
+     * @type {string[]}
+     */
+    wrappers = [];
+}

package/src/Composer.js

@@ -0,0 +1,68 @@
+/**
+ *
+ */
+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/Container.js

@@ -0,0 +1,142 @@
+/**
+ * The Object Container (composition root).
+ */
+import Composer from './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
+
+// FUNCS
+/**
+ * ID to store singletons in the internal registry.
+ * @param {TeqFw_Di_Api_ObjectKey} key
+ * @return {string}
+ */
+function getSingletonId(key) {
+    return `${key.moduleName}#${key.exportName}`;
+}
+
+// MAIN
+export default class TeqFw_Di_Container {
+
+    constructor() {
+        // VARS
+        let _composer = new Composer();
+        let _debug = false;
+        let _parser = new Parser();
+        let _preProcessor = new PreProcessor();
+        _preProcessor.addHandler(NewReplace()); // create new instance of the replacement handler
+
+        /**
+         * Registry for loaded es6 modules.
+         * @type {Object<string, Module>}
+         */
+        const _regModules = {};
+        /**
+         * Registry to store singletons.
+         * @type {Object<string, *>}
+         */
+        const _regSingles = {};
+        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.`);
+            // return container itself if requested
+            if (
+                (objectKey === Defs.KEY_CONTAINER) ||
+                (objectKey === 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);
+            // modify original key according to some rules (replacements, etc.)
+            const key = _preProcessor.process(parsed);
+            // return existing singleton
+            if (key.life === Defs.LIFE_SINGLETON) {
+                const singleId = getSingletonId(key);
+                if (_regSingles[singleId]) {
+                    log(`Existing singleton '${singleId}' is returned.`);
+                    return _regSingles[singleId];
+                }
+            }
+            // load es6 module if not loaded before
+            if (!_regModules[key.moduleName]) {
+                log(`ES6 module '${key.moduleName}' is not loaded 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;
+                }
+
+            }
+            // 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;
+                    }
+                });
+            }
+
+            if (key.life === Defs.LIFE_SINGLETON) {
+                const singleId = getSingletonId(key);
+                _regSingles[singleId] = res;
+                log(`Object '${objectKey}' is saved as singleton.`);
+            }
+            return res;
+        };
+
+        this.getParser = () => _parser;
+
+        this.getPreProcessor = () => _preProcessor
+        ;
+        this.getResolver = () => _resolver;
+
+        this.setDebug = function (data) {
+            _debug = data;
+            _composer.setDebug(data);
+        };
+
+        this.setParser = (data) => _parser = data;
+
+        this.setPreProcessor = (data) => _preProcessor = data;
+
+        this.setResolver = (data) => _resolver = data;
+
+        // MAIN
+        _regSingles[Defs.KEY_CONTAINER] = this;
+    }
+};

package/src/Defs.js

@@ -0,0 +1,25 @@
+/**
+ * Hardcoded constants for the package.
+ */
+export default {
+    COMPOSE_AS_IS: 'A',
+    COMPOSE_FACTORY: 'F',
+    EXT: 'js',
+    KEY_CONTAINER: 'container',
+    KEY_CONTAINER_NS: 'TeqFw_Di_Container$',
+    LIFE_INSTANCE: 'I',
+    LIFE_SINGLETON: 'S',
+    WRAP_PROXY: 'proxy',
+
+    /**
+     * Return 'true' if function is a class definition.
+     * See: https://stackoverflow.com/a/29094018/4073821
+     *
+     * @param {function} fn
+     * @return {boolean}
+     */
+    isClass(fn) {
+        const proto = Object.getOwnPropertyDescriptor(fn, 'prototype');
+        return proto && !proto.writable;
+    },
+};

package/src/DepId/Parser.mjs

@@ -0,0 +1,68 @@
+/**
+ * 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;
+}

package/src/Parser/Def.js

@@ -0,0 +1,63 @@
+/**
+ * Default parser for object keys in format:
+ *   - Vnd_Pkg_Prj_Mod$FA
+ */
+import Dto from '../Api/ObjectKey.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])?)?)?)$/;
+
+
+// MAIN
+/**
+ * @param {string} objectKey
+ * @return {TeqFw_Di_Api_ObjectKey}
+ */
+export default function TeqFw_Di_Parser_Def(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/Parser/Old.js

@@ -0,0 +1,108 @@
+/**
+ * Parser for object keys in old format:
+ *   - Vnd_Pkg_Prj_Mod[.|#]export$$
+ */
+import Dto from '../Api/ObjectKey.js';
+import Defs from '../Defs.js';
+
+// VARS
+/** @type {string} default export keyword */
+const DEF_EXP = 'default';
+/** @type {string} logical namespace export mark (Ns_Mod.export) */
+const EXP = '.';
+/** @type {string} filesystem export mark (@vendor/package!module#export$$) and old logical export mark */
+const EXP_OLD = '#';
+/** @type {string} new instance mark (Ns_Mod.export$$) */
+const INST = '$$';
+/** @type {RegExp} expression for logical namespace IDs (Ns_Module[.|#]export$$@@) */
+const REGEXP = /^((([A-Z])[A-Za-z0-9_]*)((#|.)?([A-Za-z0-9_]*)(\${1,2}|@{1,2})?)?)$/;
+/** @type {RegExp} expression for objects that manually added to DI container (singleton, namedFactory$$)  */
+const MANUAL = /^((([a-z])[A-Za-z0-9_]*)(\$\$)?)$/s;
+/** @type {string} new instance proxy mark (Ns_Mod.export@@) */
+const P_INST = '@@';
+/** @type {string} singleton proxy mark (Ns_Mod.export@) */
+const P_SNGLT = '@';
+/** @type {string} singleton mark (Ns_Mod.export$) */
+const SNGLT = '$';
+
+// MAIN
+export default function TeqFw_Di_Parser_Old(objectKey) {
+    const res = new Dto();
+    res.value = objectKey;
+    const parts = REGEXP.exec(objectKey);
+    if (parts) {
+        res.moduleName = parts[2];
+        // Ns_Module.name$$[@@] - named instance [proxy]
+        if (
+            ((parts[5] === EXP) || (parts[5] === EXP_OLD))
+            && ((parts[7] === INST) || (parts[7] === P_INST))
+        ) {
+            if (parts[7] === P_INST)
+                res.wrappers.push(Defs.WRAP_PROXY);
+            res.composition = Defs.COMPOSE_FACTORY;
+            res.life = Defs.LIFE_INSTANCE;
+            res.exportName = parts[6];
+        }
+        // Ns_Module.name$[@] - named singleton [proxy]
+        else if (
+            ((parts[5] === EXP) || (parts[5] === EXP_OLD))
+            && ((parts[7] === SNGLT) || (parts[7] === P_SNGLT))
+        ) {
+            if (parts[7] === P_SNGLT)
+                res.wrappers.push(Defs.WRAP_PROXY);
+            res.composition = Defs.COMPOSE_FACTORY;
+            res.life = Defs.LIFE_SINGLETON;
+            res.exportName = parts[6];
+        }
+        // Ns_Module.name - named export
+        else if (
+            ((parts[5] === EXP) || (parts[5] === EXP_OLD))
+            && ((parts[6] !== undefined) && (parts[6] !== ''))
+        ) {
+            res.composition = Defs.COMPOSE_AS_IS;
+            res.exportName = parts[6];
+            res.life = Defs.LIFE_SINGLETON;
+        }
+        // Ns_Module$$[@@]- default instance [proxy]
+        else if ((parts[4] === INST) || (parts[4] === P_INST)) {
+            if (parts[4] === P_INST)
+                res.wrappers.push(Defs.WRAP_PROXY);
+            res.composition = Defs.COMPOSE_FACTORY;
+            res.life = Defs.LIFE_INSTANCE;
+            res.exportName = DEF_EXP;
+        }
+        // Ns_Module$[@] - default singleton [proxy]
+        else if ((parts[4] === SNGLT) || (parts[4] === P_SNGLT)) {
+            if (parts[4] === P_SNGLT)
+                res.wrappers.push(Defs.WRAP_PROXY);
+            res.composition = Defs.COMPOSE_FACTORY;
+            res.life = Defs.LIFE_SINGLETON;
+            res.exportName = DEF_EXP;
+        }
+        // Ns_Module#[.] - default export
+        else if (
+            ((parts[5] === EXP) || (parts[5] === EXP_OLD))
+            && (parts[7] === undefined)
+        ) {
+            res.composition = Defs.COMPOSE_AS_IS;
+            res.life = Defs.LIFE_SINGLETON;
+            res.exportName = DEF_EXP;
+        } else {
+            // just a es6-module (deprecated)
+
+        }
+    } else {
+        const manual = MANUAL.exec(objectKey);
+        if (manual) {
+            if (manual[4] === '$$') {
+                res.composition = Defs.COMPOSE_FACTORY;
+                res.life = Defs.LIFE_INSTANCE;
+            } else {
+                res.life = Defs.LIFE_SINGLETON;
+            }
+        } else {
+            // TODO: add exception
+        }
+    }
+    return res;
+}

package/src/Parser.js

@@ -0,0 +1,65 @@
+/**
+ * The root parser for `objectKeys` contains all other parsers.
+ * It calls the other parser one by one to parse the object key as a structure.
+ * Every npm package can have its own format for an `objectKey`.
+ */
+import defaultParser from './Parser/Def.js';
+
+// VARS
+const KEY_PARSER = 'parser';
+const KEY_VALIDATOR = 'validator';
+
+// MAIN
+export default class TeqFw_Di_Parser {
+
+    constructor() {
+        // VARS
+        /**
+         * Default parsing function.
+         * @type {(function(string): TeqFw_Di_Api_ObjectKey)}
+         */
+        let _defaultParser = defaultParser;
+        /**
+         * The array of the pairs {validator, parser} to parse objectKeys.
+         * @type {Object<validator:function, parser:function>[]}
+         */
+        const _parsers = [];
+
+        // INSTANCE METHODS
+
+        /**
+         *
+         * @param {function(string):boolean} validator
+         * @param {function(string):TeqFw_Di_Api_ObjectKey} parser
+         */
+        this.addParser = function (validator, parser) {
+            _parsers.push({[KEY_VALIDATOR]: validator, [KEY_PARSER]: parser});
+        };
+
+        /**
+         * @param {string} objectKey
+         * @return {TeqFw_Di_Api_ObjectKey}
+         */
+        this.parse = function (objectKey) {
+            let res;
+            for (const one of _parsers) {
+                if (one[KEY_VALIDATOR](objectKey)) {
+                    res = one[KEY_PARSER](objectKey);
+                    break;
+                }
+            }
+            if (!res)
+                res = _defaultParser(objectKey);
+            return res;
+        };
+
+        /**
+         * @param {function(string):TeqFw_Di_Api_ObjectKey} parser
+         */
+        this.setDefaultParser = function (parser) {
+            _defaultParser = parser;
+        };
+
+        // MAIN
+    }
+};

package/src/PreProcessor/Replace.js

@@ -0,0 +1,48 @@
+/**
+ * Pre-processor handler to replace one object key with another.
+ * @namespace TeqFw_Di_PreProcessor_Replace
+ */
+
+/**
+ * Factory function to create pre-processor handler.
+ * @return {function(*): *}
+ */
+export default function () {
+    // VARS
+    /**
+     * Storage for ES modules replacements (interface => implementation).
+     * Sample: {['Vnd_Plug_Interface']:'Vnd_Plug_Impl', ...}
+     * @type {Object<string, string>}
+     */
+    const replacements = {};
+
+    // FUNCS
+    /**
+     * @param {TeqFw_Di_Api_ObjectKey} objectKey
+     * @param {TeqFw_Di_Api_ObjectKey} originalKey
+     * @return {TeqFw_Di_Api_ObjectKey}
+     */
+    function TeqFw_Di_PreProcessor_Replace(objectKey, originalKey) {
+        let module = objectKey.moduleName;
+        while (replacements[module]) module = replacements[module];
+        if (module !== objectKey.moduleName) {
+            const res = Object.assign({}, objectKey);
+            res.moduleName = module;
+            return res;
+        } else
+            return objectKey;
+    }
+
+    /**
+     * Add replacement for ES6 modules.
+     *
+     * @param {string} orig ('Vnd_Plug_Interface')
+     * @param {string} alter ('Vnd_Plug_Impl')
+     */
+    TeqFw_Di_PreProcessor_Replace.add = function (orig, alter) {
+        replacements[orig] = alter;
+    };
+
+    // MAIN
+    return TeqFw_Di_PreProcessor_Replace;
+}