@teqfw/di 2.7.0 → 2.8.0

package/src/Config/NamespaceRegistry.mjs

@@ -2,218 +2,8 @@
 
 /**
  * @namespace TeqFw_Di_Config_NamespaceRegistry
- * @description Deterministic loader for package namespace rules.
+ * @description Deprecated compatibility re-export for the Node.js namespace registry.
+ * @deprecated Use @teqfw/di/node/registry/namespace in new integrations.
  */
 
-/**
- * @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} deps
-     */
-    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};
-        };
-
-        /**
-         * Checks whether package.json exists inside a dependency directory.
-         *
-         * @param {string} candidateAbs
-         * @returns {Promise<boolean>}
-         */
-        const hasPackageJson = async function (candidateAbs) {
-            try {
-                await fs.stat(path.join(candidateAbs, 'package.json'));
-                return true;
-            } catch {
-                return false;
-            }
-        };
-
-        /**
-         * @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) && (await hasPackageJson(candidate))) {
-                    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 = [{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({rootAbs: depRootAbs});
-                }
-            }
-
-            entries.sort((a, b) => b.prefix.length - a.prefix.length);
-            for (const entry of entries) {
-                Object.freeze(entry);
-            }
-            return Object.freeze(entries);
-        };
-    }
-}
+export {default} from "../Node/Registry/Namespace.mjs";

package/src/Container/GraphResolver.mjs

@@ -14,13 +14,14 @@
 
 /**
  * @typedef {object} TeqFw_Di_Container_GraphResolver_Dependencies
- * @property {TeqFw_Di_Parser} parser
+ * @property {(specifier: string) => TeqFw_Di_DepId__DTO} canonicalize
+ * @property {(depId: TeqFw_Di_DepId__DTO) => {found: boolean, value: unknown}} findMock
  * @property {TeqFw_Di_Resolver} resolver
  * @property {{log(message: string): void}|null} [logger]
  */
 
 /**
- * @typedef {{depId: TeqFw_Di_DepId__DTO, namespace: object}} TeqFw_Di_Container_GraphResolver_Node
+ * @typedef {{depId: TeqFw_Di_DepId__DTO, namespace: object|null, dependencies: Map<string, string>, mock: {found: boolean, value: unknown}}} TeqFw_Di_Container_GraphResolver_Node
  */
 
 import {buildDependencyKey} from '../Internal/DependencyKey.mjs';
