@teqfw/di 1.3.0 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teqfw/di",
-  "version": "1.3.0",
+  "version": "2.0.1",
   "description": "Dependency Injection container for ES6 modules that works in both browser and Node.js apps.",
   "keywords": [
     "dependency injection",
@@ -23,6 +23,9 @@
   "files": [
     "dist/",
     "src/",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
     "teqfw.json",
     "types.d.ts"
   ],
@@ -31,12 +34,15 @@
   "types": "types.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/esm.js",
-      "require": "./dist/umd.js"
+      "browser": {
+        "import": "./dist/esm.js",
+        "require": "./dist/umd.js"
+      },
+      "import": "./src/Container.mjs",
+      "default": "./src/Container.mjs"
     },
-    "./pre/replace": {
-      "import": "./src/Pre/Replace.js"
-    }
+    "./src/Container.mjs": "./src/Container.mjs",
+    "./src/Config/NamespaceRegistry.mjs": "./src/Config/NamespaceRegistry.mjs"
   },
   "type": "module",
   "repository": {
@@ -45,16 +51,16 @@
   },
   "scripts": {
     "rollup": "rollup -c",
-    "eslint": "npx eslint './src/**/*.js'",
-    "test:unit": "node --test"
+    "eslint": "npx eslint './src/**/*.mjs'",
+    "test:unit": "node --test test/unit",
+    "test:integration": "node --test test/integration"
   },
   "devDependencies": {
-    "@eslint/js": "^9.33.0",
-    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@eslint/js": "^10.0.1",
+    "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-terser": "^0.4.4",
-    "eslint": "^9.33.0",
-    "rollup": "^4.47.1",
-    "typescript": "^5.9.3"
+    "eslint": "^10.0.2",
+    "rollup": "^4.59.0"
   },
   "engines": {
     "node": ">=20"

package/src/AGENTS.md

@@ -0,0 +1,177 @@
+# AGENTS.md — `src/`
+
+Path: `./src/AGENTS.md`
+
+## Scope
+
+This file governs all implementation source code located under `./src/`.
+
+All changes in this directory MUST comply with normative documents located in `ctx/docs/code/`.
+
+This file defines only implementation-level obligations. It does not redefine architecture, product, or composition semantics.
+
+## Normative References
+
+The following documents are mandatory:
+
+- `ctx/docs/code/structure.md`
+- `ctx/docs/code/container.md`
+- `ctx/docs/code/resolver.md`
+- `ctx/docs/code/parser.md`
+- `ctx/docs/code/depid.md`
+- `ctx/docs/code/testing.md`
+- `ctx/docs/code/jsdoc-spec.md`
+- `ctx/docs/code/conventions/es6-modules.md`
+- `ctx/docs/code/conventions/teqfw/dto.md`
+- `ctx/docs/code/conventions/teqfw/enum.md`
+
+Agent MUST read and follow them before generating or modifying code.
+
+Deviation from these documents constitutes non-compliance.
+
+## Structural Compliance
+
+Directory layout, namespace mapping, file naming, dependency direction, and static import rules MUST strictly follow:
+
+`ctx/docs/code/structure.md`
+
+In particular:
+
+- `Enum/` and `Dto/` directories are mandatory.
+- File names MUST use PascalCase.
+- Underscores in file names are prohibited.
+- Namespace hierarchy MUST be reflected in directory hierarchy.
+- Static dependency direction MUST follow the allowed layer graph.
+- `Container.mjs` is the only public entry point.
+
+Structural violations are execution errors.
+
+## JSDoc Compliance
+
+JSDoc is mandatory and governed by:
+
+`ctx/docs/code/jsdoc-spec.md`
+
+All implementation files MUST:
+
+- include `// @ts-check`;
+- contain a module-level JSDoc block;
+- annotate all exported classes, functions, and public methods;
+- annotate private methods and private fields;
+- provide explicit `@typedef` for constructor dependency descriptors;
+- use existing public type aliases from `types.d.ts` when available;
+- avoid introducing duplicate typedefs for already declared public DTO types.
+
+Local variables with non-trivial types MUST use `@type` annotations.
+
+TypeScript source files are prohibited.
+
+Absence of required JSDoc constitutes non-compliance.
+
+## DTO and Enum Rules
+
+All DTO and Enum implementations MUST strictly follow:
+
+- `ctx/docs/code/conventions/teqfw/dto.md`
+- `ctx/docs/code/conventions/teqfw/enum.md`
+
+In particular:
+
+- DTO structural classes MUST NOT participate in DI.
+- DTO factories MUST expose exactly one public `create(...)` method.
+- Enum modules MUST export a single flat literal object as `default`.
+- No behavioral logic may be introduced into DTO or Enum modules.
+- Semantic constants MUST be referenced via Enum codifiers.
+- String literals MUST NOT be used where an Enum codifier exists.
+
+## Fail-Fast Semantics (No Defensive Programming)
+
+Implementation under `src/` follows strict fail-fast architecture.
+
+Agents MUST assume that:
+
+- DepId DTO instances are structurally valid.
+- Resolver configuration DTO is valid.
+- Enum codifiers are valid.
+- Constructor dependency descriptors are correct.
+- Public API callers provide semantically correct inputs.
+
+Unless explicitly required by a code-level contract document, implementation MUST NOT:
+
+- perform defensive runtime validation of input types,
+- duplicate parser or DTO validation logic,
+- introduce early-guard checks for invariants guaranteed by higher layers,
+- validate constructor dependency descriptor shapes,
+- add “safe” fallback branches,
+- attempt graceful degradation.
+
+This rule applies equally to internal and public methods, including `Container.get`.
+
+If an invariant is violated, the system MUST fail at the point of use.
+Explicit pre-validation for the sole purpose of producing earlier or clearer error messages is prohibited.
+
+Redundant validation logic constitutes architectural violation.
+
+## Testing Alignment
+
+Unit and integration tests MUST follow:
+
+`ctx/docs/code/testing.md`
+
+For every testable source module, exactly one corresponding unit test MUST exist under `test/unit/`, mirroring directory structure.
+
+Tests MUST use:
+
+- `node:test`
+- `node:assert/strict`
+
+Isolation and determinism requirements are mandatory.
+
+## Type Declaration Discipline
+
+The file `types.d.ts` defines exported structural type aliases corresponding to implementation modules.
+
+When adding or renaming an exported implementation module under `src/`, agent MUST:
+
+- ensure a corresponding type alias exists in `types.d.ts`;
+- ensure alias mapping follows namespace-to-file mapping rules.
+
+Only types intended for global availability MAY be placed inside `declare global {}`.
+
+All other types MUST be exported normally and imported explicitly.
+
+Implicit global types are prohibited.
+
+## Responsibility Boundary
+
+Agents operating under `src/` are responsible only for:
+
+- implementation-level correctness,
+- structural compliance,
+- deterministic behavior,
+- strict fail-fast semantics,
+- JSDoc typing discipline,
+- alignment with code-level contracts.
+
+Agents MUST NOT:
+
+- redefine architecture-level invariants,
+- weaken fail-fast guarantees,
+- introduce defensive runtime validation,
+- modify dependency direction rules,
+- introduce new extension points not defined at code level.
+
+## Summary
+
+`src/` is governed by strict structural, typing, determinism, and fail-fast invariants.
+
+Implementation must remain:
+
+- structurally deterministic,
+- layer-consistent,
+- JSDoc-typed,
+- DTO/Enum-disciplined,
+- free of defensive redundancy,
+- compliant with namespace-to-file mapping rules.
+
+Any deviation constitutes non-compliant implementation.

package/src/Config/NamespaceRegistry.mjs

@@ -0,0 +1,210 @@
+// @ts-check
+
+/**
+ * @typedef {object} TeqFw_Di_Config_NamespaceRegistry_Dependencies
+ * @property {{readFile(path: string, encoding: string): Promise<string>, readdir(path: string): Promise<string[]>, realpath(path: string): Promise<string>, stat(path: string): Promise<{isDirectory(): boolean}>}} fs
+ * @property {{join(...paths: string[]): string, dirname(path: string): string, relative(from: string, to: string): string, resolve(...paths: string[]): string, isAbsolute(path: string): boolean}} path
+ * @property {string} appRoot
+ */
+
+/**
+ * @typedef {object} TeqFw_Di_Config_NamespaceRegistry_Entry
+ * @property {string} prefix
+ * @property {string} dirAbs
+ * @property {string} ext
+ */
+
+/**
+ * Builds deterministic immutable namespace registry from root package and installed dependencies.
+ */
+export default class TeqFw_Di_Config_NamespaceRegistry {
+    /**
+     * @param {TeqFw_Di_Config_NamespaceRegistry_Dependencies} dependencies
+     */
+    constructor({fs, path, appRoot}) {
+        const appRootAbs = path.resolve(appRoot);
+
+        /**
+         * @param {string} fileAbs
+         * @returns {Promise<Record<string, unknown>>}
+         */
+        const readJson = async function (fileAbs) {
+            const content = await fs.readFile(fileAbs, 'utf8');
+            return /** @type {Record<string, unknown>} */ (JSON.parse(content));
+        };
+
+        /**
+         * @param {string} absPath
+         * @returns {Promise<boolean>}
+         */
+        const isDirectory = async function (absPath) {
+            try {
+                const stat = await fs.stat(absPath);
+                return stat.isDirectory();
+            } catch {
+                return false;
+            }
+        };
+
+        /**
+         * @param {string} rootAbs
+         * @param {string} candidateAbs
+         * @returns {boolean}
+         */
+        const isInside = function (rootAbs, candidateAbs) {
+            const rel = path.relative(rootAbs, candidateAbs);
+            return (rel === '') || (!rel.startsWith('..') && !path.isAbsolute(rel));
+        };
+
+        /**
+         * @param {string} packageRootAbs
+         * @param {string} dirAbs
+         * @returns {Promise<void>}
+         */
+        const assertInsidePackageRoot = async function (packageRootAbs, dirAbs) {
+            const packageRootReal = await fs.realpath(packageRootAbs);
+            const dirReal = await fs.realpath(dirAbs);
+            if (!isInside(packageRootReal, dirReal)) {
+                throw new Error(`Namespace path resolves outside package root: '${dirAbs}'.`);
+            }
+        };
+
+        /**
+         * @param {unknown} ext
+         * @returns {string}
+         */
+        const normalizeExt = function (ext) {
+            if (ext === undefined) return '.mjs';
+            if ((typeof ext !== 'string') || (ext.length === 0)) {
+                throw new Error('Namespace extension must be a non-empty string.');
+            }
+            const normalized = ext.startsWith('.') ? ext : `.${ext}`;
+            if ((normalized !== '.mjs') && (normalized !== '.js')) {
+                throw new Error(`Namespace extension is not ESM-compatible: '${normalized}'.`);
+            }
+            return normalized;
+        };
+
+        /**
+         * @param {unknown} raw
+         * @param {string} packageRootAbs
+         * @returns {Promise<TeqFw_Di_Config_NamespaceRegistry_Entry>}
+         */
+        const normalizeEntry = async function (raw, packageRootAbs) {
+            if ((raw === null) || (typeof raw !== 'object')) {
+                throw new Error('Namespace entry must be an object.');
+            }
+            const item = /** @type {Record<string, unknown>} */ (raw);
+
+            const prefix = item.prefix;
+            if ((typeof prefix !== 'string') || (prefix.length === 0) || !prefix.endsWith('_')) {
+                throw new Error(`Namespace prefix is invalid: '${String(prefix)}'.`);
+            }
+
+            const rawPath = item.path;
+            if ((typeof rawPath !== 'string') || (rawPath.length === 0) || path.isAbsolute(rawPath)) {
+                throw new Error(`Namespace path must be a non-empty relative path: '${String(rawPath)}'.`);
+            }
+            const dirAbs = path.resolve(packageRootAbs, rawPath);
+            if (!(await isDirectory(dirAbs))) {
+                throw new Error(`Namespace path does not point to existing directory: '${dirAbs}'.`);
+            }
+            await assertInsidePackageRoot(packageRootAbs, dirAbs);
+
+            const ext = normalizeExt(item.ext);
+
+            return {prefix, dirAbs, ext};
+        };
+
+        /**
+         * @param {string} packageRootAbs
+         * @returns {Promise<{namespaces: unknown[], dependencies: string[]}>}
+         */
+        const readPackageMetadata = async function (packageRootAbs) {
+            const packageJsonAbs = path.join(packageRootAbs, 'package.json');
+            const packageJson = await readJson(packageJsonAbs);
+            const teqfw = (packageJson.teqfw && typeof packageJson.teqfw === 'object')
+                ? /** @type {Record<string, unknown>} */ (packageJson.teqfw)
+                : {};
+            const namespaces = Array.isArray(teqfw.namespaces) ? teqfw.namespaces : [];
+            const dependencies = (packageJson.dependencies && typeof packageJson.dependencies === 'object')
+                ? Object.keys(/** @type {Record<string, unknown>} */ (packageJson.dependencies)).sort()
+                : [];
+            return {namespaces, dependencies};
+        };
+
+        /**
+         * @param {string} packageName
+         * @param {string} fromPackageRootAbs
+         * @returns {Promise<string>}
+         */
+        const resolveDependencyPackageRoot = async function (packageName, fromPackageRootAbs) {
+            let cursor = fromPackageRootAbs;
+            while (isInside(appRootAbs, cursor)) {
+                const candidate = path.join(cursor, 'node_modules', packageName);
+                if (await isDirectory(candidate)) {
+                    const packageJsonAbs = path.join(candidate, 'package.json');
+                    const hasPackageJson = await (async () => {
+                        try {
+                            await fs.stat(packageJsonAbs);
+                            return true;
+                        } catch {
+                            return false;
+                        }
+                    })();
+                    if (hasPackageJson) {
+                        return path.resolve(candidate);
+                    }
+                }
+                if (cursor === appRootAbs) break;
+                const parent = path.dirname(cursor);
+                if (parent === cursor) break;
+                cursor = parent;
+            }
+            throw new Error(`Installed dependency is not found: '${packageName}' from '${fromPackageRootAbs}'.`);
+        };
+
+        /**
+         * @returns {Promise<Readonly<TeqFw_Di_Config_NamespaceRegistry_Entry[]>>}
+         */
+        this.build = async function () {
+            /** @type {{name: string, rootAbs: string}[]} */
+            const queue = [{name: '<root>', rootAbs: appRootAbs}];
+            /** @type {Set<string>} */
+            const visitedRoots = new Set();
+            /** @type {Set<string>} */
+            const uniquePrefixes = new Set();
+            /** @type {TeqFw_Di_Config_NamespaceRegistry_Entry[]} */
+            const entries = [];
+
+            while (queue.length > 0) {
+                const current = queue.shift();
+                const packageRootAbs = current.rootAbs;
+                const packageRootReal = await fs.realpath(packageRootAbs);
+                if (visitedRoots.has(packageRootReal)) continue;
+                visitedRoots.add(packageRootReal);
+
+                const meta = await readPackageMetadata(packageRootAbs);
+                for (const raw of meta.namespaces) {
+                    const normalized = await normalizeEntry(raw, packageRootAbs);
+                    if (uniquePrefixes.has(normalized.prefix)) {
+                        throw new Error(`Duplicate namespace prefix is not allowed: '${normalized.prefix}'.`);
+                    }
+                    uniquePrefixes.add(normalized.prefix);
+                    entries.push(normalized);
+                }
+
+                for (const depName of meta.dependencies) {
+                    const depRootAbs = await resolveDependencyPackageRoot(depName, packageRootAbs);
+                    queue.push({name: depName, rootAbs: depRootAbs});
+                }
+            }
+
+            entries.sort((a, b) => b.prefix.length - a.prefix.length);
+            for (const entry of entries) {
+                Object.freeze(entry);
+            }
+            return Object.freeze(entries);
+        };
+    }
+}

package/src/Container/Instantiate/ExportSelector.mjs

@@ -0,0 +1,39 @@
+// @ts-check
+
+/**
+ * Instantiate-stage export selector.
+ *
+ * Selects exactly one export from an already loaded ES module namespace object
+ * using only `depId.exportName`.
+ */
+export default class TeqFw_Di_Container_Instantiate_ExportSelector {
+    /**
+     * Creates export selector instance.
+     */
+    constructor() {
+        /**
+         * Selects a raw export value from module namespace.
+         *
+         * @param {object} namespace Loaded ES module namespace object.
+         * @param {TeqFw_Di_DepId$DTO} depId Dependency identity DTO.
+         * @returns {unknown} Raw selected export value.
+         */
+        this.select = function (namespace, depId) {
+            if (!namespace || (typeof namespace !== 'object')) {
+                throw new Error('Namespace must be an object.');
+            }
+
+            /** @type {string|null} */
+            const exportName = depId.exportName;
+            if (exportName === null) {
+                throw new Error('Export name must not be null for export selection.');
+            }
+
+            if (!(exportName in namespace)) {
+                throw new Error(`Export '${exportName}' is not found in module namespace.`);
+            }
+
+            return namespace[exportName];
+        };
+    }
+}

package/src/Container/Instantiate/Instantiator.mjs

@@ -0,0 +1,143 @@
+// @ts-check
+
+import TeqFw_Di_Enum_Composition from '../../Enum/Composition.mjs';
+
+/**
+ * Instantiate-stage immutable core executor.
+ *
+ * Performs export selection and composition execution only,
+ * using already resolved dependency values.
+ */
+
+/**
+ * @typedef {(deps: object) => unknown} CallableFactory
+ */
+
+/**
+ * @typedef {new (deps: object) => unknown} ConstructableFactory
+ */
+
+/**
+ * @typedef {CallableFactory | ConstructableFactory} Factory
+ */
+export default class TeqFw_Di_Container_Instantiate_Instantiator {
+
+    /**
+     * Creates instantiator instance.
+     */
+    constructor() {
+
+        /**
+         * Selects the value used by composition.
+         *
+         * @param {TeqFw_Di_DepId$DTO} depId
+         * @param {object} moduleNamespace
+         * @returns {Factory}
+         */
+        const selectExport = function (depId, moduleNamespace) {
+            if (depId.exportName === null) {
+                return moduleNamespace;
+            }
+
+            if (!(depId.exportName in moduleNamespace)) {
+                throw new Error(
+                    `Export '${depId.exportName}' is not found in module namespace.`
+                );
+            }
+
+            return moduleNamespace[depId.exportName];
+        };
+
+        /**
+         * Determines whether a callable supports construction with `new`.
+         *
+         * @param {Function} value
+         * @returns {value is ConstructableFactory}
+         */
+        const isConstructible = function (value) {
+            try {
+                Reflect.construct(String, [], value);
+                return true;
+            } catch {
+                return false;
+            }
+        };
+
+        /**
+         * Detects Promise-like asynchronous return values.
+         *
+         * @param {unknown} value
+         * @returns {boolean}
+         */
+        const isThenable = function (value) {
+            if ((value === null) || (value === undefined)) {
+                return false;
+            }
+
+            const type = typeof value;
+
+            if ((type !== 'object') && (type !== 'function')) {
+                return false;
+            }
+
+            /** @type {{ then?: unknown }} */
+            const maybeThenable = value;
+
+            return (typeof maybeThenable.then === 'function');
+        };
+
+        /**
+         * Produces a value from a resolved module namespace and dependency map.
+         *
+         * @param {TeqFw_Di_DepId$DTO} depId
+         * @param {object} moduleNamespace
+         * @param {Record<string, unknown>} resolvedDeps
+         * @returns {unknown}
+         */
+        this.instantiate = function (depId, moduleNamespace, resolvedDeps) {
+            /** @type {Factory} */
+            const selected = selectExport(depId, moduleNamespace);
+
+            if (depId.composition === TeqFw_Di_Enum_Composition.AS_IS) {
+                return selected;
+            }
+
+            if (depId.composition === TeqFw_Di_Enum_Composition.FACTORY) {
+
+                if (typeof selected !== 'function') {
+                    throw new Error(
+                        'Factory composition requires a callable export.'
+                    );
+                }
+
+                /** @type {Factory} */
+                const factory = selected;
+
+                /** @type {unknown} */
+                let result;
+
+                if (isConstructible(factory)) {
+                    /** @type {ConstructableFactory} */
+                    const Ctor = factory;
+                    result = new Ctor(resolvedDeps);
+                } else {
+                    /** @type {CallableFactory} */
+                    const Fn = factory;
+                    result = Fn(resolvedDeps);
+                }
+
+                if (isThenable(result)) {
+                    throw new Error(
+                        'Factory composition must return synchronously (non-thenable).'
+                    );
+                }
+
+                return result;
+            }
+
+            throw new Error(
+                `Unsupported composition mode: ${String(depId.composition)}.`
+            );
+        };
+    }
+}