@teqfw/di 1.3.0 → 2.0.0

package/src/Container/Lifecycle/Registry.mjs

@@ -0,0 +1,81 @@
+// @ts-check
+
+import TeqFw_Di_Enum_Composition from '../../Enum/Composition.mjs';
+import TeqFw_Di_Enum_Life from '../../Enum/Life.mjs';
+
+/**
+ * Lifecycle-stage registry for produced dependency values.
+ *
+ * Applies lifecycle caching policy to already instantiated values:
+ * - singleton factory values are cached by structural DepId identity;
+ * - transient values are never cached;
+ * - as-is composition is returned as produced without lifecycle caching.
+ */
+export default class TeqFw_Di_Container_Lifecycle_Registry {
+
+    /**
+     * Creates lifecycle registry instance.
+     */
+    constructor(logger = null) {
+        /** @type {Map<string, unknown>} */
+        const singletonCache = new Map();
+        /** @type {{log(message: string): void}|null} */
+        const log = logger;
+
+        /**
+         * Builds deterministic cache key from structural DepId fields.
+         *
+         * @param {TeqFw_Di_DepId$DTO} depId
+         * @returns {string}
+         */
+        const buildKey = function (depId) {
+            /** @type {string} */
+            const wrappers = Array.isArray(depId.wrappers) ? depId.wrappers.join('|') : '';
+            return [
+                depId.platform,
+                depId.moduleName,
+                depId.exportName === null ? '' : depId.exportName,
+                depId.composition,
+                depId.life === null ? '' : depId.life,
+                wrappers,
+            ].join('::');
+        };
+
+        /**
+         * Returns value according to lifecycle policy.
+         *
+         * @param {TeqFw_Di_DepId$DTO} depId
+         * @param {() => unknown} producer
+         * @returns {unknown}
+         */
+        this.apply = function (depId, producer) {
+            if (depId.composition !== TeqFw_Di_Enum_Composition.FACTORY) {
+                if (log) log.log(`Lifecycle.apply: composition='${depId.composition}' cache=skip.`);
+                return producer();
+            }
+
+            if (depId.life === TeqFw_Di_Enum_Life.TRANSIENT) {
+                if (log) log.log('Lifecycle.apply: transient cache=skip.');
+                return producer();
+            }
+
+            if (depId.life === TeqFw_Di_Enum_Life.SINGLETON) {
+                /** @type {string} */
+                const key = buildKey(depId);
+                if (singletonCache.has(key)) {
+                    if (log) log.log(`Lifecycle.cache: hit key='${key}'.`);
+                    return singletonCache.get(key);
+                }
+                if (log) log.log(`Lifecycle.cache: miss key='${key}', create.`);
+                /** @type {unknown} */
+                const created = producer();
+                singletonCache.set(key, created);
+                if (log) log.log(`Lifecycle.cache: stored key='${key}'.`);
+                return created;
+            }
+
+            if (log) log.log('Lifecycle.apply: no lifecycle marker cache=skip.');
+            return producer();
+        };
+    }
+}

package/src/Container/Resolve/GraphResolver.mjs