@@ -31,7 +32,8 @@ export default class TeqFw_Di_Container_GraphResolver {
     /**
      * @param {TeqFw_Di_Container_GraphResolver_Dependencies} deps
      */
-    constructor({parser, resolver, logger = null}) {
+    constructor({canonicalize, parser, findMock = () => ({found: false, value: undefined}), resolver, logger = null}) {
+        canonicalize ??= parser.parse.bind(parser);
         /** @type {{log(message: string): void}|null} */
         const log = logger;
 
@@ -61,19 +63,28 @@ export default class TeqFw_Di_Container_GraphResolver {
             const key = makeNodeKey(depId);
             if (out.has(key)) return;
 
+            const mock = findMock(depId);
+            if (mock.found) {
+                out.set(key, {depId, namespace: null, dependencies: new Map(), mock});
+                return;
+            }
+
             stack.add(identity);
             chain.push(identity);
             try {
                 /** @type {object} */
                 const namespace = await resolver.resolve(depId);
                 if (log) log.log(`GraphResolver.walk: resolved '${key}'.`);
-                out.set(key, {depId, namespace});
+                /** @type {Map<string, string>} */
+                const dependencies = new Map();
+                out.set(key, {depId, namespace, dependencies, mock});
 
                 /** @type {Record<string, unknown>} */
                 const depsMap = readDepsDecl(namespace, depId);
-                for (const nextCdc of Object.values(depsMap)) {
+                for (const [name, nextSpecifier] of Object.entries(depsMap)) {
                     /** @type {TeqFw_Di_DepId__DTO} */
-                    const nextDepId = parser.parse(/** @type {string} */ (nextCdc));
+                    const nextDepId = canonicalize(/** @type {string} */ (nextSpecifier));
+                    dependencies.set(name, makeNodeKey(nextDepId));
                     if (log) log.log(`GraphResolver.walk: edge '${key}' -> '${nextDepId.platform}::${nextDepId.moduleName}'.`);
                     await walk(nextDepId, out, stack, chain);
                 }

package/src/Container/Pipeline.mjs

@@ -6,12 +6,10 @@
  */
 
 import {buildDependencyKey} from '../Internal/DependencyKey.mjs';
-import {readDepsDecl} from '../Internal/DepsDecl.mjs';
 import {makePromiseSafe} from '../Internal/PromiseSafe.mjs';
 
 /**
  * @typedef {object} TeqFw_Di_Container_Pipeline_Context
- * @property {TeqFw_Di_Parser} parser
  * @property {TeqFw_Di_Resolver|undefined} resolver
  * @property {TeqFw_Di_Container_GraphResolver|undefined} graphResolver
  * @property {TeqFw_Di_Container_Lifecycle|undefined} lifecycle
@@ -21,20 +19,19 @@ import {makePromiseSafe} from '../Internal/PromiseSafe.mjs';
  * @property {boolean} testMode
  * @property {Map<string, unknown>} mockRegistry
  * @property {(value: unknown) => unknown} freeze
- * @property {(depId: TeqFw_Di_DepId__DTO) => TeqFw_Di_DepId__DTO} applyPreprocess
- * @property {(value: unknown) => unknown} applyPostprocess
+ * @property {(specifier: string) => TeqFw_Di_DepId__DTO} canonicalize
+ * @property {(value: unknown, depId: TeqFw_Di_DepId__DTO) => unknown} applyPostprocess
  */
 
 /**
- * Executes full container get pipeline for a CDC.
+ * Executes the full container pipeline for a Dependency Specifier.
  *
  * @param {TeqFw_Di_Container_Pipeline_Context} ctx
- * @param {string} cdc
+ * @param {string} specifier
  * @returns {Promise<any>}
  */
-export async function executeContainerPipeline(ctx, cdc) {
+export async function executeContainerPipeline(ctx, specifier) {
     const {
-        parser,
         resolver,
         graphResolver,
         lifecycle,
@@ -44,7 +41,7 @@ export async function executeContainerPipeline(ctx, cdc) {
         testMode,
         mockRegistry,
         freeze,
-        applyPreprocess,
+        canonicalize,
         applyPostprocess,
     } = ctx;
 
@@ -58,14 +55,14 @@ export async function executeContainerPipeline(ctx, cdc) {
     /** @type {string} */
     let stage = 'start';
     try {
-        logger.log(`Container.get: cdc='${cdc}'.`);
+        logger.log(`Container.get: specifier='${specifier}'.`);
         stage = 'parse';
         logger.log('Container.pipeline: parse:entry.');
-        const parsed = parser.parse(cdc);
+        const root = canonicalize(specifier);
+        const parsed = root;
         logger.log(`Container.pipeline: parse:exit '${parsed.platform}::${parsed.moduleName}'.`);
         stage = 'preprocess';
         logger.log('Container.pipeline: preprocess:entry.');
-        const root = applyPreprocess(parsed);
         logger.log(`Container.pipeline: preprocess:exit '${root.platform}::${root.moduleName}'.`);
         if (testMode === true) {
             stage = 'mock';
@@ -95,6 +92,10 @@ export async function executeContainerPipeline(ctx, cdc) {
             if (built.has(key)) return built.get(key);
             if (!graph.has(key)) throw new Error(`Resolved graph node is missing for '${key}'.`);
             const node = graph.get(key);
+            if (node.mock?.found) {
+                stage = 'freeze';
+                return freeze(node.mock.value);
+            }
             stage = 'lifecycle';
             logger.log(`Container.pipeline: lifecycle:entry '${node.depId.platform}::${node.depId.moduleName}'.`);
             const value = lifecycle.apply(node.depId, function () {
@@ -102,17 +103,14 @@ export async function executeContainerPipeline(ctx, cdc) {
                 logger.log(`Container.pipeline: instantiate:entry '${node.depId.platform}::${node.depId.moduleName}'.`);
                 /** @type {Record<string, unknown>} */
                 const deps = {};
-                /** @type {Record<string, unknown>} */
-                const depsDecl = readDepsDecl(node.namespace, node.depId);
-                for (const [name, cdcValue] of Object.entries(depsDecl)) {
-                    const childDepId = parser.parse(/** @type {string} */ (cdcValue));
-                    deps[name] = build(getKey(childDepId));
+                for (const [name, childKey] of (node.dependencies ?? [])) {
+                    deps[name] = build(childKey);
                 }
                 const instantiated = instantiator.instantiate(node.depId, node.namespace, deps);
                 logger.log(`Container.pipeline: instantiate:exit '${node.depId.platform}::${node.depId.moduleName}'.`);
                 stage = 'postprocess';
                 logger.log(`Container.pipeline: postprocess:entry '${node.depId.platform}::${node.depId.moduleName}'.`);
-                const postprocessed = applyPostprocess(instantiated);
+                const postprocessed = applyPostprocess(instantiated, node.depId);
                 logger.log(`Container.pipeline: postprocess:exit '${node.depId.platform}::${node.depId.moduleName}'.`);
                 const wrapped = wrapperExecutor.execute(node.depId, postprocessed, node.namespace);
                 stage = 'freeze';

package/src/Container.mjs

@@ -32,7 +32,7 @@ export default class TeqFw_Di_Container {
         let state = 'notConfigured';
         /** @type {((depId: TeqFw_Di_DepId__DTO) => TeqFw_Di_DepId__DTO)[]} */
         const preprocess = [];
-        /** @type {((value: unknown) => unknown)[]} */
+        /** @type {((value: unknown, context: TeqFw_Di_Container_Postprocess_Context) => unknown)[]} */
         const postprocess = [];
         /** @type {TeqFw_Di_Dto_Resolver_Config_Namespace__DTO[]} */
         const namespaceRoots = [];
@@ -60,18 +60,13 @@ export default class TeqFw_Di_Container {
         const getKey = buildDependencyKey;
         const getMockKey = buildDependencyKey;
 
-        const freeze = function (value) {
+        let freeze = function (value) {
             if ((value === null) || (value === undefined)) return value;
             const type = typeof value;
             if ((type !== 'object') && (type !== 'function')) return value;
             if (Object.prototype.toString.call(value) === '[object Module]') return value;
             if (Object.isFrozen(value)) return value;
-            try {
-                Object.freeze(value);
-            } catch (error) {
-                logger.log(`Container.freeze: skipped (${String(error)}).`);
-            }
-            return value;
+            return Object.freeze(value);
         };
 
         const applyPreprocess = function (depId) {
@@ -81,10 +76,26 @@ export default class TeqFw_Di_Container {
             return current;
         };
 
-        const applyPostprocess = function (value) {
+        const canonicalize = function (specifier) {
+            return applyPreprocess(parser.parse(specifier));
+        };
+
+        const findMock = function (depId) {
+            const key = getMockKey(depId);
+            return {found: testMode === true && mockRegistry.has(key), value: mockRegistry.get(key)};
+        };
+
+        const applyPostprocess = function (value, depId) {
             /** @type {unknown} */
             let current = value;
-            for (const fn of postprocess) current = fn(current);
+            /** @type {TeqFw_Di_Container_Postprocess_Context} */
+            const context = Object.freeze({depId});
+            for (const fn of postprocess) {
+                current = fn(current, context);
+                if (current instanceof Promise) {
+                    throw new Error('Postprocess callback must return synchronously (non-Promise).');
+                }
+            }
             return current;
         };
 
@@ -104,7 +115,7 @@ export default class TeqFw_Di_Container {
             const resolverConfig = configFactory.create({namespaces: namespaceRoots});
             if (typeof parser.setLogger === 'function') parser.setLogger(logger);
             resolver = new TeqFw_Di_Resolver({config: resolverConfig, logger});
-            graphResolver = new TeqFw_Di_Container_GraphResolver({parser, resolver, logger});
+            graphResolver = new TeqFw_Di_Container_GraphResolver({canonicalize, findMock, resolver, logger});
             lifecycle = new TeqFw_Di_Container_Lifecycle(logger);
         };
 
@@ -123,7 +134,7 @@ export default class TeqFw_Di_Container {
         /**
          * Adds a postprocessing hook.
          *
-         * @param {(value: unknown) => unknown} fn
+         * @param {(value: unknown, context: TeqFw_Di_Container_Postprocess_Context) => unknown} fn
          * @returns {void}
          */
         this.addPostprocess = function (fn) {
@@ -132,6 +143,19 @@ export default class TeqFw_Di_Container {
             postprocess.push(fn);
         };
 
+
+        /**
+         * Sets the host hardening policy for every resolved value and mock.
+         *
+         * @param {(value: unknown) => unknown} fn
+         * @returns {void}
+         */
+        this.setHardener = function (fn) {
+            assertBuilderStage();
+            logBuilder('setHardener().');
+            freeze = fn;
+        };
+
         /**
          * Registers namespace root mapping.
          *
@@ -172,29 +196,29 @@ export default class TeqFw_Di_Container {
         };
 
         /**
-         * Registers a mock value for a CDC.
+         * Registers a mock value for a Dependency Specifier.
          *
-         * @param {string} cdc
+         * @param {string} specifier
          * @param {any} mock
          * @returns {void}
          */
-        this.register = function (cdc, mock) {
+        this.register = function (specifier, mock) {
             assertBuilderStage();
-            logBuilder(`register('${cdc}').`);
+            logBuilder(`register('${specifier}').`);
             if (testMode !== true) throw new Error('Container test mode is disabled.');
-            const depId = parser.parse(cdc);
+            const depId = canonicalize(specifier);
             mockRegistry.set(getMockKey(depId), mock);
         };
 
         /**
-         * Resolves a CDC into a frozen linked instance.
+         * Resolves a Dependency Specifier into a frozen Resolved Value.
          *
-         * @param {string} cdc
+         * @param {string} specifier
          * @returns {Promise<any>}
          */
-        this.get = async function (cdc) {
+        this.get = async function (specifier) {
             if (state === 'failed') {
-                logger.error(`Container.get: rejected in failed state cdc='${cdc}'.`);
+                logger.error(`Container.get: rejected in failed state specifier='${specifier}'.`);
                 throw new Error('Container is in failed state.');
             }
 
@@ -202,7 +226,6 @@ export default class TeqFw_Di_Container {
                 initializeInfrastructure();
                 logger.log(`Container.state: '${state}'.`);
                 return await executeContainerPipeline({
-                    parser,
                     resolver,
                     graphResolver,
                     lifecycle,
@@ -212,9 +235,9 @@ export default class TeqFw_Di_Container {
                     testMode,
                     mockRegistry,
                     freeze,
-                    applyPreprocess,
+                    canonicalize,
                     applyPostprocess,
-                }, cdc);
+                }, specifier);
             } catch (error) {
                 logger.error(`Container.transition: operational -> failed.`, error);
                 state = 'failed';
@@ -223,3 +246,12 @@ export default class TeqFw_Di_Container {
         };
     }
 }
+
+        const canonicalize = function (specifier) {
+            return applyPreprocess(parser.parse(specifier));
+        };
+
+        const findMock = function (depId) {
+            const key = getMockKey(depId);
+            return {found: testMode === true && mockRegistry.has(key), value: mockRegistry.get(key)};
+        };

package/src/Dto/DepId.mjs

@@ -47,7 +47,7 @@ export default class DTO {
     /** @type {string[]} Wrapper pipeline names. */
     wrappers;
 
-    /** @type {string} Original CDC string. */
+    /** @type {string} Original Dependency Specifier string. */
     origin;
 }
 

package/src/Internal/DepsDecl.mjs

@@ -9,7 +9,7 @@
  * Reads dependency declaration map for the selected export of a module namespace.
  *
  * @param {object} namespace Loaded module namespace.
- * @param {TeqFw_Di_DepId__DTO} depId Canonical dependency identity.
+ * @param {TeqFw_Di_DepId__DTO} depId Parsed dependency identity.
  * @returns {Record<string, unknown>} Dependency declaration map.
  */
 export function readDepsDecl(namespace, depId) {
@@ -24,7 +24,7 @@ export function readDepsDecl(namespace, depId) {
     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.');
+            throw new Error('__deps__ export entries must map dependency names to Dependency Specifier strings.');
         }
         return /** @type {Record<string, unknown>} */ (exportScoped);
     }