@teqfw/di 0.10.0 → 0.12.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

@@ -1,5 +1,11 @@
 # @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.

package/bin/release/clean.sh

@@ -4,6 +4,7 @@
 ##
 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/"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teqfw/di",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Dependency Injection container based on logical namespaces for ES6 modules.",
   "keywords": [
     "dependency injection",

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 {Object<string, 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;
 }
 
@@ -22,28 +27,37 @@ TeqFw_Di_Back_Api_Dto_Plugin_Desc.REPLACE = 'replace';
  * @memberOf TeqFw_Di_Back_Api_Dto_Plugin_Desc
  */
 export class Factory {
+    static namespace = NS;
+
     constructor(spec) {
         /** @type {TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload.Factory} */
-        const fAutoload = spec['TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload#Factory$'];
-        /** @type {TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace.Factory} */
-        const fReplace = spec['TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace#Factory$'];
+        const fAutoload = spec['TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload.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
+            // FUNCS
             function parseReplace(data) {
                 const res = {};
                 if (typeof data === 'object')
-                    for (const ns of Object.keys(data))
-                        res[ns] = fReplace.create(data[ns]);
+                    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
+            // MAIN
             const res = new TeqFw_Di_Back_Api_Dto_Plugin_Desc();
             res.autoload = fAutoload.create(data?.autoload);
             res.replace = parseReplace(data?.replace);
@@ -54,4 +68,3 @@ export class Factory {
 
 // freeze DTO class to deny attributes changes and pin namespace
 Object.freeze(TeqFw_Di_Back_Api_Dto_Plugin_Desc);
-Object.defineProperty(Factory, 'name', {value: `${NS}.${Factory.constructor.name}`});

package/src/Back/Plugin/Scanner.mjs

@@ -15,15 +15,15 @@ const TEQFW = 'teqfw.json';
 export default class TeqFw_Di_Back_Plugin_Scanner {
 
     constructor(spec) {
-        // EXTRACT DEPS
+        // DEPS
         /** @type {TeqFw_Di_Back_Defaults} */
         const DEF = spec['TeqFw_Di_Back_Defaults$'];
         /** @type {TeqFw_Di_Back_Api_Dto_Plugin_Desc.Factory} */
-        const fDesc = spec['TeqFw_Di_Back_Api_Dto_Plugin_Desc#Factory$'];
+        const fDesc = spec['TeqFw_Di_Back_Api_Dto_Plugin_Desc.Factory$'];
         /** @type {TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload.Factory} */
-        const fAutoload = spec['TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload#Factory$'];
+        const fAutoload = spec['TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload.Factory$'];
 
-        // DEFINE INSTANCE METHODS
+        // INSTANCE METHODS
 
         this.getDescriptors = async function (path) {
             const result = [];
@@ -75,9 +75,9 @@ export default class TeqFw_Di_Back_Plugin_Scanner {
      * @return {Promise<Object.<string, TeqFw_Di_Back_Api_Dto_Scanned>>} Object-to-path map for found plugins
      */
     async scanFilesystem(path) {
-        // DEFINE INNER FUNCTIONS
+        // FUNCS
         function readData(path) {
-            // DEFINE INNER FUNCTIONS
+            // FUNCS
             /**
              * Check existence of JSON file, read content, parse JSON and return data.
              *
@@ -106,7 +106,7 @@ export default class TeqFw_Di_Back_Plugin_Scanner {
                 return result;
             }
 
-            // MAIN FUNCTIONALITY
+            // MAIN
             let result = null;
             const pathTeqfw = join(path, TEQFW);
             const pathPkg = join(path, PACKAGE);
@@ -121,7 +121,7 @@ export default class TeqFw_Di_Back_Plugin_Scanner {
             return result;
         }
 
-        // MAIN FUNCTIONALITY
+        // MAIN
         const result = {};
         // get scan data for root folder (application itself)
         const dataRoot = readData(path);

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

@@ -28,6 +28,8 @@ TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload.PATH = 'path';
  * @memberOf TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload
  */
 export class Factory {
+    static namespace = NS;
+
     constructor() {
         /**
          * @param {TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload|null} data
@@ -46,4 +48,3 @@ export class Factory {
 
 // freeze DTO class to deny attributes changes and pin namespace
 Object.freeze(TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload);
-Object.defineProperty(Factory, 'name', {value: `${NS}.${Factory.constructor.name}`});

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

@@ -62,7 +62,7 @@ export default class TeqFw_Di_Shared_Container {
          */
         async function getObject(mainId, uplineDeps) {
 
-            // DEFINE INNER FUNCTIONS
+            // FUNCS
             /**
              * Add 'spec' proxy as fnConstruct argument and create new object and all deps.
              *
@@ -73,7 +73,7 @@ export default class TeqFw_Di_Shared_Container {
             function _useFactory(fnConstruct) {
                 // This promise will be resolved after all dependencies in spec proxy will be created.
                 return new Promise(function (resolve, reject) {
-                    // MAIN FUNCTIONALITY
+                    // MAIN
                     const constructorType = typeof fnConstruct;
                     if (constructorType === 'object') {
                         // `constructor` is an object, clone this fnConstruct and return cloned object
@@ -162,7 +162,7 @@ export default class TeqFw_Di_Shared_Container {
                 return orig;
             }
 
-            // MAIN FUNCTIONALITY
+            // MAIN
             let result;
             /** @type {TeqFw_Di_Shared_IdParser_Dto} */
             const parsed = $parser.parse(mainId);

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

@@ -1,50 +0,0 @@
-/**
- * DTO to represent plugin descriptor (teqfw.json) structure
- * that is related to 'di/replace' node:
- */
-// MODULE'S IMPORT
-import AREA from '../../../Enum/Area.mjs';
-// 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 {
-    /**
-     * App area to use replacement ('back', 'front', 'shared').
-     * @type {string}
-     */
-    area;
-    /**
-     * Logical name for ES6 module with replacement code (Vnd_Plug_Implementation).
-     * @type {string}
-     */
-    ns;
-}
-
-// attributes names to use as aliases in queries to object props
-TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace.AREA = 'area';
-TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Replace.NS = 'ns';
-
-/**
- * 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();
-            res.ns = data?.ns;
-            res.area = ((data?.area === AREA.BACK) || (data?.area === AREA.FRONT))
-                ? data.area : AREA.SHARED;
-            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}`});

package/src/Shared/Api/Enum/Area.mjs

@@ -1,10 +0,0 @@
-/**
- * Enumeration for application areas.
- */
-const TeqFw_Di_Shared_Api_Enum_Area = {
-    BACK: 'back', // nodejs compatible 'import' is allowed
-    FRONT: 'front', // browser compatible 'import' is allowed
-    SHARED: 'shared', // relative 'import' only is allowed
-}
-Object.freeze(TeqFw_Di_Shared_Api_Enum_Area);
-export default TeqFw_Di_Shared_Api_Enum_Area;

package/src/Shared/Api/IFactory.mjs

@@ -1,11 +0,0 @@
-/**
- * Interface for factory to create objects.
- * @interface
- */
-export default class TeqFw_Di_Shared_Api_IFactory {
-    /**
-     * @param opts
-     * @return {*}
-     */
-    async create(opts = null) {}
-}