@@ -0,0 +1,119 @@
+// @ts-check
+
+/**
+ * Resolve-stage graph builder.
+ *
+ * Recursively resolves module namespaces and their declared `__deps__`
+ * into a deterministic map keyed by `${platform}::${moduleName}`.
+ */
+
+/**
+ * @typedef {object} TeqFw_Di_Container_Resolve_GraphResolver_Dependencies
+ * @property {TeqFw_Di_Def_Parser} parser
+ * @property {TeqFw_Di_Resolver} resolver
+ * @property {{log(message: string): void}|null} [logger]
+ */
+
+/**
+ * @typedef {{depId: TeqFw_Di_DepId$DTO, namespace: object}} TeqFw_Di_Container_Resolve_GraphResolver_Node
+ */
+
+export default class TeqFw_Di_Container_Resolve_GraphResolver {
+
+    /**
+     * @param {TeqFw_Di_Container_Resolve_GraphResolver_Dependencies} deps
+     */
+    constructor({parser, resolver, logger = null}) {
+        /** @type {{log(message: string): void}|null} */
+        const log = logger;
+
+        /**
+         * @param {TeqFw_Di_DepId$DTO} depId
+         * @returns {string}
+         */
+        const makeNodeKey = function (depId) {
+            return `${depId.platform}::${depId.moduleName}`;
+        };
+
+        /**
+         * @param {TeqFw_Di_DepId$DTO} depId
+         * @returns {string}
+         */
+        const makeDepIdentity = function (depId) {
+            /** @type {string} */
+            const wrappers = Array.isArray(depId.wrappers) ? depId.wrappers.join('|') : '';
+            return [
+                depId.platform,
+                depId.moduleName,
+                depId.exportName === null ? '' : depId.exportName,
+                depId.composition,
+                depId.life === null ? '' : depId.life,
+                wrappers,
+            ].join('::');
+        };
+
+        /**
+         * @param {TeqFw_Di_DepId$DTO} depId
+         * @param {Map<string, TeqFw_Di_Container_Resolve_GraphResolver_Node>} out
+         * @param {Set<string>} stack
+         * @param {string[]} chain
+         * @returns {Promise<void>}
+         */
+        const walk = async function (depId, out, stack, chain) {
+            /** @type {string} */
+            const identity = makeDepIdentity(depId);
+            if (stack.has(identity)) {
+                /** @type {string} */
+                const cycle = [...chain, identity].join(' -> ');
+                throw new Error(`Cyclic dependency detected: ${cycle}`);
+            }
+
+            /** @type {string} */
+            const key = makeNodeKey(depId);
+            if (out.has(key)) 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 {unknown} */
+                const depsDecl = Reflect.get(namespace, '__deps__');
+                if (depsDecl === undefined) return;
+                /** @type {Record<string, unknown>} */
+                const depsMap = /** @type {Record<string, unknown>} */ (depsDecl);
+                for (const [, cdc] of Object.entries(depsMap)) {
+                    /** @type {string} */
+                    const nextCdc = /** @type {string} */ (cdc);
+                    /** @type {TeqFw_Di_DepId$DTO} */
+                    const nextDepId = parser.parse(nextCdc);
+                    if (log) log.log(`GraphResolver.walk: edge '${key}' -> '${nextDepId.platform}::${nextDepId.moduleName}'.`);
+                    await walk(nextDepId, out, stack, chain);
+                }
+            } finally {
+                chain.pop();
+                stack.delete(identity);
+            }
+        };
+
+        /**
+         * Resolves full dependency graph for a root depId.
+         *
+         * @param {TeqFw_Di_DepId$DTO} depId
+         * @returns {Promise<Map<string, TeqFw_Di_Container_Resolve_GraphResolver_Node>>}
+         */
+        this.resolve = async function (depId) {
+            /** @type {Map<string, TeqFw_Di_Container_Resolve_GraphResolver_Node>} */
+            const out = new Map();
+            /** @type {Set<string>} */
+            const stack = new Set();
+            /** @type {string[]} */
+            const chain = [];
+            await walk(depId, out, stack, chain);
+            return out;
+        };
+    }
+}

package/src/Container/Resolver.mjs

