@teqfw/di 0.12.1 → 0.20.1

package/src/PreProcessor.js

@@ -0,0 +1,45 @@
+/**
+ * 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;
+ */
+export default class TeqFw_Di_PreProcessor {
+
+    constructor() {
+        // VARS
+        /**
+         * The array of handlers in the dependency order (from the basic (di) up to the app).
+         * @type {Array<function(TeqFw_Di_Api_ObjectKey, TeqFw_Di_Api_ObjectKey):TeqFw_Di_Api_ObjectKey>}
+         */
+        const _handlers = [];
+
+        // INSTANCE METHODS
+
+        /**
+         *
+         * @param {function(TeqFw_Di_Api_ObjectKey, TeqFw_Di_Api_ObjectKey):TeqFw_Di_Api_ObjectKey} hndl
+         */
+        this.addHandler = function (hndl) {
+            _handlers.push(hndl);
+        };
+
+        /**
+         * Get all pre-processing handlers.
+         * @return {Array<function(TeqFw_Di_Api_ObjectKey, TeqFw_Di_Api_ObjectKey): TeqFw_Di_Api_ObjectKey>}
+         */
+        this.getHandlers = () => _handlers;
+
+        /**
+         * @param {TeqFw_Di_Api_ObjectKey} objectKey
+         * @return {TeqFw_Di_Api_ObjectKey}
+         */
+        this.process = function (objectKey) {
+            let res = objectKey;
+            for (const one of _handlers)
+                res = one(res, objectKey);
+            return res;
+        };
+    }
+};

package/src/Resolver.js

@@ -0,0 +1,65 @@
+/**
+ * The Resolver should convert ES6 module name into the path to the sources (file path or URL).
+ *
+ * This is a base resolver that considers that:
+ *  - module name is Zend1-compatible ('Vendor_Package_Module')
+ *  - every namespace is bound to some real path ('Vendor_Package_' => '.../node_modules/@vendor/package/src/...)
+ *  - 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';
+
+// VARS
+const KEY_EXT = 'ext';
+const KEY_NS = 'ns';
+const KEY_PATH = 'root';
+/**
+ * Namespace parts separator.
+ *
+ * @type {string}
+ */
+const NSS = '_';
+
+// MAIN
+export default class TeqFw_Di_Resolver {
+
+    constructor() {
+        // VARS
+        const _regNs = {};
+        let _namespaces = [];
+        let _ps = '/'; // web & unix path separator
+
+        // INSTANCE METHODS
+
+        this.addNamespaceRoot = function (ns, path, ext) {
+            _regNs[ns] = {
+                [KEY_EXT]: ext ?? Defs.EXT,
+                [KEY_NS]: ns,
+                [KEY_PATH]: path,
+            };
+            _namespaces = Object.keys(_regNs).sort((a, b) => b.localeCompare(a));
+        };
+
+        /**
+         * 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'
+         */
+        this.resolve = function (moduleName) {
+            let root, ext, ns;
+            for (ns of _namespaces) {
+                if (moduleName.startsWith(ns)) {
+                    root = _regNs[ns][KEY_PATH];
+                    ext = _regNs[ns][KEY_EXT];
+                    break;
+                }
+            }
+            if (root && ext) {
+                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/Spec/Parser.mjs

@@ -0,0 +1,101 @@
+/**
+ * This is default parser that converts dependencies specification into array of depIds.
+ * @namespace Spec.Parser
+ */
+// IMPORTS
+
+// VARS
+const FN_ARW = /^.*\((\{[^}]*}|[^)]*)\)\s* =>.*$/s;
+const FN_CLASS = /class.*constructor.*\((.*)\).*/s;
+const FN_REG = /^function.*\((\{[^}]*}|[^)]*)\)\s*\{[^}]*}$/s;
+
+// FUNCS
+
+/**
+ * Extract spec arguments from the class constructor '({...}=>{})
+ * @param {string} spec
+ * @return {null|string}
+ */
+function specClass(spec) {
+    const parts = FN_CLASS.exec(spec);
+    if (parts?.[1]) {
+        return parts[1].replace('{', '')
+            .replace('}', '')
+            .replace(/\n/g, ' ');
+    }
+    return null;
+}
+
+/**
+ * Extract spec arguments from the arrow '({...}=>{})
+ * @param {string} spec
+ * @return {null|string}
+ */
+function specFnArrow(spec) {
+    const parts = FN_ARW.exec(spec);
+    if (parts?.[1]) {
+        return parts[1].replace('{', '')
+            .replace('}', '')
+            .replace(/\n/g, ' ');
+    }
+    return null;
+}
+
+/**
+ * Extract spec arguments from the regular 'function({...})
+ * @param {string} spec
+ * @return {null|string}
+ */
+function specFnRegular(spec) {
+    const parts = FN_REG.exec(spec);
+    if (parts?.[1]) {
+        return parts[1].replace('{', '')
+            .replace('}', '')
+            .replace(/\n/g, ' ');
+    }
+    return null;
+}
+
+function argsComplex(args) {
+    const res = [];
+    /** @type {string[]} */
+    const all = args.split(',');
+    for (const one of all) {
+        let arg = one.trim();
+        if (arg.includes('[')) {
+            // ['Vendor_App_Mod.arg1$$#adp']: arg1,
+            const norm = arg.replaceAll('\'', '')
+                .replaceAll('"', '')
+                .replace('[', '')
+                .replace(']', '');
+            const parts = norm.split(':');
+            res.push(parts[0]);
+        } else if (arg.includes(':')) {
+            // Vendor_App_Mod$$: arg1,
+            const parts = arg.split(':');
+            res.push(parts[0]);
+        } else if (arg.length) {
+            // Vendor_App_Mod$$
+            res.push(arg);
+        }
+    }
+    return res;
+}
+
+/**
+ * @param {Object} factory
+ * @return {string[]}
+ */
+export default function (factory) {
+    const res = [];
+    if (typeof factory === 'function') {
+        const def = factory.toString();
+        let spec = specFnRegular(def);
+        if (spec) return argsComplex(spec);
+        spec = specFnArrow(def);
+        if (spec) return argsComplex(spec);
+        spec = specClass(def);
+        if (spec) return argsComplex(spec);
+    }
+    return res;
+}

