@teqfw/di 1.3.0 → 2.0.1

package/src/Dto/Resolver/Config/Namespace.mjs

@@ -0,0 +1,48 @@
+// @ts-check
+
+/**
+ * DTO and factory for resolver namespace rule records.
+ */
+
+/**
+ * Runtime DTO for one namespace resolution rule.
+ */
+export class DTO {
+    /** @type {string|undefined} Namespace prefix in depId module name. */
+    prefix;
+    /** @type {string|undefined} Import target base for matched namespace. */
+    target;
+    /** @type {string|undefined} Default extension appended to matched module path. */
+    defaultExt;
+}
+
+/**
+ * Factory for resolver namespace DTO with optional immutability.
+ */
+export default class Factory {
+    /**
+     * Creates normalized resolver namespace DTO.
+     *
+     * @param {Partial<TeqFw_Di_Dto_Resolver_Config_Namespace$DTO$>|Record<string, unknown>} [input] Source values.
+     * @param {{immutable?: boolean}|Record<string, unknown>} [options] Factory options.
+     * @returns {TeqFw_Di_Dto_Resolver_Config_Namespace$DTO$}
+     */
+    create(input, options) {
+        /** @type {Partial<TeqFw_Di_Dto_Resolver_Config_Namespace$DTO$>|Record<string, unknown>} */
+        const source = (input && (typeof input === 'object')) ? input : {};
+        /** @type {{immutable?: boolean}|Record<string, unknown>} */
+        const mode = (options && (typeof options === 'object')) ? options : {};
+
+        /** @type {TeqFw_Di_Dto_Resolver_Config_Namespace$DTO$} */
+        const dto = new DTO();
+        dto.prefix = (typeof source.prefix === 'string') ? source.prefix : undefined;
+        dto.target = (typeof source.target === 'string') ? source.target : undefined;
+        dto.defaultExt = (typeof source.defaultExt === 'string') ? source.defaultExt : undefined;
+
+        if (mode.immutable === true) {
+            Object.freeze(dto);
+        }
+
+        return dto;
+    }
+}

package/src/Dto/Resolver/Config.mjs

@@ -0,0 +1,58 @@
+// @ts-check
+
+import TeqFw_Di_Dto_Resolver_Config_Namespace from './Config/Namespace.mjs';
+
+/**
+ * DTO and factory for resolver configuration records.
+ */
+
+/**
+ * Runtime DTO for resolver configuration.
+ */
+export class DTO {
+    /** @type {TeqFw_Di_Dto_Resolver_Config_Namespace$DTO$[]} Namespace resolution rules. */
+    namespaces;
+    /** @type {string|undefined} Optional node_modules root prefix for npm modules. */
+    nodeModulesRoot;
+}
+
+/**
+ * Factory for resolver configuration DTO with optional immutability.
+ */
+export default class Factory {
+    /**
+     * Creates factory instance.
+     */
+    constructor() {
+        /** @type {TeqFw_Di_Dto_Resolver_Config_Namespace} Factory for namespace DTO records. */
+        const nsFactory = new TeqFw_Di_Dto_Resolver_Config_Namespace();
+
+        /**
+         * Creates normalized resolver configuration DTO.
+         *
+         * @param {Partial<TeqFw_Di_Dto_Resolver_Config$DTO>|Record<string, unknown>} [input] Source values.
+         * @param {{immutable?: boolean}|Record<string, unknown>} [options] Factory options.
+         * @returns {TeqFw_Di_Dto_Resolver_Config$DTO}
+         */
+        this.create = function (input, options) {
+            /** @type {Partial<TeqFw_Di_Dto_Resolver_Config$DTO>|Record<string, unknown>} */
+            const source = (input && (typeof input === 'object')) ? input : {};
+            /** @type {{immutable?: boolean}|Record<string, unknown>} */
+            const mode = (options && (typeof options === 'object')) ? options : {};
+
+            /** @type {TeqFw_Di_Dto_Resolver_Config$DTO} */
+            const dto = new DTO();
+            /** @type {unknown[]} */
+            const items = Array.isArray(source.namespaces) ? source.namespaces : [];
+            dto.namespaces = items.map((item) => nsFactory.create(item, mode));
+            dto.nodeModulesRoot = (typeof source.nodeModulesRoot === 'string') ? source.nodeModulesRoot : undefined;
+
+            if (mode.immutable === true) {
+                Object.freeze(dto.namespaces);
+                Object.freeze(dto);
+            }
+
+            return dto;
+        };
+    }
+}

package/src/Enum/Composition.mjs