@@ -0,0 +1,175 @@
+// @ts-check
+
+/**
+ * @typedef {object} TeqFw_Di_Resolver_Dependencies
+ * @property {TeqFw_Di_Dto_Resolver_Config$DTO} config Resolver configuration DTO.
+ * @property {(specifier: string) => Promise<object>} [importFn] Import function override.
+ * @property {{log(message: string): void, error(message: string, error?: unknown): void}|null} [logger]
+ */
+
+/**
+ * @typedef {{prefix: string, target: string, defaultExt: string}} TeqFw_Di_Resolver_NamespaceRule
+ */
+
+/**
+ * Infrastructure resolver that derives module specifiers, loads module namespace objects,
+ * and caches them by `(platform, moduleName)`.
+ */
+export default class TeqFw_Di_Resolver {
+    /**
+     * Initializes resolver with runtime dependencies.
+     *
+     * @param {TeqFw_Di_Resolver_Dependencies} param0 Resolver dependencies descriptor.
+     */
+    constructor({config, importFn = (specifier) => import(specifier), logger = null}) {
+        /** @type {Map<string, Promise<object>>} Cache keyed by `(platform,moduleName)`. */
+        const cache = new Map();
+        /** @type {TeqFw_Di_Dto_Resolver_Config$DTO} Original config reference captured from dependencies. */
+        const configInput = config;
+        /** @type {{nodeModulesRoot: (string|undefined), namespaces: TeqFw_Di_Resolver_NamespaceRule[]}|undefined} */
+        let configSnapshot;
+        /** @type {(specifier: string) => Promise<object>} Import function used for namespace loading. */
+        const importModule = importFn;
+        /** @type {{log(message: string): void, error(message: string, error?: unknown): void}|null} */
+        const log = logger;
+
+        /**
+         * Creates immutable-in-effect structural snapshot used for all post-start resolutions.
+         *
+         * @param {TeqFw_Di_Dto_Resolver_Config$DTO} input Resolver config DTO.
+         * @returns {{nodeModulesRoot: (string|undefined), namespaces: TeqFw_Di_Resolver_NamespaceRule[]}}
+         */
+        const makeConfigSnapshot = function (input) {
+            return {
+                nodeModulesRoot: input.nodeModulesRoot,
+                namespaces: input.namespaces.map((one) => ({
+                    prefix: one.prefix,
+                    target: one.target,
+                    defaultExt: one.defaultExt,
+                })),
+            };
+        };
+
+        /**
+         * Selects namespace rule with deterministic longest-prefix match.
+         *
+         * @param {string} moduleName Teq module namespace.
+         * @returns {TeqFw_Di_Resolver_NamespaceRule}
+         */
+        const selectNamespaceRule = function (moduleName) {
+            /** @type {TeqFw_Di_Resolver_NamespaceRule|null} */
+            let found = null;
+            let foundLen = -1;
+            /** @type {TeqFw_Di_Resolver_NamespaceRule[]} */
+            const items = configSnapshot.namespaces;
+            for (const one of items) {
+                const match = moduleName.startsWith(one.prefix);
+                if (log) log.log(`Resolver.namespace: prefix='${one.prefix}' match=${String(match)} module='${moduleName}'.`);
+                if (!match) continue;
+                if (one.prefix.length > foundLen) {
+                    found = one;
+                    foundLen = one.prefix.length;
+                }
+            }
+            if (!found) throw new Error(`Namespace rule is not found for '${moduleName}'.`);
+            return found;
+        };
+
+        /**
+         * Appends default extension exactly once.
+         *
+         * @param {string} path Relative module path.
+         * @param {string} defaultExt Namespace default extension.
+         * @returns {string}
+         */
+        const appendExt = function (path, defaultExt) {
+            if (!defaultExt) return path;
+            if (path.endsWith(defaultExt)) return path;
+            return `${path}${defaultExt}`;
+        };
+
+        /**
+         * Joins namespace target and relative path without path normalization.
+         *
+         * @param {string} target Namespace target.
+         * @param {string} path Relative module path.
+         * @returns {string}
+         */
+        const join = function (target, path) {
+            if (!target) return path;
+            if (target.endsWith('/')) return `${target}${path}`;
+            return `${target}/${path}`;
+        };
+
+        /**
+         * Derives module specifier from depId structural fields.
+         *
+         * @param {TeqFw_Di_Enum_Platform[keyof TeqFw_Di_Enum_Platform]} platform DepId platform.
+         * @param {string} moduleName DepId module namespace.
+         * @returns {string}
+         */
+        const deriveSpecifier = function (platform, moduleName) {
+            if (platform === 'node') {
+                const specifier = `node:${moduleName}`;
+                if (log) log.log(`Resolver.specifier: module='${moduleName}' -> '${specifier}'.`);
+                return specifier;
+            }
+            if (platform === 'npm') {
+                const specifier = moduleName;
+                if (log) log.log(`Resolver.specifier: module='${moduleName}' -> '${specifier}'.`);
+                return specifier;
+            }
+            if (platform !== 'teq') throw new Error(`Unsupported platform: ${platform}`);
+
+            /** @type {TeqFw_Di_Resolver_NamespaceRule} */
+            const rule = selectNamespaceRule(moduleName);
+            const remainder = moduleName.slice(rule.prefix.length);
+            const relativePath = remainder.split('_').join('/');
+            const filePath = appendExt(relativePath, rule.defaultExt);
+            const specifier = join(rule.target, filePath);
+            if (log) log.log(`Resolver.specifier: module='${moduleName}' -> '${specifier}'.`);
+            return specifier;
+        };
+
+        /**
+         * Resolves module namespace object by depId platform and moduleName.
+         *
+         * @param {TeqFw_Di_DepId$DTO} depId Validated dependency identity DTO.
+         * @returns {Promise<object>} Promise resolved with ES module namespace object.
+         */
+        this.resolve = async function (depId) {
+            await Promise.resolve();
+
+            if (!configSnapshot) {
+                configSnapshot = makeConfigSnapshot(configInput);
+            }
+
+            const platform = depId.platform;
+            const moduleName = depId.moduleName;
+            const key = `${platform}::${moduleName}`;
+
+            if (cache.has(key)) {
+                if (log) log.log(`Resolver.cache: hit key='${key}'.`);
+                return cache.get(key);
+            }
+            if (log) log.log(`Resolver.cache: miss key='${key}'.`);
+
+            /** @type {Promise<object>} */
+            const promise = (async () => {
+                const specifier = deriveSpecifier(platform, moduleName);
+                if (log) log.log(`Resolver.import: '${specifier}'.`);
+                return importModule(specifier);
+            })();
+
+            cache.set(key, promise);
+
+            try {
+                return await promise;
+            } catch (error) {
+                cache.delete(key);
+                if (log) log.error(`Resolver.cache: evict key='${key}' after failure.`, error);
+                throw error;
+            }
+        };
+    }
+}