package/src/SpecAnalyser.js

@@ -0,0 +1,82 @@
+/**
+ * This function analyzes specification of dependencies extracted from the text definition of the function itself.
+ */
+import Defs from './Defs.js';
+
+// VARS
+const FUNC = /function\s*\w*\s*\(\s*\{([^\}]*)\}/s;
+const CLASS = /constructor\s*\(\s*\{([^\}]*)\}/s;
+
+// FUNCS
+
+/**
+ * Internal function to analyze extracted parameters.
+ *
+ * @param {string} params
+ * @return {string[]}
+ * @private
+ */
+function _analyze(params) {
+    const res = [];
+    // create wrapper for arguments and collect dependencies using Proxy
+    try {
+        const fn = new Function(`{${params}}`, 'return');
+        const spec = new Proxy({}, {
+            get: (target, prop) => res.push(prop),
+        });
+        // run wrapper and return dependencies
+        fn(spec);
+    } catch (e) {
+        const msg = `Cannot analyze the deps specification:${params}\n`
+            + `\nPlease, be sure that spec does not contain extra ')' in a comments.`
+            + `\n\nError: ${e}`;
+        throw new Error(msg);
+    }
+    return res;
+}
+
+/**
+ * @param {Function|Object} exp
+ * @return {string[]}
+ */
+function _analyzeClass(exp) {
+    const res = [];
+    // extract arguments from constructor
+    const def = exp.toString();
+    const parts = CLASS.exec(def);
+    if (parts) {
+        res.push(..._analyze(parts[1]));
+    } // else: constructor does not have arguments
+    return res;
+}
+
+/**
+ * @param {Function|Object} exp
+ * @return {string[]}
+ */
+function _analyzeFunc(exp) {
+    const res = [];
+    // extract arguments from factory function
+    const def = exp.toString();
+    const parts = FUNC.exec(def);
+    if (parts) {
+        res.push(..._analyze(parts[1]));
+    } // else: constructor does not have arguments
+    return res;
+}
+
+// MAIN
+/**
+ * @param {Function|Object} exp
+ * @return {string[]}
+ */
+export default function (exp) {
+    if (typeof exp === 'function') {
+        if (Defs.isClass(exp)) {
+            return _analyzeClass(exp);
+        } else {
+            return _analyzeFunc(exp);
+        }
+    } else
+        return [];
+}

package/teqfw.json

@@ -2,7 +2,8 @@
   "@teqfw/di": {
     "autoload": {
       "ns": "TeqFw_Di",
-      "path": "./src"
+      "path": "./src",
+      "ext": "js"
     }
   }
 }

package/webpack.config.mjs

@@ -0,0 +1,15 @@
+// const path = require('path');
+import path from 'node:path';
+
+const __dirname = path.dirname(new URL(import.meta.url).pathname);
+
+export default {
+    entry: {
+        esm: {import: './index.mjs', filename: 'di.esm.js'},
+        cjs: {import: './index.cjs', filename: 'di.cjs.js'},
+    },
+    output: {
+        path: path.resolve(__dirname, 'dist'),
+    },
+    mode: 'development',
+};

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