@@ -0,0 +1,11 @@
+// @ts-check
+
+/**
+ * Composition mode enum used in dependency identity DTO.
+ */
+const TeqFw_Di_Enum_Composition = {
+    AS_IS: 'A',
+    FACTORY: 'F',
+};
+
+export default TeqFw_Di_Enum_Composition;

package/src/Enum/Life.mjs

@@ -0,0 +1,11 @@
+// @ts-check
+
+/**
+ * Lifecycle mode enum used in dependency identity DTO.
+ */
+const TeqFw_Di_Enum_Life = {
+    SINGLETON: 'S',
+    TRANSIENT: 'T',
+};
+
+export default TeqFw_Di_Enum_Life;

package/src/Enum/Platform.mjs

@@ -0,0 +1,12 @@
+// @ts-check
+
+/**
+ * Platform enum used to resolve module loading strategy.
+ */
+const TeqFw_Di_Enum_Platform = {
+    TEQ: 'teq',
+    NODE: 'node',
+    NPM: 'npm',
+};
+
+export default TeqFw_Di_Enum_Platform;

package/src/Internal/Logger.mjs

@@ -0,0 +1,54 @@
+// @ts-check
+
+/**
+ * Internal synchronous console logger.
+ *
+ * This module is internal infrastructure and must not be exposed as a public API.
+ */
+export default class TeqFw_Di_Internal_Logger {
+    /**
+     * @param {string} scope
+     */
+    constructor(scope = 'teqfw/di') {
+        /** @type {string} */
+        const prefix = `[${scope}]`;
+
+        /**
+         * @param {string} message
+         * @returns {void}
+         */
+        this.log = function (message) {
+            console.debug(`${prefix} ${message}`);
+        };
+
+        /**
+         * @param {string} message
+         * @param {unknown} [error]
+         * @returns {void}
+         */
+        this.error = function (message, error) {
+            console.error(`${prefix} ${message}`);
+            if (error instanceof Error) {
+                console.error(error.stack ?? error.message);
+                return;
+            }
+            if (error !== undefined) {
+                console.error(error);
+            }
+        };
+    }
+}
+
+/**
+ * No-op logger for disabled logging mode.
+ */
+export const TeqFw_Di_Internal_Logger_Noop = Object.freeze({
+    /**
+     * @returns {void}
+     */
+    log() {},
+    /**
+     * @returns {void}
+     */
+    error() {},
+});

package/types.d.ts

