@teqfw/di 1.3.0 → 2.0.0

package/src/Container/A/Composer.js

@@ -1,69 +0,0 @@
-/**
- * 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
-         * @returns {Promise<*>}
-         */
-        this.create = async function (depId, module, stack, container) {
-            if (stack.includes(depId.origin))
-                throw new Error(`Circular dependency for '${depId.origin}'. Parents are: ${JSON.stringify(stack)}`);
-            if (depId.exportName) {
-                // use export from the es6-module
-                const stackNew = [...stack, depId.origin];
-                const {[depId.exportName]: exp} = module;
-                if (depId.composition === Defs.CF) {
-                    if (typeof exp === 'function') {
-                        // create deps for factory function
-                        const deps = specParser(exp);
-                        if (deps.length) log(`Deps for object '${depId.origin}' 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
-                    // just return the export (w/o factory function)
-                    return exp;
-            } else {
-                return module;
-            }
-        };
-
-        this.setDebug = function (data) {
-            _debug = data;
-        };
-
-        // MAIN
-    }
-};

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

@@ -1,69 +0,0 @@
-/**
- * Default parser for object keys in format:
- *   - Ns_Module.export$$(post)
- *   - node:package.export$$(post)
- *   - node:@scope/package.export$$(post)
- *
- * @namespace TeqFw_Di_Container_A_Parser_Chunk_Def
- */
-import Dto from '../../../../DepId.js';
-import Defs from '../../../../Defs.js';
-
-// VARS
-/** @type {RegExp} expression for a default object key */
-const REGEXP = /^(node:)?(@?[A-Za-z0-9_-]+\/?[A-Za-z0-9_-]*)(([.#])?([A-Za-z0-9_]*)((\$)?(\$)?)?)?(\(([A-Za-z0-9_,]*)\))?$/;
-
-/**
- * @implements TeqFw_Di_Api_Container_Parser_Chunk
- */
-export default class TeqFw_Di_Container_A_Parser_Chunk_Def {
-
-    canParse() {
-        // the default parser always tries to parse the depId
-        return true;
-    }
-
-    parse(objectKey) {
-        const res = new Dto();
-        res.origin = objectKey;
-        const parts = REGEXP.exec(objectKey);
-        if (parts) {
-            res.isNodeModule = Boolean(parts[1]); // Detect 'node:' prefix
-            res.moduleName = parts[2].replace(/^node:/, ''); // Remove 'node:' prefix
-
-            if ((parts[4] === '.') || (parts[4] === '#')) {
-                // Ns_Module.export or node:package.export
-                if ((parts[6] === '$') || (parts[6] === '$$')) {
-                    res.composition = Defs.CF;
-                    res.exportName = parts[5];
-                    res.life = (parts[6] === '$') ? Defs.LS : Defs.LI;
-                } else {
-                    res.composition = Defs.CA;
-                    res.life = Defs.LS;
-                    res.exportName = (parts[5] !== '') ? parts[5] : 'default';
-                }
-            } else if ((parts[6] === '$') || parts[6] === '$$') {
-                // Ns_Module$$ or node:package$$
-                res.composition = Defs.CF;
-                res.exportName = 'default';
-                res.life = (parts[6] === '$') ? Defs.LS : Defs.LI;
-            } else {
-                // Ns_Module or node:package (ES6 module)
-                res.composition = undefined;
-                res.exportName = undefined;
-                res.life = undefined;
-            }
-
-            // Wrappers handling
-            if (parts[10]) {
-                res.wrappers = parts[10].split(',');
-            }
-        }
-
-        // Ensure singletons for non-factory exports
-        if ((res.composition === Defs.CA) && (res.life === Defs.LI))
-            throw new Error(`Export is not a function and should be used as a singleton only: '${res.origin}'.`);
-
-        return res;
-    }
-}

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

@@ -1,66 +0,0 @@
-/**
- * Default parser for object keys in format:
- *   - Ns_Module[.|#]export$[F|A][S|I]
- *   - node:package[.|#]export$[F|A][S|I]
- *
- * @namespace TeqFw_Di_Container_A_Parser_Chunk_V02X
- */
-import Dto from '../../../../DepId.js';
-import Defs from '../../../../Defs.js';
-
-// VARS
-/** @type {RegExp} expression for a default object key */
-const REGEXP = /^(node:)?(([A-Z])[A-Za-z0-9_]*|[a-z][a-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_V02X {
-
-    canParse() {
-        // the default parser always tries to parse the depId
-        return true;
-    }
-
-    parse(objectKey) {
-        const res = new Dto();
-        res.origin = objectKey;
-        const parts = REGEXP.exec(objectKey);
-        if (parts) {
-            res.isNodeModule = Boolean(parts[1]); // Check if it starts with 'node:'
-            res.moduleName = parts[2].replace(/^node:/, ''); // Remove 'node:' if present
-
-            if (parts[5] === '.') {
-                // App_Service.export or node:package.export
-                if (parts[8] === '$') {
-                    // App_Service.export$ or node:package.export$
-                    res.composition = Defs.CF;
-                    res.exportName = parts[6];
-                    res.life = (parts[10] === Defs.LI) ? Defs.LI : Defs.LS;
-                } else {
-                    res.composition = (!parts[8] || parts[8] === Defs.CA) ? Defs.CA : Defs.CF;
-                    res.exportName = parts[6];
-                    res.life = (!parts[8] || parts[10] === Defs.LS) ? Defs.LS : Defs.LI;
-                }
-            } else if (parts[8] === '$') {
-                // App_Logger$FS or node:package$
-                res.composition = (!parts[9] || parts[9] === Defs.CF) ? Defs.CF : Defs.CA;
-                res.exportName = 'default';
-                res.life = parts[10] ? (parts[10] === Defs.LS ? Defs.LS : Defs.LI) : (res.composition === Defs.CF ? Defs.LS : Defs.LI);
-            } else {
-                // App_Service or node:package (ES6 module)
-                res.composition = undefined;
-                res.exportName = undefined;
-                res.life = undefined;
-            }
-
-        }
-
-        // Enforce singleton for non-factory exports
-        if (res.composition === Defs.CA && res.life === Defs.LI) {
-            throw new Error(`Export is not a function and should be used as a singleton only: '${res.origin}'.`);
-        }
-
-        return res;
-    }
-}

package/src/Container/Config.js

@@ -1,93 +0,0 @@
-import Container from '../Container.js';
-
-/**
- * Runtime configuration facade for the DI container.
- *
- * @implements {TeqFw_Di_Api_Container_Config}
- */
-export default class TeqFw_Di_Container_Config {
-    constructor() {
-        // VARS
-        const _container = new Container();
-        let _finalized = false;
-
-        // FUNCS
-        function assertNotFinalized() {
-            if (_finalized) throw new Error('Container configuration is finalized.');
-        }
-
-        // INSTANCE METHODS
-
-        /**
-         * Returns the parser configurator.
-         *
-         * @returns {TeqFw_Di_Api_Container_Parser}
-         */
-        this.parser = function () {
-            assertNotFinalized();
-            return _container.getParser();
-        };
-
-        /**
-         * Returns the pre-processor configurator.
-         *
-         * @returns {TeqFw_Di_Api_Container_PreProcessor}
-         */
-        this.preProcessor = function () {
-            assertNotFinalized();
-            return _container.getPreProcessor();
-        };
-
-        /**
-         * Returns the post-processor configurator.
-         *
-         * @returns {TeqFw_Di_Api_Container_PostProcessor}
-         */
-        this.postProcessor = function () {
-            assertNotFinalized();
-            return _container.getPostProcessor();
-        };
-
-        /**
-         * Returns the resolver configurator.
-         *
-         * @returns {TeqFw_Di_Api_Container_Resolver}
-         */
-        this.resolver = function () {
-            assertNotFinalized();
-            return _container.getResolver();
-        };
-
-        /**
-         * Enables test mode.
-         *
-         * @returns {void}
-         */
-        this.enableTestMode = function () {
-            assertNotFinalized();
-            _container.enableTestMode();
-        };
-
-        /**
-         * Registers a singleton or a Node.js module replacement in test mode.
-         *
-         * @param {string} depId
-         * @param {object} obj
-         * @returns {void}
-         */
-        this.register = function (depId, obj) {
-            assertNotFinalized();
-            _container.register(depId, obj);
-        };
-
-        /**
-         * Finalizes configuration and returns a runtime container instance.
-         *
-         * @returns {TeqFw_Di_Api_Container}
-         */
-        this.finalize = function () {
-            _finalized = true;
-            return _container;
-        };
-    }
-}

package/src/Container/Parser.js

@@ -1,48 +0,0 @@
-/**
- * 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

@@ -1,32 +0,0 @@
-/**
- * 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

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

@@ -1,80 +0,0 @@
-/**
- * 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/...)
- */
-
-// VARS
-const KEY_EXT = 'ext';
-const KEY_NS = 'ns';
-const KEY_PATH = 'root';
-/**
- * Namespace parts separator.
- *
- * @type {string}
- */
-const NSS = '_';
-
-// MAIN
-/**
- * @implements {TeqFw_Di_Api_Container_Resolver}
- */
-export default class TeqFw_Di_Container_Resolver {
-
-    constructor() {
-        // VARS
-        const _regNs = {};
-        let _isWindows = false; // flag of the runtime env - win or *nix/web
-        let _namespaces = [];
-        let _ps = '/'; // web & unix path separator
-
-        // INSTANCE METHODS
-
-        this.addNamespaceRoot = function (ns, path, ext) {
-            const lead = (_isWindows) ? path.replace(/^\\/, '') : path; // remove leading backslash for Win
-            const norm = lead.replace(/\\/g, '/'); // replace all windows path separators
-            const root = (_isWindows) ? `file://${norm}` : norm;
-            _regNs[ns] = {
-                [KEY_EXT]: ext ?? 'js',
-                [KEY_NS]: ns,
-                [KEY_PATH]: root,
-            };
-            _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'
-         * @returns {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;
-        };
-
-        /**
-         * 'true' - to use '\' as path separator to resolve paths.
-         * @param {boolean} isWindows
-         */
-        this.setWindowsEnv = function (isWindows = true) {
-            _isWindows = isWindows;
-            _ps = (isWindows) ? '\\' : '/';
-        };
-    }
-};

package/src/Container.js

@@ -1,187 +0,0 @@
-/**
- * The Object Container (composition root).
- * We can use static imports in the Container.
- *
- * @namespace TeqFw_Di_Container
- */
-import Composer from './Container/A/Composer.js';
-import Defs from './Defs.js';
-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_DepId} key
- * @returns {string}
- */
-function getSingletonId(key) {
-    return `${key.moduleName}#${key.exportName}`;
-}
-
-/**
- * Determines if an object, function, or primitive can be safely frozen.
- * @param {*} value - The value to check.
- * @returns {boolean} - Returns true if the value can be safely frozen.
- */
-function canBeFrozen(value) {
-    // Primitives (except objects and functions) cannot be frozen
-    if (value === null || typeof value !== 'object' && typeof value !== 'function') return false;
-    // // ES modules cannot be frozen
-    if (Object.prototype.toString.call(value) === '[object Module]') return false;
-    // check is Object is already frozen
-    return !Object.isFrozen(value);
-}
-
-// MAIN
-export default class TeqFw_Di_Container {
-
-    constructor() {
-        // VARS
-        let _composer = new Composer();
-        let _debug = false;
-        let _parser = new Parser();
-        let _postProcessor = new PostProcessor();
-        let _preProcessor = new PreProcessor();
-        let _testMode = false;
-
-        /**
-         * Registry for paths for loaded es6 modules.
-         *
-         * @type {Object<string, string>}
-         */
-        const _regPaths = {};
-        /**
-         * Registry to store singletons.
-         * @type {Object<string, object>}
-         */
-        const _regSingles = {};
-        /**
-         * Registry to store mocks for Node.js libs in the Test mode.
-         * @type {Object<string, object>}
-         */
-        const _regTestNodeLibs = {};
-
-        let _resolver = new Resolver();
-
-        // FUNCS
-
-        function log() {
-            if (_debug) console.log(...arguments);
-        }
-
-        // INSTANCE METHODS
-
-        this.get = async function (depId, stack = []) {
-            log(`Object '${depId}' is requested.`);
-            // parse the `objectKey` and get the structured DTO
-            const parsed = _parser.parse(depId);
-            // modify the original key according to some rules (replacements, etc.)
-            const key = _preProcessor.modify(parsed, stack);
-            // return existing singleton
-            if (key.life === Defs.LS) {
-                const singleId = getSingletonId(key);
-                if (_regSingles[singleId]) {
-                    log(`Existing singleton '${singleId}' is returned.`);
-                    return _regSingles[singleId];
-                }
-            }
-            // return existing node lib in the Test mode
-            if (key.isNodeModule && _testMode) {
-                const nodeId = key.origin;
-                if (_regTestNodeLibs[nodeId]) {
-                    log(`Existing nodejs lib '${nodeId}' is returned.`);
-                    return _regTestNodeLibs[nodeId];
-                }
-            }
-            // resolve a path to es6 module if not resolved before
-            if (!_regPaths[key.moduleName]) {
-                log(`ES6 module '${key.moduleName}' is not resolved yet`);
-                // convert the module name to the path to an es6-module file with a source
-                _regPaths[key.moduleName] = _resolver.resolve(key.moduleName);
-            }
-
-            // 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 an object using the composer, then modify it in post-processor
-            let res = await _composer.create(key, module, stack, this);
-            // freeze the result to prevent modifications
-            if (canBeFrozen(res)) Object.freeze(res);
-            res = await _postProcessor.modify(res, key, stack);
-            log(`Object '${depId}' is created.`);
-
-            // save singletons
-            if (key.life === Defs.LS) {
-                const singleId = getSingletonId(key);
-                _regSingles[singleId] = res;
-                log(`Object '${depId}' is saved as singleton.`);
-            }
-            return res;
-        };
-
-        /**
-         * Enables test mode, allowing manual singleton registration.
-         */
-        this.enableTestMode = function () {
-            _testMode = true;
-            log('Test mode enabled');
-        };
-
-        this.getParser = () => _parser;
-
-        this.getPreProcessor = () => _preProcessor;
-
-        this.getPostProcessor = () => _postProcessor;
-
-        this.getResolver = () => _resolver;
-
-        /**
-         * Registers a new singleton object in the Container.
-         *
-         * @param {string} depId - Dependency identifier. Must be a singleton identifier.
-         * @param {object} obj - The object to register.
-         */
-        this.register = function (depId, obj) {
-            if (!_testMode) throw new Error('Use enableTestMode() to allow it');
-
-            if (!depId || !obj) throw new Error('Both params are required');
-
-            const key = _parser.parse(depId);
-            if ((key.life !== Defs.LS) && !key.isNodeModule) throw new Error(`Only node modules & singletons can be registered: '${depId}'`);
-            if (key.life === Defs.LS) {
-                const singleId = getSingletonId(key);
-                if (_regSingles[singleId]) throw new Error(`'${depId}' is already registered`);
-                _regSingles[singleId] = obj;
-            } else if (key.isNodeModule) {
-                const nodeId = key.origin;
-                if (_regTestNodeLibs[nodeId]) throw new Error(`'${depId}' is already registered`);
-                _regTestNodeLibs[nodeId] = obj;
-            }
-
-            log(`'${depId}' is registered`);
-        };
-
-        this.setDebug = function (data) {
-            _debug = data;
-            _composer.setDebug(data);
-        };
-
-        this.setParser = (data) => _parser = data;
-
-        this.setPreProcessor = (data) => _preProcessor = data;
-
-        this.setPostProcessor = (data) => _postProcessor = data;
-
-        this.setResolver = (data) => _resolver = data;
-    }
-};