@@ -1,70 +0,0 @@
-/**
- * DTO to represent plugin descriptor (teqfw.json) structure
- * that is related to 'di' node:
- */
-// MODULE'S VARS
-const NS = 'TeqFw_Di_Back_Api_Dto_Plugin_Desc';
-
-// MODULE'S CLASSES
-export default class TeqFw_Di_Back_Api_Dto_Plugin_Desc {
-    /** @type {TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload} */
-    autoload;
-    /**
-     * 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;
-}
-
-// attributes names to use as aliases in queries to object props
-TeqFw_Di_Back_Api_Dto_Plugin_Desc.AUTOLOAD = 'autoload';
-TeqFw_Di_Back_Api_Dto_Plugin_Desc.REPLACE = 'replace';
-
-/**
- * Factory to create new DTO instances.
- * @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$'];
-
-        /**
-         * @param {*} data
-         * @return {TeqFw_Di_Back_Api_Dto_Plugin_Desc}
-         */
-        this.create = function (data = null) {
-
-            // FUNCS
-            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
-            const res = new TeqFw_Di_Back_Api_Dto_Plugin_Desc();
-            res.autoload = fAutoload.create(data?.autoload);
-            res.replace = parseReplace(data?.replace);
-            return res;
-        }
-    }
-}
-
-// freeze DTO class to deny attributes changes and pin namespace
-Object.freeze(TeqFw_Di_Back_Api_Dto_Plugin_Desc);

package/src/Back/Api/Dto/Scanned.mjs

@@ -1,12 +0,0 @@
-// MODULE'S CLASSES
-/**
- * Data structure for TeqFW plugins scanner (@see TeqFw_Di_Back_Plugin_Scanner).
- */
-export default class TeqFw_Di_Back_Api_Dto_Scanned {
-    /** @type {Object} 'package.json' data */
-    package;
-    /** @type {String} absolute path to the root of the plugin package */
-    path;
-    /** @type {Object} 'teqfw.json' data */
-    teqfw;
-}

package/src/Back/Api/README.md

@@ -1 +0,0 @@
-Data structures and functionality available for consumer's backend code (published API for external nodejs programs).

package/src/Back/Defaults.mjs

@@ -1,11 +0,0 @@
-/**
- * Plugin constants (hardcoded configuration) for backend code.
- */
-export default class TeqFw_Di_Back_Defaults {
-
-    NAME = '@teqfw/di'; // node in 'teqfw.json' descriptors
-
-    constructor() {
-        Object.freeze(this);
-    }
-}

package/src/Back/Plugin/Scanner.mjs