@@ -1,34 +1,26 @@
-export {};
-
 declare global {
-  type TeqFw_Di_Api_Container = InstanceType<typeof import('./src/Api/Container.js').default>;
-  type TeqFw_Di_Api_Container_Config = InstanceType<typeof import('./src/Api/Container/Config.js').default>;
-  type TeqFw_Di_Api_Container_Parser = InstanceType<typeof import('./src/Api/Container/Parser.js').default>;
-  type TeqFw_Di_Api_Container_Parser_Chunk = InstanceType<typeof import('./src/Api/Container/Parser/Chunk.js').default>;
-  type TeqFw_Di_Api_Container_PostProcessor = InstanceType<typeof import('./src/Api/Container/PostProcessor.js').default>;
-  type TeqFw_Di_Api_Container_PostProcessor_Chunk = InstanceType<
-    typeof import('./src/Api/Container/PostProcessor/Chunk.js').default
-  >;
-  type TeqFw_Di_Api_Container_PreProcessor = InstanceType<typeof import('./src/Api/Container/PreProcessor.js').default>;
-  type TeqFw_Di_Api_Container_PreProcessor_Chunk = InstanceType<
-    typeof import('./src/Api/Container/PreProcessor/Chunk.js').default
-  >;
-  type TeqFw_Di_Api_Container_Resolver = InstanceType<typeof import('./src/Api/Container/Resolver.js').default>;
-  type TeqFw_Di_Container = InstanceType<typeof import('./src/Container.js').default>;
-  type TeqFw_Di_Container_A_Composer = InstanceType<typeof import('./src/Container/A/Composer.js').default>;
-  type TeqFw_Di_Container_A_Composer_A_SpecParser = typeof import('./src/Container/A/Composer/A/SpecParser.js').default;
-  type TeqFw_Di_Container_A_Parser_Chunk_Def = InstanceType<
-    typeof import('./src/Container/A/Parser/Chunk/Def.js').default
-  >;
-  type TeqFw_Di_Container_A_Parser_Chunk_V02X = InstanceType<
-    typeof import('./src/Container/A/Parser/Chunk/V02X.js').default
-  >;
-  type TeqFw_Di_Container_Config = InstanceType<typeof import('./src/Container/Config.js').default>;
-  type TeqFw_Di_Container_Parser = InstanceType<typeof import('./src/Container/Parser.js').default>;
-  type TeqFw_Di_Container_PostProcessor = InstanceType<typeof import('./src/Container/PostProcessor.js').default>;
-  type TeqFw_Di_Container_PreProcessor = InstanceType<typeof import('./src/Container/PreProcessor.js').default>;
-  type TeqFw_Di_Container_Resolver = InstanceType<typeof import('./src/Container/Resolver.js').default>;
-  type TeqFw_Di_Defs = typeof import('./src/Defs.js').default;
-  type TeqFw_Di_DepId = InstanceType<typeof import('./src/DepId.js').default>;
-  type TeqFw_Di_Pre_Replace = InstanceType<typeof import('./src/Pre/Replace.js').default>;
+  type TeqFw_Di_Config_NamespaceRegistry = import("./src/Config/NamespaceRegistry.mjs").default;
+  type TeqFw_Di_Container = import("./src/Container.mjs").default;
+  type TeqFw_Di_Container_Instantiate_ExportSelector = import("./src/Container/Instantiate/ExportSelector.mjs").default;
+  type TeqFw_Di_Container_Instantiate_Instantiator = import("./src/Container/Instantiate/Instantiator.mjs").default;
+  type TeqFw_Di_Container_Lifecycle_Registry = import("./src/Container/Lifecycle/Registry.mjs").default;
+  type TeqFw_Di_Container_Resolve_GraphResolver = import("./src/Container/Resolve/GraphResolver.mjs").default;
+  type TeqFw_Di_Container_Wrapper_Executor = import("./src/Container/Wrapper/Executor.mjs").default;
+  type TeqFw_Di_Def_Parser = import("./src/Def/Parser.mjs").default;
+  type TeqFw_Di_DepId = import("./src/Dto/DepId.mjs").default;
+  type TeqFw_Di_DepId$DTO = import("./src/Dto/DepId.mjs").DTO;
+  type TeqFw_Di_Dto_DepId = import("./src/Dto/DepId.mjs").default;
+  type TeqFw_Di_Dto_DepId$DTO = import("./src/Dto/DepId.mjs").DTO;
+  type TeqFw_Di_Dto_Resolver_Config = import("./src/Dto/Resolver/Config.mjs").default;
+  type TeqFw_Di_Dto_Resolver_Config$DTO = import("./src/Dto/Resolver/Config.mjs").DTO;
+  type TeqFw_Di_Dto_Resolver_Config_Namespace = import("./src/Dto/Resolver/Config/Namespace.mjs").default;
+  type TeqFw_Di_Dto_Resolver_Config_Namespace$DTO = import("./src/Dto/Resolver/Config/Namespace.mjs").DTO;
+  type TeqFw_Di_Dto_Resolver_Config_Namespace$DTO$ = import("./src/Dto/Resolver/Config/Namespace.mjs").DTO;
+  type TeqFw_Di_Enum_Composition = typeof import("./src/Enum/Composition.mjs").default;
+  type TeqFw_Di_Enum_Life = typeof import("./src/Enum/Life.mjs").default;
+  type TeqFw_Di_Enum_Platform = typeof import("./src/Enum/Platform.mjs").default;
+  type TeqFw_Di_Internal_Logger = import("./src/Internal/Logger.mjs").default;
+  type TeqFw_Di_Resolver = import("./src/Container/Resolver.mjs").default;
 }
+
+export {};

package/src/Api/Container/Config.js

