@teqfw/di 2.6.2 → 2.8.0

package/src/Parser.mjs

@@ -2,7 +2,7 @@
 
 /**
  * @namespace TeqFw_Di_Parser
- * @description CDC parser that builds dependency identity DTOs.
+ * @description Dependency Specifier parser that builds dependency identity DTOs.
  */
 
 import TeqFw_Di_Enum_Composition from './Enum/Composition.mjs';
@@ -11,7 +11,7 @@ import TeqFw_Di_Enum_Platform from './Enum/Platform.mjs';
 import {Factory as TeqFw_Di_Dto_DepId_Factory} from './Dto/DepId.mjs';
 
 /**
- * Parser for CDC identifiers into frozen dependency identity DTO.
+ * Parser for Dependency Specifiers into frozen dependency identity DTOs.
 */
 export default class TeqFw_Di_Parser {
     /**
@@ -26,7 +26,7 @@ export default class TeqFw_Di_Parser {
         /**
          * Detects platform prefix and strips it from the source string.
          *
-         * @param {string} source CDC source without validation.
+         * @param {string} source Dependency Specifier source without validation.
          * @returns {{platform: typeof TeqFw_Di_Enum_Platform[keyof typeof TeqFw_Di_Enum_Platform], source: string}}
          */
         const detectPlatform = function (source) {
@@ -49,7 +49,7 @@ export default class TeqFw_Di_Parser {
         /**
          * Parses lifecycle and wrapper suffix from the source string.
          *
-         * @param {string} source CDC source without platform prefix.
+         * @param {string} source Dependency Specifier source without platform prefix.
          * @param {typeof TeqFw_Di_Enum_Platform[keyof typeof TeqFw_Di_Enum_Platform]} platform
          * @returns {{core: string, life: typeof TeqFw_Di_Enum_Life[keyof typeof TeqFw_Di_Enum_Life] | null, lifecycleDeclared: boolean, wrappers: string[]}}
          */
@@ -89,7 +89,7 @@ export default class TeqFw_Di_Parser {
         /**
          * Splits module and export names from canonical core string.
          *
-         * @param {string} core CDC core without lifecycle suffix.
+         * @param {string} core Dependency Specifier core without lifecycle suffix.
          * @returns {{moduleName: string, exportName: string|null}}
          */
         const parseModuleExport = function (core) {
@@ -139,20 +139,20 @@ export default class TeqFw_Di_Parser {
         };
 
         /**
-         * Parses one CDC identifier and returns normalized frozen dependency DTO.
+         * Parses one Dependency Specifier and returns a normalized frozen dependency DTO.
          *
-         * @param {string} cdc CDC identifier string.
+         * @param {string} specifier Dependency Specifier string.
          * @returns {TeqFw_Di_DepId__DTO}
          */
-        this.parse = function (cdc) {
-            if (logger) logger.log(`Parser.parse: input='${cdc}'.`);
-            if (typeof cdc !== 'string') throw new Error('CDC must be a string.');
-            if (cdc.length === 0) throw new Error('CDC must be non-empty.');
-            if (!/^[\x00-\x7F]+$/.test(cdc)) throw new Error('CDC must be ASCII.');
+        this.parse = function (specifier) {
+            if (logger) logger.log(`Parser.parse: input='${specifier}'.`);
+            if (typeof specifier !== 'string') throw new Error('Dependency Specifier must be a string.');
+            if (specifier.length === 0) throw new Error('Dependency Specifier must be non-empty.');
+            if (!/^[\x00-\x7F]+$/.test(specifier)) throw new Error('Dependency Specifier must be ASCII.');
 
             /** @type {string} */
-            const origin = cdc;
-            const detected = detectPlatform(cdc);
+            const origin = specifier;
+            const detected = detectPlatform(specifier);
             const platform = detected.platform;
             const source = detected.source;
             if (source.length === 0) throw new Error('moduleName must be non-empty.');
@@ -163,10 +163,10 @@ export default class TeqFw_Di_Parser {
             /** @type {typeof TeqFw_Di_Enum_Composition[keyof typeof TeqFw_Di_Enum_Composition]} */
             let composition = TeqFw_Di_Enum_Composition.AS_IS;
             let exportName = split.exportName;
-            if (exportName !== null) {
-                composition = TeqFw_Di_Enum_Composition.FACTORY;
-            } else if (lifecycle.lifecycleDeclared) {
-                exportName = 'default';
+            if (lifecycle.lifecycleDeclared) {
+                if (exportName === null) {
+                    exportName = 'default';
+                }
                 composition = TeqFw_Di_Enum_Composition.FACTORY;
             }
 

package/types.d.ts

@@ -1,10 +1,15 @@
 declare global {
+  type TeqFw_Di_Node_Registry_Namespace = import("./src/Node/Registry/Namespace.mjs").default;
   type TeqFw_Di_Config_NamespaceRegistry = import("./src/Config/NamespaceRegistry.mjs").default;
+  type TeqFw_Di_Node_Registry_Namespace_Entry = Readonly<{prefix: string, dirAbs: string, ext: string}>;
+  type TeqFw_Di_Node_Registry_Package = import("./src/Node/Registry/Package.mjs").default;
+  type TeqFw_Di_Node_Registry_Package_Record = Readonly<{name: string, rootAbs: string, rootReal: string, packageJson: Readonly<Record<string, unknown>>, dependencies: ReadonlyArray<string>}>;
   type TeqFw_Di_Container = import("./src/Container.mjs").default;
-  type TeqFw_Di_Container_Instantiate_Instantiator = import("./src/Container/Instantiate.mjs").default;
-  type TeqFw_Di_Container_Lifecycle_Registry = import("./src/Container/Lifecycle.mjs").default;
-  type TeqFw_Di_Container_Resolve_GraphResolver = import("./src/Container/GraphResolver.mjs").default;
-  type TeqFw_Di_Container_Wrapper_Executor = import("./src/Container/Executor.mjs").default;
+  type TeqFw_Di_Container_Instantiate = import("./src/Container/Instantiate.mjs").default;
+  type TeqFw_Di_Container_Lifecycle = import("./src/Container/Lifecycle.mjs").default;
+  type TeqFw_Di_Container_Postprocess_Context = Readonly<{depId: TeqFw_Di_DepId__DTO}>;
+  type TeqFw_Di_Container_GraphResolver = import("./src/Container/GraphResolver.mjs").default;
+  type TeqFw_Di_Container_Executor = import("./src/Container/Executor.mjs").default;
   type TeqFw_Di_Parser = import("./src/Parser.mjs").default;
   type TeqFw_Di_DepId = import("./src/Dto/DepId.mjs").default;
   type TeqFw_Di_DepId__DTO = import("./src/Dto/DepId.mjs").default;

package/ai/concepts.md

@@ -1,25 +0,0 @@
-# concepts.md
-
-Version: 20260606
-
-## Late Binding
-
-Dependencies are resolved at runtime rather than through direct static imports between application modules. This keeps modules independent of concrete implementations and moves dependency binding into the container.
-
-## Runtime Linker
-
-The container acts as a runtime linker for ES modules. It interprets CDC identifiers, resolves modules, selects exports, and produces linked values for callers.
-
-## Dependency Contracts
-
-Dependencies are declared through CDC strings and module-level `__deps__` descriptors. Together they form the contract between module code and runtime composition.
-
-The canonical `__deps__` form is hierarchical and keyed by export name.
-
-## Namespace Mapping
-
-Logical module identifiers are translated into module-specifier bases through namespace roots. This keeps dependency addressing independent from concrete filesystem paths or URL locations.
-
-## Immutable Linked Values
-
-Values returned by the container are frozen after linking. Consumers should treat them as stable resolved values rather than mutable construction targets.

package/ai/usage.md

@@ -1,194 +0,0 @@
-# usage.md
-
-Version: 20260606
-
-## Purpose
-
-This document shows canonical usage patterns for the container. Examples are intentionally short and prioritize supported, recommended forms over convenience shorthand.
-
-## Canonical Module Descriptor
-
-The canonical form of `__deps__` is hierarchical and keyed by export name.
-
-```js
-// @ts-check
-
-export const __deps__ = {
-  default: {
-    cast: "App_Helper_Cast$",
-  },
-};
-
-export default class App_Root {
-  /**
-   * @param {{cast: (value: unknown) => string}} deps
-   */
-  constructor({ cast }) {
-    return {
-      configure(params = {}) {
-        return {
-          name: cast(params.name ?? "app"),
-        };
-      },
-    };
-  }
-}
-```
-
-Dependency module:
-
-```js
-// @ts-check
-
-export default function App_Helper_Cast() {
-  return function cast(value) {
-    return String(value);
-  };
-}
-```
-
-Rules:
-
-- the hierarchical export-scoped form is canonical;
-- each export entry maps constructor dependency names to CDC identifiers;
-- if `__deps__` is omitted, the module has no declared dependencies;
-- dependencies are resolved recursively before instantiation.
-
-## Canonical Container Setup
-
-The container is configured in the composition root before the first resolution.
-
-```js
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import Container from "@teqfw/di";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const container = new Container();
-container.addNamespaceRoot("App_", path.resolve(__dirname, "./src/App"), ".mjs");
-```
-
-Namespace roots may also use URL-backed module-specifier bases:
-
-```js
-container.addNamespaceRoot("App_", "https://cdn.example.com/app", ".mjs");
-```
-
-## Resolve Root Dependency
-
-Applications typically resolve one root dependency and let the container build the full object graph.
-
-```js
-const root = await container.get("App_Root$");
-console.log(root.configure({name: 123}).name);
-console.log(Object.isFrozen(root));
-```
-
-## Named Export
-
-Named exports use the `__ExportName` segment in the CDC and the same hierarchical `__deps__` structure.
-
-```js
-export const __deps__ = {
-  default: {
-    cast: "App_Helper_Cast$",
-  },
-  Factory: {
-    cast: "App_Helper_Cast$",
-  },
-};
-
-export default class RuntimeWrapper {
-  constructor() {
-    return {mode: "runtime"};
-  }
-}
-
-export class Factory {
-  constructor({ cast }) {
-    this.configure = function (params = {}) {
-      return {
-        mode: "factory",
-        name: cast(params.name ?? "app"),
-      };
-    };
-  }
-}
-```
-
-Resolution examples:
-
-```js
-const runtime = await container.get("App_Module$");
-const factory = await container.get("App_Module__Factory$");
-```
-
-## Singleton And Transient
-
-Common lifecycle-based compositions:
-
-```txt
-App_Service$
-App_Task$$
-App_Task$$$
-```
-
-- `$` creates and reuses a singleton instance;
-- `$$` creates a new instance for each request;
-- `$$$` is a transient alias in the current implementation.
-
-## Wrappers
-
-Wrapper exports are selected by CDC suffixes and are applied after postprocess hooks.
-
-```txt
-App_Service$$_wrapLog_wrapTrace
-```
-
-This pattern is useful when runtime behavior should be decorated without changing the service module contract.
-
-## Platform Modules
-
-CDC may refer to platform modules directly.
-
-```txt
-node:fs
-npm:@humanfs/core
-node:worker_threads
-```
-
-These forms resolve the selected platform module export as-is unless a lifecycle marker is explicitly added.
-
-## Non-Canonical Shorthand
-
-A flat `__deps__` object is a supported shorthand for default-export-only modules, but it is not the canonical model.
-
-```js
-export const __deps__ = {
-  cast: "App_Helper_Cast$",
-};
-
-export default class App_Short {
-  constructor({ cast }) {
-    this.cast = cast;
-  }
-}
-```
-
-Prefer the hierarchical form for new integrations and for any module that exposes named exports.
-
-## Empty Descriptor
-
-Modules with no declared dependencies omit `__deps__` entirely.
-
-```js
-export default class App_Empty {
-  constructor() {
-    this.ready = function () {
-      return true;
-    };
-  }
-}
-```