@@ -1,154 +0,0 @@
-/**
- * Scanner to lookup for Teq-plugins in given folder and 'node_modules' subfolder and to compose array with
- * 'TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload' data.
- */
-// MODULE'S IMPORT
-import ScanData from '../Api/Dto/Scanned.mjs';
-import {existsSync, readdirSync, readFileSync, statSync} from 'fs';
-import {join} from 'path';
-
-// MODULE'S VARS
-const PACKAGE = 'package.json';
-const TEQFW = 'teqfw.json';
-
-// MODULE'S CLASSES
-export default class TeqFw_Di_Back_Plugin_Scanner {
-
-    constructor(spec) {
-        // 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$'];
-        /** @type {TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload.Factory} */
-        const fAutoload = spec['TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload.Factory$'];
-
-        // INSTANCE METHODS
-
-        this.getDescriptors = async function (path) {
-            const result = [];
-            const plugins = await this.scanFilesystem(path);
-            for (const [, one] of Object.entries(plugins)) {
-                if (one.teqfw?.[DEF.NAME]) {
-                    /** @type {TeqFw_Di_Back_Api_Dto_Plugin_Desc} */
-                    const desc = fDesc.create(one.teqfw[DEF.NAME]);
-                    Object.freeze(desc);
-                    result.push(desc);
-                }
-            }
-            return result;
-        }
-
-        /**
-         *  Scan given 'path' to get namespaces mapping for TeqFW plugins.
-         * @param {String} path
-         * @return {Promise<Object.<string, TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload>>}
-         */
-        this.getNamespaces = async function (path) {
-            const result = {};
-            const plugins = await this.scanFilesystem(path);
-            for (const [path, one] of Object.entries(plugins)) {
-                if (one.teqfw?.[DEF.NAME]) {
-                    /** @type {TeqFw_Di_Back_Api_Dto_Plugin_Desc} */
-                    const desc = fDesc.create(one.teqfw[DEF.NAME]);
-                    if (desc?.autoload?.ns) {
-                        // make a copy, setup and freeze it
-                        /** @type {TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload} */
-                        const item = fAutoload.create(desc.autoload);
-                        item.path = join(path, item.path);
-                        Object.freeze(item);
-                        result[item.ns] = item;
-                    }
-                }
-            }
-            return result;
-        }
-    }
-
-    // DEFINE PROTO METHODS
-
-    /**
-     * Scan given 'path' to get JSON descriptors for TeqFW plugins ('teqfw.json')
-     * and for corresponded 'package.json' files.
-     *
-     * @param {String} path
-     * @return {Promise<Object.<string, TeqFw_Di_Back_Api_Dto_Scanned>>} Object-to-path map for found plugins
-     */
-    async scanFilesystem(path) {
-        // FUNCS
-        function readData(path) {
-            // FUNCS
-            /**
-             * Check existence of JSON file, read content, parse JSON and return data.
-             *
-             * @param {String} filename
-             * @returns {Object|null}
-             */
-            function readJson(filename) {
-                let result = null;
-                try {
-                    const stat = statSync(filename);
-                    if (stat.isFile()) {
-                        const buffer = readFileSync(filename);
-                        const content = buffer.toString();
-                        const json = JSON.parse(content);
-                        if (typeof json === 'object') {
-                            result = json;
-                        }
-                    }
-                } catch (e) {
-                    // stealth exception if JSON file does not exist.
-                    if (e.code !== 'ENOENT' && e.code !== 'ENOTDIR') {
-                        // re-throw other exceptions (wrong format or something else)
-                        throw e;
-                    }
-                }
-                return result;
-            }
-
-            // MAIN
-            let result = null;
-            const pathTeqfw = join(path, TEQFW);
-            const pathPkg = join(path, PACKAGE);
-            const dataTeqfw = readJson(pathTeqfw);
-            const dataPkg = readJson(pathPkg);
-            if ((dataTeqfw !== null) && (dataPkg !== null)) {
-                result = new ScanData();
-                result.teqfw = dataTeqfw;
-                result.package = dataPkg;
-                result.path = path;
-            }
-            return result;
-        }
-
-        // MAIN
-        const result = {};
-        // get scan data for root folder (application itself)
-        const dataRoot = readData(path);
-        if (dataRoot !== null) result[path] = dataRoot;
-        // scan 'node modules' packages for TeqFW plugins
-        const pathNodeMods = join(path, 'node_modules');
-        if (existsSync(pathNodeMods)) {
-            const packages = readdirSync(pathNodeMods);
-            for (const pack of packages) {
-                if (pack[0] === '@') {
-                    // scan scope for nested packages
-                    const pathScope = join(pathNodeMods, pack);
-                    const scopedPackages = readdirSync(pathScope);
-                    for (const sub of scopedPackages) {
-                        const pathNested = join(pathScope, sub);
-                        const dataNested = readData(pathNested);
-                        if (dataNested !== null) result[pathNested] = dataNested;
-                    }
-                } else {
-                    // check package
-                    const pathNested = join(pathNodeMods, pack);
-                    const dataNested = readData(pathNested);
-                    if (dataNested !== null) result[pathNested] = dataNested;
-                }
-            }
-        }
-        return result;
-    }
-
-}

package/src/Back/README.md

@@ -1 +0,0 @@
-This code can be used in nodejs apps only (contains nodejs imports).

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

@@ -1,50 +0,0 @@
-/**
- * DTO to represent plugin descriptor (teqfw.json) structure
- * that is related to 'di/autoload' node:
- */
-// MODULE'S VARS
-const NS = 'TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload';
-
-// MODULE'S CLASSES
-export default class TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload {
-    /** @type {string} extension for files in the namespace */
-    ext;
-    /** @type {boolean} absolute or relative mapping is used in namespace */
-    isAbsolute;
-    /** @type {string} namespace ('Vnd_Project_Plugin') */
-    ns;
-    /** @type {string} path to the root of the namespace relative to npm package root ('./src') */
-    path;
-}
-
-// attributes names to use as aliases in queries to object props
-TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload.EXT = 'ext';
-TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload.IS_ABSOLUTE = 'isAbsolute';
-TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload.NS = 'ns';
-TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload.PATH = 'path';
-
-/**
- * Factory to create new DTO instances.
- * @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
-         * @return {TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload}
-         */
-        this.create = function (data = null) {
-            const res = new TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload();
-            res.ext = data?.ext ?? 'mjs';
-            res.isAbsolute = data?.isAbsolute ?? false;
-            res.ns = data?.ns;
-            res.path = data?.path;
-            return res;
-        }
-    }
-}
-
-// freeze DTO class to deny attributes changes and pin namespace
-Object.freeze(TeqFw_Di_Shared_Api_Dto_Plugin_Desc_Autoload);

package/src/Shared/Api/IProxy.mjs

@@ -1,11 +0,0 @@
-/**
- * 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() { }
-}