@@ -1,73 +0,0 @@
-/**
- * Public configuration API of the DI container.
- *
- * This is not executable code, it is just for documentation purposes (similar to .h files in the C/C++ language).
- * @interface
- */
-export default class TeqFw_Di_Api_Container_Config {
-
-    /**
-     * Returns the parser configurator.
-     *
-     * @returns {TeqFw_Di_Api_Container_Parser}
-     */
-    parser() {
-        throw new Error('TeqFw_Di_Api_Container_Config#parser is abstract.');
-    }
-
-    /**
-     * Returns the pre-processor configurator.
-     *
-     * @returns {TeqFw_Di_Api_Container_PreProcessor}
-     */
-    preProcessor() {
-        throw new Error('TeqFw_Di_Api_Container_Config#preProcessor is abstract.');
-    }
-
-    /**
-     * Returns the post-processor configurator.
-     *
-     * @returns {TeqFw_Di_Api_Container_PostProcessor}
-     */
-    postProcessor() {
-        throw new Error('TeqFw_Di_Api_Container_Config#postProcessor is abstract.');
-    }
-
-    /**
-     * Returns the resolver configurator.
-     *
-     * @returns {TeqFw_Di_Api_Container_Resolver}
-     */
-    resolver() {
-        throw new Error('TeqFw_Di_Api_Container_Config#resolver is abstract.');
-    }
-
-    /**
-     * Enables test mode.
-     *
-     * @returns {void}
-     */
-    enableTestMode() {
-        throw new Error('TeqFw_Di_Api_Container_Config#enableTestMode is abstract.');
-    }
-
-    /**
-     * Registers a singleton or a Node.js module replacement in test mode.
-     *
-     * @param {string} depId
-     * @param {object} obj
-     * @returns {void}
-     */
-    register(depId, obj) {
-        throw new Error('TeqFw_Di_Api_Container_Config#register is abstract.');
-    }
-
-    /**
-     * Finalizes configuration and returns a runtime container instance.
-     *
-     * @returns {TeqFw_Di_Api_Container}
-     */
-    finalize() {
-        throw new Error('TeqFw_Di_Api_Container_Config#finalize is abstract.');
-    }
-}

package/src/Api/Container/Parser/Chunk.js

@@ -1,27 +0,0 @@
-/**
- * Interface for one chunk of the runtime dependency ID parser.
- *
- * This is not executable code, it is just for documentation purposes (similar to .h files in the C/C++ language).
- * @interface
- */
-export default class TeqFw_Di_Api_Container_Parser_Chunk {
-
-    /**
-     * Returns 'true' if this chunk can parse the given dependency ID.
-     *
-     * @param {string} depId
-     * @returns {boolean}
-     */
-    canParse(depId) {
-        throw new Error('TeqFw_Di_Api_Container_Parser_Chunk#canParse is abstract.');
-    }
-
-    /**
-     * Parses a string ID for a runtime dependency and returns structured data (DTO).
-     * @param {string} depId
-     * @returns {TeqFw_Di_DepId}
-     */
-    parse(depId) {
-        throw new Error('TeqFw_Di_Api_Container_Parser_Chunk#parse is abstract.');
-    }
-};

package/src/Api/Container/Parser.js

@@ -1,34 +0,0 @@
-/**
- * Interface for the parser of the runtime dependency ID.
- *
- * This is not executable code, it is just for documentation purposes (similar to .h files in the C/C++ language).
- * @interface
- */
-export default class TeqFw_Di_Api_Container_Parser {
-    /**
-     * Adds the given chunk to the parser.
-     *
-     * @param {TeqFw_Di_Api_Container_Parser_Chunk} chunk
-     */
-    addChunk(chunk) {
-        throw new Error('TeqFw_Di_Api_Container_Parser#addChunk is abstract.');
-    }
-
-    /**
-     * Parse given dependency ID and return structured data as DTO.
-     * @param {string} depId
-     * @returns {TeqFw_Di_DepId}
-     */
-    parse(depId) {
-        throw new Error('TeqFw_Di_Api_Container_Parser#parse is abstract.');
-    }
-
-    /**
-     * Sets the default chunk of the parser.
-     *
-     * @param {TeqFw_Di_Api_Container_Parser_Chunk} chunk
-     */
-    setDefaultChunk(chunk) {
-        throw new Error('TeqFw_Di_Api_Container_Parser#setDefaultChunk is abstract.');
-    }
-}

package/src/Api/Container/PostProcessor/Chunk.js

@@ -1,17 +0,0 @@
-/**
- * Interface for one chunk of the post-processor that modifies result.
- *
- * This is not executable code, it is just for documentation purposes (similar to .h files in the C/C++ language).
- * @interface
- */
-export default class TeqFw_Di_Api_Container_PostProcessor_Chunk {
-
-    /**
-     * Modify result before returning to the caller.
-     * @param {*} obj - created object
-     * @param {TeqFw_Di_DepId} originalId - original `depId` DTO
-     * @param {string[]} stack - stack of parents depIds
-     * @returns {*} modified object
-     */
-    modify(obj, originalId, stack) {}
-};

package/src/Api/Container/PostProcessor.js