package/src/Container/Wrapper/Executor.mjs

@@ -0,0 +1,71 @@
+// @ts-check
+
+/**
+ * Wrapper-stage executor.
+ *
+ * Executes wrapper pipeline declared in `depId.wrappers` using functions
+ * exported by the resolved module namespace.
+ */
+export default class TeqFw_Di_Container_Wrapper_Executor {
+
+    /**
+     * Creates wrapper executor instance.
+     */
+    constructor() {
+        /**
+         * 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');
+        };
+
+        /**
+         * Narrows unknown export to unary wrapper callable.
+         *
+         * @param {unknown} value
+         * @returns {value is (value: unknown) => unknown}
+         */
+        const isWrapper = function (value) {
+            return (typeof value === 'function');
+        };
+
+        /**
+         * Applies wrappers in declaration order.
+         *
+         * @param {TeqFw_Di_DepId$DTO} depId
+         * @param {unknown} value
+         * @param {object} moduleNamespace
+         * @returns {unknown}
+         */
+        this.execute = function (depId, value, moduleNamespace) {
+            /** @type {unknown} */
+            let current = value;
+            const wrappers = depId.wrappers;
+
+            for (const name of wrappers) {
+                if (!(name in moduleNamespace)) {
+                    throw new Error(`Wrapper '${name}' is not found in module namespace.`);
+                }
+                /** @type {unknown} */
+                const candidate = moduleNamespace[name];
+                if (!isWrapper(candidate)) {
+                    throw new Error(`Wrapper '${name}' must be callable.`);
+                }
+                current = candidate(current);
+                if (isThenable(current)) {
+                    throw new Error(`Wrapper '${name}' must return synchronously (non-thenable).`);
+                }
+            }
+
+            return current;
+        };
+    }
+}