@teqfw/di 2.4.0 → 2.5.1

package/src/Container/Wrapper/Executor.mjs

@@ -1,5 +1,10 @@
 // @ts-check
 
+/**
+ * @namespace TeqFw_Di_Container_Wrapper_Executor
+ * @description Applies wrapper pipeline to resolved values.
+ */
+
 /**
  * Wrapper-stage executor.
  *
@@ -25,7 +30,7 @@ export default class TeqFw_Di_Container_Wrapper_Executor {
         /**
          * Applies wrappers in declaration order.
          *
-         * @param {TeqFw_Di_DepId$DTO} depId
+         * @param {TeqFw_Di_DepId__DTO} depId
          * @param {unknown} value
          * @param {object} moduleNamespace
          * @returns {unknown}

package/src/Container.mjs

@@ -1,5 +1,10 @@
 // @ts-check
 
+/**
+ * @namespace TeqFw_Di_Container
+ * @description DI container orchestration entry point.
+ */
+
 import TeqFw_Di_Def_Parser from './Def/Parser.mjs';
 import {Factory as TeqFw_Di_Dto_Resolver_Config_Factory} from './Dto/Resolver/Config.mjs';
 import TeqFw_Di_Resolver from './Container/Resolver.mjs';
@@ -30,11 +35,11 @@ export default class TeqFw_Di_Container {
     constructor() {
         /** @type {TeqFw_Di_Container_State} */
         let state = 'notConfigured';
-        /** @type {((depId: TeqFw_Di_DepId$DTO) => TeqFw_Di_DepId$DTO)[]} */
+        /** @type {((depId: TeqFw_Di_DepId__DTO) => TeqFw_Di_DepId__DTO)[]} */
         const preprocess = [];
         /** @type {((value: unknown) => unknown)[]} */
         const postprocess = [];
-        /** @type {TeqFw_Di_Dto_Resolver_Config_Namespace$DTO[]} */
+        /** @type {TeqFw_Di_Dto_Resolver_Config_Namespace__DTO[]} */
         const namespaceRoots = [];
         /** @type {Map<string, unknown>} */
         const mockRegistry = new Map();
@@ -45,7 +50,7 @@ export default class TeqFw_Di_Container {
 
         /** @type {TeqFw_Di_Def_Parser} */
         let parser = new TeqFw_Di_Def_Parser();
-        /** @type {TeqFw_Di_Dto_Resolver_Config$Factory} */
+        /** @type {TeqFw_Di_Dto_Resolver_Config__Factory} */
         const configFactory = new TeqFw_Di_Dto_Resolver_Config_Factory();
         /** @type {TeqFw_Di_Resolver|undefined} */
         let resolver;
@@ -61,7 +66,7 @@ export default class TeqFw_Di_Container {
         const wrapperExecutor = new TeqFw_Di_Container_Wrapper_Executor();
 
         /**
-         * @param {TeqFw_Di_DepId$DTO} depId
+         * @param {TeqFw_Di_DepId__DTO} depId
          * @returns {string}
          */
         const getKey = function (depId) {
@@ -81,7 +86,7 @@ export default class TeqFw_Di_Container {
         /**
          * Canonical structural identity excluding `origin`.
          *
-         * @param {TeqFw_Di_DepId$DTO} depId
+         * @param {TeqFw_Di_DepId__DTO} depId
          * @returns {string}
          */
         const getMockKey = function (depId) {
@@ -138,11 +143,11 @@ export default class TeqFw_Di_Container {
         /**
          * Applies ordered preprocess pipeline.
          *
-         * @param {TeqFw_Di_DepId$DTO} depId
-         * @returns {TeqFw_Di_DepId$DTO}
+         * @param {TeqFw_Di_DepId__DTO} depId
+         * @returns {TeqFw_Di_DepId__DTO}
          */
         const applyPreprocess = function (depId) {
-            /** @type {TeqFw_Di_DepId$DTO} */
+            /** @type {TeqFw_Di_DepId__DTO} */
             let current = depId;
             for (const fn of preprocess) {
                 current = fn(current);
@@ -167,21 +172,36 @@ export default class TeqFw_Di_Container {
 
         /**
          * @param {object} namespace
-         * @param {TeqFw_Di_DepId$DTO} depId
+         * @param {TeqFw_Di_DepId__DTO} depId
          * @returns {Record<string, unknown>}
          */
         const readDepsDecl = function (namespace, depId) {
             /** @type {unknown} */
             const deps = Reflect.get(namespace, '__deps__');
             if (deps === undefined) return {};
-            if ((deps !== null) && (typeof deps === 'object') && !Array.isArray(deps)) {
-                const exportName = depId.exportName === null ? 'default' : depId.exportName;
-                const exportScoped = Reflect.get(/** @type {object} */ (deps), exportName);
-                if ((exportScoped !== undefined) && (exportScoped !== null) && (typeof exportScoped === 'object') && !Array.isArray(exportScoped)) {
-                    return /** @type {Record<string, unknown>} */ (exportScoped);
+            if ((deps === null) || (typeof deps !== 'object') || Array.isArray(deps)) {
+                throw new Error('__deps__ must be a plain object.');
+            }
+            const exportName = depId.exportName === null ? 'default' : depId.exportName;
+            const exportScoped = Reflect.get(/** @type {object} */ (deps), exportName);
+            if ((exportScoped !== undefined) && (exportScoped !== null) && (typeof exportScoped === 'object') && !Array.isArray(exportScoped)) {
+                const values = Object.values(/** @type {Record<string, unknown>} */ (exportScoped));
+                if (!values.every((value) => typeof value === 'string')) {
+                    throw new Error('__deps__ export entries must map dependency names to CDC strings.');
+                }
+                return /** @type {Record<string, unknown>} */ (exportScoped);
+            }
+            if (exportName === 'default') {
+                const values = Object.values(/** @type {Record<string, unknown>} */ (deps));
+                if (values.every((value) => typeof value === 'string')) {
+                    return /** @type {Record<string, unknown>} */ (deps);
+                }
+                if (values.every((value) => (value !== null) && (typeof value === 'object') && !Array.isArray(value))) {
+                    return {};
                 }
+                throw new Error('__deps__ must be either flat or export-scoped.');
             }
-            return /** @type {Record<string, unknown>} */ (deps);
+            return {};
         };
 
         /**
@@ -223,7 +243,7 @@ export default class TeqFw_Di_Container {
         /**
          * Registers preprocess extension before first resolution.
          *
-         * @param {(depId: TeqFw_Di_DepId$DTO) => TeqFw_Di_DepId$DTO} fn
+         * @param {(depId: TeqFw_Di_DepId__DTO) => TeqFw_Di_DepId__DTO} fn
          * @returns {void}
          */
         this.addPreprocess = function (fn) {
@@ -329,12 +349,12 @@ export default class TeqFw_Di_Container {
                 logger.log(`Container.get: cdc='${cdc}'.`);
                 initializeInfrastructure();
                 logger.log(`Container.state: '${state}'.`);
-                /** @type {TeqFw_Di_DepId$DTO} */
+                /** @type {TeqFw_Di_DepId__DTO} */
                 stage = 'parse';
                 logger.log('Container.pipeline: parse:entry.');
                 const parsed = parser.parse(cdc);
                 logger.log(`Container.pipeline: parse:exit '${parsed.platform}::${parsed.moduleName}'.`);
-                /** @type {TeqFw_Di_DepId$DTO} */
+                /** @type {TeqFw_Di_DepId__DTO} */
                 stage = 'preprocess';
                 logger.log('Container.pipeline: preprocess:entry.');
                 const root = applyPreprocess(parsed);
@@ -356,7 +376,7 @@ export default class TeqFw_Di_Container {
                 } else {
                     logger.log('Container.pipeline: mock-lookup:disabled.');
                 }
-                /** @type {Map<string, {depId: TeqFw_Di_DepId$DTO, namespace: object}>} */
+                /** @type {Map<string, {depId: TeqFw_Di_DepId__DTO, namespace: object}>} */
                 stage = 'resolve';
                 logger.log('Container.pipeline: resolve:entry.');
                 const graph = await graphResolver.resolve(root);
@@ -385,7 +405,7 @@ export default class TeqFw_Di_Container {
                         for (const [name, cdc] of Object.entries(depsDecl)) {
                             /** @type {string} */
                             const childCdc = /** @type {string} */ (cdc);
-                            /** @type {TeqFw_Di_DepId$DTO} */
+                            /** @type {TeqFw_Di_DepId__DTO} */
                             const childDepId = parser.parse(childCdc);
                             deps[name] = build(getKey(childDepId));
                         }

package/src/Def/Parser.mjs

@@ -1,5 +1,10 @@
 // @ts-check
 
+/**
+ * @namespace TeqFw_Di_Def_Parser
+ * @description CDC parser that builds dependency identity DTOs.
+ */
+
 import TeqFw_Di_Enum_Composition from '../Enum/Composition.mjs';
 import TeqFw_Di_Enum_Life from '../Enum/Life.mjs';
 import TeqFw_Di_Enum_Platform from '../Enum/Platform.mjs';
@@ -13,7 +18,7 @@ export default class TeqFw_Di_Def_Parser {
      * Creates parser instance.
      */
     constructor() {
-        /** @type {TeqFw_Di_Dto_DepId$Factory} Factory used to construct dependency identity DTO. */
+        /** @type {TeqFw_Di_Dto_DepId__Factory} Factory used to construct dependency identity DTO. */
         const depIdFactory = new TeqFw_Di_Dto_DepId_Factory();
         /** @type {{log(message: string): void}|null} */
         let logger = null;
@@ -22,7 +27,7 @@ export default class TeqFw_Di_Def_Parser {
          * Parses one CDC identifier and returns normalized frozen dependency DTO.
          *
          * @param {string} cdc CDC identifier string.
-         * @returns {TeqFw_Di_DepId$DTO}
+         * @returns {TeqFw_Di_DepId__DTO}
          */
         this.parse = function (cdc) {
             if (logger) logger.log(`Parser.parse: input='${cdc}'.`);
@@ -71,7 +76,7 @@ export default class TeqFw_Di_Def_Parser {
                 }
             } else {
                 if (source.includes('$')) throw new Error('Invalid lifecycle encoding.');
-                if (/(?:^|[^_])_[a-z][0-9A-Za-z]*$/.test(source)) {
+                if ((platform !== TeqFw_Di_Enum_Platform.NODE) && /(?:^|[^_])_[a-z][0-9A-Za-z]*$/.test(source)) {
                     throw new Error('Wrapper without lifecycle is forbidden.');
                 }
             }

package/src/Dto/DepId.mjs

@@ -1,5 +1,10 @@
 // @ts-check
 
+/**
+ * @namespace TeqFw_Di_Dto_DepId
+ * @description Dependency identity DTO and factory.
+ */
+
 import TeqFw_Di_Enum_Composition from '../Enum/Composition.mjs';
 import TeqFw_Di_Enum_Life from '../Enum/Life.mjs';
 import TeqFw_Di_Enum_Platform from '../Enum/Platform.mjs';
@@ -54,7 +59,7 @@ export class Factory {
      * Creates normalized frozen dependency identity DTO.
      *
      * @param {unknown} [input]
-     * @returns {TeqFw_Di_DepId$DTO}
+     * @returns {TeqFw_Di_DepId__DTO}
      */
     create(input) {
         /** @type {Record<string, unknown>} */

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

@@ -1,5 +1,10 @@
 // @ts-check
 
+/**
+ * @namespace TeqFw_Di_Dto_Resolver_Config_Namespace
+ * @description Resolver namespace rule DTO and factory.
+ */
+
 /**
  * DTO for resolver namespace rule records and its factory.
  */
@@ -25,14 +30,14 @@ export class Factory {
     /**
      * Creates normalized frozen resolver namespace DTO.
      *
-     * @param {Partial<TeqFw_Di_Dto_Resolver_Config_Namespace$DTO>|Record<string, unknown>} [input] Source values.
-     * @returns {TeqFw_Di_Dto_Resolver_Config_Namespace$DTO}
+     * @param {Partial<TeqFw_Di_Dto_Resolver_Config_Namespace__DTO>|Record<string, unknown>} [input] Source values.
+     * @returns {TeqFw_Di_Dto_Resolver_Config_Namespace__DTO}
      */
     create(input) {
-        /** @type {Partial<TeqFw_Di_Dto_Resolver_Config_Namespace$DTO>|Record<string, unknown>} */
+        /** @type {Partial<TeqFw_Di_Dto_Resolver_Config_Namespace__DTO>|Record<string, unknown>} */
         const source = (input && (typeof input === 'object')) ? input : {};
 
-        /** @type {TeqFw_Di_Dto_Resolver_Config_Namespace$DTO} */
+        /** @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;

package/src/Dto/Resolver/Config.mjs

@@ -1,5 +1,10 @@
 // @ts-check
 
+/**
+ * @namespace TeqFw_Di_Dto_Resolver_Config
+ * @description Resolver configuration DTO and factory.
+ */
+
 import {Factory as TeqFw_Di_Dto_Resolver_Config_Namespace_Factory} from './Config/Namespace.mjs';
 
 /**
@@ -10,7 +15,7 @@ import {Factory as TeqFw_Di_Dto_Resolver_Config_Namespace_Factory} from './Confi
  * Runtime DTO for resolver configuration.
  */
 export default class DTO {
-    /** @type {TeqFw_Di_Dto_Resolver_Config_Namespace$DTO[]} Namespace resolution rules. */
+    /** @type {TeqFw_Di_Dto_Resolver_Config_Namespace__DTO[]} Namespace resolution rules. */
     namespaces;
 
     /** @type {string|undefined} Optional node_modules root prefix for npm modules. */
@@ -31,14 +36,14 @@ export class Factory {
         /**
          * Creates normalized frozen resolver configuration DTO.
          *
-         * @param {Partial<TeqFw_Di_Dto_Resolver_Config$DTO>|Record<string, unknown>} [input] Source values.
-         * @returns {TeqFw_Di_Dto_Resolver_Config$DTO}
+         * @param {Partial<TeqFw_Di_Dto_Resolver_Config__DTO>|Record<string, unknown>} [input] Source values.
+         * @returns {TeqFw_Di_Dto_Resolver_Config__DTO}
          */
         this.create = function (input) {
-            /** @type {Partial<TeqFw_Di_Dto_Resolver_Config$DTO>|Record<string, unknown>} */
+            /** @type {Partial<TeqFw_Di_Dto_Resolver_Config__DTO>|Record<string, unknown>} */
             const source = (input && (typeof input === 'object')) ? input : {};
 
-            /** @type {TeqFw_Di_Dto_Resolver_Config$DTO} */
+            /** @type {TeqFw_Di_Dto_Resolver_Config__DTO} */
             const dto = new DTO();
             /** @type {unknown[]} */
             const items = Array.isArray(source.namespaces) ? source.namespaces : [];

package/src/Enum/Composition.mjs

@@ -1,5 +1,10 @@
 // @ts-check
 
+/**
+ * @namespace TeqFw_Di_Enum_Composition
+ * @description Composition mode enum constants.
+ */
+
 /**
  * Composition mode enum used in dependency identity DTO.
  */

package/src/Enum/Life.mjs

@@ -1,5 +1,10 @@
 // @ts-check
 
+/**
+ * @namespace TeqFw_Di_Enum_Life
+ * @description Lifecycle mode enum constants.
+ */
+
 /**
  * Lifecycle mode enum used in dependency identity DTO.
  */

package/src/Enum/Platform.mjs

@@ -1,5 +1,10 @@
 // @ts-check
 
+/**
+ * @namespace TeqFw_Di_Enum_Platform
+ * @description Platform selector enum constants.
+ */
+
 /**
  * Platform enum used to resolve module loading strategy.
  */

package/src/Internal/Logger.mjs

@@ -1,5 +1,10 @@
 // @ts-check
 
+/**
+ * @namespace TeqFw_Di_Internal_Logger
+ * @description Internal console logger for diagnostics.
+ */
+
 /**
  * Internal synchronous console logger.
  *

package/types.d.ts

@@ -8,17 +8,17 @@ declare global {
   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").default;
+  type TeqFw_Di_DepId__DTO = import("./src/Dto/DepId.mjs").default;
   type TeqFw_Di_DepId$Factory = InstanceType<typeof import("./src/Dto/DepId.mjs").Factory>;
   type TeqFw_Di_Dto_DepId = import("./src/Dto/DepId.mjs").default;
   type TeqFw_Di_Dto_DepId$DTO = import("./src/Dto/DepId.mjs").default;
-  type TeqFw_Di_Dto_DepId$Factory = InstanceType<typeof import("./src/Dto/DepId.mjs").Factory>;
+  type TeqFw_Di_Dto_DepId__Factory = InstanceType<typeof import("./src/Dto/DepId.mjs").Factory>;
   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").default;
-  type TeqFw_Di_Dto_Resolver_Config$Factory = InstanceType<typeof import("./src/Dto/Resolver/Config.mjs").Factory>;
+  type TeqFw_Di_Dto_Resolver_Config__DTO = import("./src/Dto/Resolver/Config.mjs").default;
+  type TeqFw_Di_Dto_Resolver_Config__Factory = InstanceType<typeof import("./src/Dto/Resolver/Config.mjs").Factory>;
   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").default;
-  type TeqFw_Di_Dto_Resolver_Config_Namespace$Factory = InstanceType<typeof import("./src/Dto/Resolver/Config/Namespace.mjs").Factory>;
+  type TeqFw_Di_Dto_Resolver_Config_Namespace__DTO = import("./src/Dto/Resolver/Config/Namespace.mjs").default;
+  type TeqFw_Di_Dto_Resolver_Config_Namespace__Factory = InstanceType<typeof import("./src/Dto/Resolver/Config/Namespace.mjs").Factory>;
   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;