@@ -1,29 +0,0 @@
-/**
- * Interface for the post-processor of the result object.
- *
- * This is not executable code, it is just for documentation purposes (similar to .h files in the C/C++ language).
- * @interface
- */
-export default class TeqFw_Di_Api_Container_PostProcessor {
-    /**
-     * Adds the given chunk to the parser.
-     *
-     * @param {TeqFw_Di_Api_Container_PostProcessor_Chunk} chunk
-     */
-    addChunk(chunk) {
-        throw new Error('TeqFw_Di_Api_Container_PostProcessor#addChunk is abstract.');
-    }
-
-    /**
-     * Modifies the result of the object composition.
-     *
-     * @param {*} obj - The result object to be modified.
-     * @param {TeqFw_Di_DepId} depId - The original depID DTO.
-     * @param {string[]} stack - The stack of parent IDs.
-     * @returns {Promise<*>}
-     */
-    modify(obj, depId, stack) {
-        throw new Error('TeqFw_Di_Api_Container_PostProcessor#modify is abstract.');
-    }
-
-}

package/src/Api/Container/PreProcessor/Chunk.js

@@ -1,19 +0,0 @@
-/**
- * Interface for one chunk of the pre-processor that modify initial `depId`.
- *
- * This is not executable code, it is just for documentation purposes (similar to .h files in the C/C++ language).
- * @interface
- */
-export default class TeqFw_Di_Api_Container_PreProcessor_Chunk {
-
-    /**
-     * Modify runtime dependency ID before creating any object.
-     * @param {TeqFw_Di_DepId} depId - `depId` DTO after all previous pre-processing steps
-     * @param {TeqFw_Di_DepId} originalId - original `depId` DTO
-     * @param {string[]} stack - stack of parents depIds
-     * @returns {TeqFw_Di_DepId}
-     */
-    modify(depId, originalId, stack) {
-        throw new Error('TeqFw_Di_Api_Container_PreProcessor_Chunk#modify is abstract.');
-    }
-};

package/src/Api/Container/PreProcessor.js

@@ -1,27 +0,0 @@
-/**
- * Interface for the pre-processor of the runtime dependency ID.
- *
- * This is not executable code, it is just for documentation purposes (similar to .h files in the C/C++ language).
- * @interface
- */
-export default class TeqFw_Di_Api_Container_PreProcessor {
-    /**
-     * Adds the given chunk to the parser.
-     *
-     * @param {TeqFw_Di_Api_Container_PreProcessor_Chunk} chunk
-     */
-    addChunk(chunk) {
-        throw new Error('TeqFw_Di_Api_Container_PreProcessor#addChunk is abstract.');
-    }
-
-    /**
-     * Modify parsed depID and return it.
-     * @param {TeqFw_Di_DepId} depId - The depID as DTO.
-     * @param {string[]} stack - The stack of parent IDs.
-     * @returns {TeqFw_Di_DepId} -
-     */
-    modify(depId, stack) {
-        throw new Error('TeqFw_Di_Api_Container_PreProcessor#modify is abstract.');
-    }
-
-}

package/src/Api/Container/Resolver.js

@@ -1,18 +0,0 @@
-/**
- * Interface for the resolver to map a module name of the dependency ID into the path to the sources.
- *
- * This is not executable code, it is just for documentation purposes (similar to .h files in the C/C++ language).
- * @interface
- */
-export default class TeqFw_Di_Api_Container_Resolver {
-
-    /**
-     * 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'
-     */
-    resolve(moduleName) {
-        throw new Error('TeqFw_Di_Api_Container_Resolver#resolve is abstract.');
-    }
-
-}

package/src/Api/Container.js

@@ -1,19 +0,0 @@
-/**
- * Public runtime API of the DI container.
- *
- * This is not executable code, it is just for documentation purposes (similar to .h files in the C/C++ language).
- * @interface
- */
-export default class TeqFw_Di_Api_Container {
-
-    /**
-     * Resolves a dependency by its identifier and returns the result.
-     *
-     * @param {string} depId
-     * @param {string[]} [stack]
-     * @returns {Promise<*>}
-     */
-    get(depId, stack) {
-        throw new Error('TeqFw_Di_Api_Container#get is abstract.');
-    }
-}

package/src/Container/A/Composer/A/SpecParser.js

@@ -1,86 +0,0 @@
-/**
- * This function analyses specification of dependencies extracted from the text definition of the function itself.
- *
- * This is a local module and is used only inside the `TeqFw_Di_Container_A_Composer` space.
- *
- * @namespace TeqFw_Di_Container_A_Composer_A_SpecParser
- */
-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
- * @returns {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
- * @returns {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
- * @returns {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[2]));
-    } // else: constructor does not have arguments
-    return res;
-}
-
-// MAIN
-/**
- * @param {Function|Object} exp
- * @returns {string[]}
- */
-export default function (exp) {
-    if (typeof exp === 'function') {
-        if (Defs.isClass(exp)) {
-            return _analyzeClass(exp);
-        } else {
-            return _analyzeFunc(exp);
-        }
-    } else
-        return [];
-}