@teqfw/di 0.7.0 → 0.11.0

package/README.md

@@ -3,10 +3,12 @@
 "_DI_" means both "_Dynamic Import_" and "_Dependency Injection_" here. This package allows defining logical namespaces
 in your projects, dynamically importing ES6-modules from these namespaces, creating new objects from imported
 functions/classes and resolving dependencies in constructors. It uses pure ECMAScript 2015+ (ES6+) and works both for
-modern browsers & nodejs apps. You can share the same code between your frontend (browser) and your backend (nodejs) without TypeScript and preprocessors. Code in the browser's debugger will be the same as in your editor. Finally, you even can use interfaces in you projects and replace it with implementations.
+modern browsers & nodejs apps. You can share the same code between your frontend (browser) and your backend (nodejs)
+without TypeScript and preprocessors. Code in the browser's debugger will be the same as in your editor. Finally, you
+even can use interfaces in you projects and replace it with implementations.
 
-The '_proxy object_' for `constructor` specification is inspired by [awilix](https://github.com/jeffijoe/awilix).
-Thanks guys.
+The '_proxy object_' for `constructor` specification is inspired by [awilix](https://github.com/jeffijoe/awilix). Thanks
+guys.
 
 ## Installation
 
@@ -36,7 +38,8 @@ import ScanData from '../Api/Dto/Scanned.mjs';
 import {existsSync, readdirSync, readFileSync, statSync} from 'fs';
 ```
 
-but DI container cannot process these imports. Function or class should have this interface to be compatible with DI container:
+but DI container cannot process these imports. Function or class should have this interface to be compatible with DI
+container:
 
 ```ecmascript 6
 export default function ObjectFactory(spec) {/* ... */}

package/RELEASE.md

@@ -0,0 +1,24 @@
+# @teqfw/di releases
+
+## 0.11.0
+
+* Restructure `/@teqfw/di/replace` node in `teqfw.json`.
+* Remove `TeqFw_Di_Shared_Api_Enum_Area` enumeration.
+* Fix example code (`npm run example`).
+
+## 0.10.0
+
+* Improve error messaging.
+* Use '.' instead of '#' in depIDs (Vnd_Plugin#export => Vnd_Plugin.export). Both variants are available for now.
+* Experimental proxy for deps are added (Vnd_Plugin.export@@).
+
+## 0.9.0
+
+* `TeqFw_Di_Shared_Api_Enum_Area` enumeration is added;
+
+## 0.8.0
+
+* docs for plugin's teq-descriptor (see in `main` branch);
+* use object notation instead of array notation in namespace replacement statements of
+  teq-descriptor (`@teqfw/di.replace` node format is changed in `./teqfw.json`);
+* array is used as a container for upline dependencies in [SpecProxy](./src/Shared/SpecProxy.mjs) (object was);

package/bin/release/clean.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+##
+# Clean development files from release branch
+##
+DIR_ROOT=${DIR_ROOT:-$(cd "$(dirname "$0")/../../" && pwd)}
+
+rm -fr "${DIR_ROOT}/doc/"
+rm -fr "${DIR_ROOT}/node_modules/"
+rm -fr "${DIR_ROOT}/package-lock.json"
+rm -fr "${DIR_ROOT}/test/"
+rm -fr "${DIR_ROOT}/tmp/"

package/package.json

@@ -1,9 +1,7 @@
 {
   "name": "@teqfw/di",
-  "version": "0.7.0",
+  "version": "0.11.0",
   "description": "Dependency Injection container based on logical namespaces for ES6 modules.",
-  "type": "module",
-  "main": "src/Shared/Container.mjs",
   "keywords": [
     "dependency injection",
     "di",
@@ -23,6 +21,8 @@
     "email": "alex@flancer64.com",
     "url": "https://github.com/flancer64"
   },
+  "main": "src/Shared/Container.mjs",
+  "type": "module",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/teqfw/di.git"

package/src/Back/Api/Dto/Plugin/Desc.mjs

@@ -9,7 +9,12 @@ const NS = 'TeqFw_Di_Back_Api_Dto_Plugin_Desc';
 export default class TeqFw_Di_Back_Api_Dto_Plugin_Desc {
     /** @type {TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload} */
     autoload;
-    /** @type {TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace[]} */
+    /**
+     * Replacements for IDs:
+     *  - {'Interface_Name': 'Impl_Name'}: replace es6-module 'Interface_Name' with 'Impl_Name' on injection;
+     *  - {'front': {'Interface_Name': 'Impl_Name'}}: do the same for 'front' area only (should be implemented outside this plugin)
+     * @type {Object<string, string>|Object<string, Object<string, string>>}
+     */
     replace;
 }
 
@@ -23,27 +28,37 @@ TeqFw_Di_Back_Api_Dto_Plugin_Desc.REPLACE = 'replace';
  */
 export class Factory {
     constructor(spec) {
-        // EXTRACT DEPS
-        /** @type {typeof TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload} */
-        const TAutoload = spec['TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload#'];
         /** @type {TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload.Factory} */
         const fAutoload = spec['TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload#Factory$'];
-        /** @type {typeof TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace} */
-        const TReplace = spec['TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace#'];
-        /** @type {TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace.Factory} */
-        const fReplace = spec['TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace#Factory$'];
 
         /**
-         * @param {TeqFw_Di_Back_Api_Dto_Plugin_Desc|null} data
+         * @param {*} data
          * @return {TeqFw_Di_Back_Api_Dto_Plugin_Desc}
          */
         this.create = function (data = null) {
+
+            // DEFINE INNER FUNCTIONS
+            function parseReplace(data) {
+                const res = {};
+                if (typeof data === 'object')
+                    for (const ns of Object.keys(data)) {
+                        const node = data[ns];
+                        if (typeof node === 'string') {
+                            res[ns] = data[ns]; // {"interface": "impl"}
+                        } else if (typeof node === 'object') {
+                            res[ns] = {}; // {"interface": {"area": "impl"}}
+                            for (const area of Object.keys(node))
+                                if (typeof node[area] === 'string')
+                                    res[ns][area] = node[area];
+                        }
+                    }
+                return res;
+            }
+
+            // MAIN FUNCTIONALITY
             const res = new TeqFw_Di_Back_Api_Dto_Plugin_Desc();
-            res.autoload = (data?.autoload instanceof TAutoload)
-                ? data.autoload : fAutoload.create(data?.autoload);
-            res.replace = Array.isArray(data?.replace)
-                ? data.replace.map((one) => (one instanceof TReplace) ? one : fReplace.create(one))
-                : [];
+            res.autoload = fAutoload.create(data?.autoload);
+            res.replace = parseReplace(data?.replace);
             return res;
         }
     }

package/src/Shared/Api/IProxy.mjs

@@ -0,0 +1,11 @@
+/**
+ * Interface for proxy factory to create objects using 'Vnd_Plugin_Single@' & 'Vnd_Plugin_Obj@@' dependency ID.
+ * @interface
+ */
+export default class TeqFw_Di_Shared_Api_IProxy {
+    /**
+     * Get target object asynchronously.
+     * @return {Promise<*>}
+     */
+    get create() { }
+}

package/src/Shared/Container.mjs

@@ -50,11 +50,14 @@ export default class TeqFw_Di_Shared_Container {
         singletons.set('container', this); // as singleton
         singletons.set('TeqFw_Di_Shared_Container', this); // as singleton of the class
 
+        // pin itself for nested functions
+        const me = this;
+
         /**
          * Internal function to get/create object|function|class|module by given `id`.
          *
          * @param {string} mainId main object ID (singleton, module, new object, default export singleton)
-         * @param {Object.<string, boolean>} uplineDeps dependencies registry to prevent circular loop.
+         * @param {string[]} uplineDeps dependencies registry to prevent circular loop.
          * @returns {Promise<*>}
          */
         async function getObject(mainId, uplineDeps) {
@@ -122,7 +125,7 @@ export default class TeqFw_Di_Shared_Container {
                         // try to create object and start chain of deps resolving in SpecProxy
                         fnCreate();
                     } else {
-                        throw new Error('Unexpected type of loaded module.');
+                        throw new Error(`Unexpected type of factory function for '${mainId}'.`);
                     }
                     // `resolve` for this promise is called from fnCreate
                     // (fnCreate is recalled from spec proxy on every dep failure)
@@ -165,7 +168,7 @@ export default class TeqFw_Di_Shared_Container {
             const parsed = $parser.parse(mainId);
             parsed.nameModule = checkReplacements(parsed.nameModule);
             // try to find requested dependency in local storages
-            result = await getFromStorages(parsed);
+            if (!parsed.isProxy) result = await getFromStorages(parsed);
             // if not found then try to load sources and create new one
             if (result === undefined) {
                 // Sources for requested dependency are not imported or not set manually before.
@@ -181,13 +184,25 @@ export default class TeqFw_Di_Shared_Container {
                     // result as ES6 module export
                     result = module[parsed.nameExport];
                 } else {
-                    // we need use module export as factory for new object or singleton for the first time
-                    const factory = module[parsed.nameExport];
-                    factories.set(parsed.mapKey, factory);
-                    const object = await _useFactory(factory);
-                    // save singleton object in container storage
-                    if (parsed.typeTarget === ParsedId.TYPE_TARGET_SINGLETON) singletons.set(parsed.mapKey, object);
-                    result = object;
+                    // create new object (singleton or instance) using factory
+                    if (parsed.isProxy) {
+                        // we need to create proxy to resolve deps for the object later
+                        const depId = parsed.orig.replace(/@/gi, '$');
+                        result = new Proxy({dep: undefined, depId}, {
+                            get: async function (base, name) {
+                                if (name === 'create') base.dep = await me.get(base.depId);
+                                return base.dep;
+                            }
+                        });
+                    } else {
+                        // we need use module export as factory for new object or singleton for the first time
+                        const factory = module[parsed.nameExport];
+                        factories.set(parsed.mapKey, factory);
+                        const object = await _useFactory(factory);
+                        // save singleton object in container storage
+                        if (parsed.typeTarget === ParsedId.TYPE_TARGET_SINGLETON) singletons.set(parsed.mapKey, object);
+                        result = object;
+                    }
                 }
             }
             return result;
@@ -252,7 +267,7 @@ export default class TeqFw_Di_Shared_Container {
          * TODO: /bootstrap path, for example/).
          */
         this.get = async function (depId, context = null) {
-            return await getObject(depId, {});
+            return await getObject(depId, []);
         };
 
         /**

package/src/Shared/IdParser/Dto.mjs

@@ -30,6 +30,11 @@
  * Structure to store parsing results of identifiers for imports and injects.
  */
 export default class TeqFw_Di_Shared_IdParser_Dto {
+    /**
+     * 'true' if dependency should be a proxy.
+     * @type {boolean}
+     */
+    isProxy;
     /**
      * Key to map object in container's store (singletons, constructors, modules) - original id w/o '$' chars.
      * @type {string}

package/src/Shared/IdParser.mjs

@@ -2,12 +2,28 @@
 import ParsedId from './IdParser/Dto.mjs';
 
 // MODULE'S 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 {RegExp} expression for filepath based IDs (@vendor/package!module#export$$) */
 const FILEPATH_ID = /^((([a-z@])([A-Za-z0-9_\-/@]*))(!([A-Za-z0-9_\-/@]*)?((#)?([A-Za-z0-9_]*)(\${1,2})?)?)?)$/;
+/** @type {string} filesystem module mark (@vendor/package!module#export$$) */
+const FSM = '!';
+/** @type {string} new instance mark (Ns_Mod.export$$) */
+const INST = '$$';
 /** @type {RegExp} expression for logical namespace IDs (Ns_Module#export$$) */
-const LOGICAL_NS_ID = /^((([A-Z])[A-Za-z0-9_]*)(#?([A-Za-z0-9_]*)(\${1,2})?)?)$/;
+const LOGICAL_NS_ID = /^((([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_DI_ID = /^((([a-z])[A-Za-z0-9_]*)(\$\$)?)$/;
+/** @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 = '$';
 
 // MODULE'S CLASSES
 /**
@@ -49,8 +65,8 @@ export default class TeqFw_Di_Shared_IdParser {
                 result.nameModule = parts[6];
                 result.mapKey = parts[1];
                 result.typeTarget = ParsedId.TYPE_TARGET_MODULE;
-                if (parts[8] === '#') {
-                    result.nameExport = 'default';
+                if (parts[8] === EXP_OLD) {
+                    result.nameExport = DEF_EXP;
                     result.typeTarget = ParsedId.TYPE_TARGET_EXPORT;
                     result.mapKey = undefined;
                 }
@@ -60,16 +76,16 @@ export default class TeqFw_Di_Shared_IdParser {
                     result.mapKey = undefined;
                 }
                 if (parts[10]) {
-                    if (parts[10] === '$$') {
+                    if (parts[10] === INST) {
                         result.typeTarget = ParsedId.TYPE_TARGET_FACTORY;
-                    } else if (parts[10] === '$') {
+                    } else if (parts[10] === SNGLT) {
                         result.typeTarget = ParsedId.TYPE_TARGET_SINGLETON;
                     }
                     if (result.nameExport === undefined) {
-                        result.nameExport = 'default';
-                        result.mapKey = result.namePackage + '!' + result.nameModule;
+                        result.nameExport = DEF_EXP;
+                        result.mapKey = result.namePackage + FSM + result.nameModule;
                     } else {
-                        result.mapKey = result.namePackage + '!' + result.nameModule + '#' + result.nameExport;
+                        result.mapKey = result.namePackage + FSM + result.nameModule + EXP_OLD + result.nameExport;
                     }
                 }
             }
@@ -90,31 +106,59 @@ export default class TeqFw_Di_Shared_IdParser {
             result.orig = id;
             result.typeId = ParsedId.TYPE_ID_LOGICAL;
             result.nameModule = parts[2];
-            result.mapKey = result.nameModule;
+            result.isProxy = false;
+            result.mapKey = result.nameModule; // init mapKey with module's name
             result.typeTarget = ParsedId.TYPE_TARGET_MODULE;
-            if (parts[4] === '#') {
-                result.nameExport = 'default';
+            // Ns_Module.name$$[@@] - named instance [proxy]
+            if (
+                ((parts[5] === EXP) || (parts[5] === EXP_OLD))
+                && ((parts[7] === INST) || (parts[7] === P_INST))
+            ) {
+                result.isProxy = (parts[7] === P_INST);
+                result.nameExport = parts[6];
+                result.typeTarget = ParsedId.TYPE_TARGET_FACTORY;
+                result.mapKey = result.nameModule + EXP + result.nameExport;
+            }
+            // Ns_Module.name$[@] - named singleton [proxy]
+            else if (
+                ((parts[5] === EXP) || (parts[5] === EXP_OLD))
+                && ((parts[7] === SNGLT) || (parts[7] === P_SNGLT))
+            ) {
+                result.isProxy = (parts[7] === P_SNGLT);
+                result.nameExport = parts[6];
+                result.typeTarget = ParsedId.TYPE_TARGET_SINGLETON;
+                result.mapKey = result.nameModule + EXP + result.nameExport;
+            }
+            // Ns_Module.name - named export
+            else if (
+                ((parts[5] === EXP) || (parts[5] === EXP_OLD))
+                && ((parts[6] !== undefined) && (parts[6] !== ''))
+            ) {
+                result.nameExport = parts[6];
                 result.typeTarget = ParsedId.TYPE_TARGET_EXPORT;
                 result.mapKey = undefined;
             }
-            if (parts[5]) {
-                result.nameExport = parts[5];
+            // Ns_Module$$[@@]- default instance [proxy]
+            else if ((parts[4] === INST) || (parts[4] === P_INST)) {
+                result.isProxy = (parts[4] === P_INST);
+                result.nameExport = DEF_EXP;
+                result.typeTarget = ParsedId.TYPE_TARGET_FACTORY;
+            }
+            // Ns_Module$[@] - default singleton [proxy]
+            else if ((parts[4] === SNGLT) || (parts[4] === P_SNGLT)) {
+                result.isProxy = (parts[4] === P_SNGLT);
+                result.nameExport = DEF_EXP;
+                result.typeTarget = ParsedId.TYPE_TARGET_SINGLETON;
+            }
+            // Ns_Module#[.] - default export
+            else if (
+                ((parts[5] === EXP) || (parts[5] === EXP_OLD))
+                && (parts[7] === undefined)
+            ) {
+                result.nameExport = DEF_EXP;
                 result.typeTarget = ParsedId.TYPE_TARGET_EXPORT;
                 result.mapKey = undefined;
             }
-            if (parts[6]) {
-                if (parts[6] === '$$') {
-                    result.typeTarget = ParsedId.TYPE_TARGET_FACTORY;
-                } else if (parts[6] === '$') {
-                    result.typeTarget = ParsedId.TYPE_TARGET_SINGLETON;
-                }
-                if (result.nameExport === undefined) {
-                    result.nameExport = 'default';
-                    result.mapKey = result.nameModule;
-                } else {
-                    result.mapKey = result.nameModule + '#' + result.nameExport;
-                }
-            }
         }
         return result;
     }

package/src/Shared/SpecProxy.mjs

@@ -18,7 +18,7 @@ const $parser = new IdParser();
 export default class TeqFw_Di_Shared_SpecProxy {
     /**
      * @param {string} mainId ID of the constructing object ('Vendor_Module$', 'Vendor_Module$$', 'dbCfg').
-     * @param {Object.<string, Boolean>} uplineDeps All incomplete dependencies in current construction process
+     * @param {string[]} uplineDeps All incomplete dependencies in current construction process
      * (to prevent circular dependencies).
      * @param {Map} containerSingletons Container level registry with created singletons (ids: 'dbCfg', 'Module$$').
      * @param {Function} fnCreate constructing process level registry to save functions that
@@ -73,14 +73,14 @@ export default class TeqFw_Di_Shared_SpecProxy {
                     } else {
                         // check stack of incomplete dependencies
                         if (parsed.nameModule) { // don't process manually inserted singletons
-                            if (uplineDeps[parsed.nameModule]) {
+                            if (uplineDeps.includes(parsed.nameModule)) {
                                 // `dep_id` is already requested to be created, so we report it as 'main'
                                 const err = new Error(`Circular dependencies (main: ${depId}; dep: ${mainId})`);
                                 fnRejectUseFactory(err);  // reject async _useFactory
                                 throw err;                  // break sync object's constructor
                             }
                             // ... and register new one
-                            uplineDeps[parsed.nameModule] = true;
+                            uplineDeps.push(parsed.nameModule);
                         }
                         // create new required dependency for this object
                         fnGetObject(depId, uplineDeps).then((obj) => {
@@ -88,7 +88,7 @@ export default class TeqFw_Di_Shared_SpecProxy {
                             // save created `dep_id` instance to local dependencies registry
                             deps[depId] = obj;
                             // remove created dependency from circular registry
-                            uplineDeps[parsed.nameModule] = false;
+                            uplineDeps.splice(uplineDeps.indexOf(parsed.nameModule), 1);
                             // re-call main object construction function
                             fnCreate();
                         }).catch(err => {

package/src/Shared/Api/Dto/Plugin/Desc/Replace.mjs

@@ -1,63 +0,0 @@
-/**
- * DTO to represent plugin descriptor (teqfw.json) structure
- * that is related to 'di/replace' node:
- */
-// MODULE'S VARS
-const NS = 'TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace';
-
-// MODULE'S CLASSES
-export default class TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace {
-    /**
-     * Logical name for ES6 module with replacement code (Vnd_Plug_Implementation).
-     * @type {string}
-     */
-    alter;
-    /**
-     * App area to use replacement ('back', 'front', 'shared').
-     * @type {string}
-     */
-    area;
-    /**
-     * Logical name for original ES6 module (Vnd_Plug_Interface).
-     * @type {string}
-     */
-    orig;
-}
-
-// attributes names to use as aliases in queries to object props
-TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace.ALTER = 'alter';
-TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace.AREA = 'area';
-TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace.ORIG = 'orig';
-
-TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace.DATA_AREA_BACK = 'back';
-TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace.DATA_AREA_FRONT = 'front';
-TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace.DATA_AREA_SHARED = 'shared';
-
-/**
- * Factory to create new DTO instances.
- * @memberOf TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace
- */
-export class Factory {
-    constructor() {
-        /**
-         * @param {TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace|null} data
-         * @return {TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace}
-         */
-        this.create = function (data = null) {
-            const res = new TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace();
-            const clazz = TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace;
-            res.alter = data?.alter;
-            res.area = (
-                (data?.area === clazz.DATA_AREA_BACK) ||
-                (data?.area === clazz.DATA_AREA_FRONT)
-            )
-                ? data.area : clazz.DATA_AREA_SHARED;
-            res.orig = data?.orig;
-            return res;
-        }
-    }
-}
-
-// freeze DTO class to deny attributes changes and pin namespace
-Object.freeze(TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace);
-Object.defineProperty(Factory, 'name', {value: `${NS}.${Factory.constructor.name}`});