@codefast/di 0.5.0-canary.6 → 0.5.0-canary.7

package/dist/container/container.js

@@ -0,0 +1,641 @@
+import { bindingSlotEquals } from "#/binding";
+import { BindingEntry } from "#/container/binding-builders";
+import { AsyncModuleLoadError, CircularDependencyError, DisposedContainerError, InternalError, RebindUnboundTokenError, ScopeViolationError, SyncDisposalNotSupportedError, } from "#/errors";
+import { buildDependencyGraph } from "#/introspection/dependency-graph";
+import { Inspector } from "#/introspection/inspector";
+import { MetadataReaderToken } from "#/metadata/metadata-reader-token";
+import { defaultMetadataReader } from "#/metadata/symbol-metadata-reader";
+import { isSyncModule, MODULE_SETUP } from "#/module";
+import { BindingRegistry } from "#/registry";
+import { effectiveBindingScope } from "#/resolution/binding-scope";
+import { LifecycleManager } from "#/resolution/lifecycle";
+import { injectionSlotToResolveOptions, bindingSlotToResolveOptions } from "#/resolution/resolve-options";
+import { DependencyResolver } from "#/resolution/resolver";
+import { ScopeManager } from "#/resolution/scope";
+import { tokenName } from "#/token";
+// True when re-adding `restored` would immediately be displaced again by `current`
+// (both slot-based with equal slots) — in that case the replacement was legitimate.
+function displacesRestoredBinding(current, restored) {
+    const currentIsPurePredicate = current.predicate !== undefined && current.slot.name === undefined && current.slot.tags.length === 0;
+    if (currentIsPurePredicate) {
+        return false;
+    }
+    return bindingSlotEquals(current.slot, restored.slot);
+}
+// ── DefaultContainer ──────────────────────────────────────────────────────────
+class DefaultContainer {
+    #disposed = false;
+    #registry;
+    #scope;
+    #lifecycle;
+    #resolver;
+    #inspector;
+    #parent;
+    // Module tracking: module -> ref count
+    #moduleRefs = new Map();
+    // Module bindings: module -> array of binding IDs registered by it
+    #moduleBindingIds = new Map();
+    constructor(parent) {
+        this.#parent = parent;
+        this.#registry = new BindingRegistry();
+        this.#scope = new ScopeManager(parent !== undefined);
+        this.#lifecycle = new LifecycleManager();
+        this.#inspector = new Inspector(this.#registry, this.#scope, parent !== undefined, () => this.#disposed);
+        this.#initResolver();
+    }
+    #initResolver() {
+        const metadataReader = this.#getMetadataReader();
+        const parentResolver = this.#parent === undefined ? undefined : this.#parent.#resolver;
+        this.#resolver = new DependencyResolver(this.#registry, this.#scope, this.#lifecycle, metadataReader, this, parentResolver);
+    }
+    #getMetadataReader() {
+        // Check if a custom MetadataReader has been bound
+        const metaBindings = this.#registry.getAll(MetadataReaderToken);
+        if (metaBindings.length > 0) {
+            try {
+                return this.#resolver.resolve(MetadataReaderToken, undefined, [], []);
+            }
+            catch {
+                // fall through to default
+            }
+        }
+        if (this.#parent !== undefined) {
+            return this.#parent.#getMetadataReader();
+        }
+        return defaultMetadataReader;
+    }
+    get isDisposed() {
+        return this.#disposed;
+    }
+    // ── Binding ──────────────────────────────────────────────────────────────
+    bind(token) {
+        this.#assertNotDisposed();
+        return this.#createBindToBuilder(token);
+    }
+    #createBindToBuilder(token, moduleRef) {
+        const registry = this.#registry;
+        // Bindings displaced by this fluent chain's commits — each stays restorable
+        // until the chain settles on a shape that genuinely conflicts with it. A list,
+        // because one chain can displace several bindings (the default at an
+        // intermediate commit, then a named/tagged binding at the final one).
+        const displacedByChain = [];
+        const commitBinding = (binding, previousId) => {
+            if (previousId !== undefined) {
+                registry.removeById(previousId);
+                if (moduleRef !== undefined) {
+                    const ids = this.#moduleBindingIds.get(moduleRef);
+                    if (ids !== undefined) {
+                        const idx = ids.indexOf(previousId);
+                        if (idx !== -1) {
+                            ids.splice(idx, 1);
+                        }
+                    }
+                }
+            }
+            // The registry stores value-erased bindings — this is the single erasure point for the builder chain.
+            const displaced = registry.add(binding);
+            if (displaced !== undefined) {
+                // A fluent chain commits eagerly on each refinement, so an intermediate
+                // commit can displace a binding that the final shape would never conflict
+                // with. Remember it so a later re-commit that morphs away (named/tagged
+                // slot, pure predicate) can restore it.
+                displacedByChain.push(displaced);
+            }
+            if (previousId !== undefined && displacedByChain.length > 0) {
+                for (let index = displacedByChain.length - 1; index >= 0; index -= 1) {
+                    const candidate = displacedByChain[index];
+                    if (!displacesRestoredBinding(binding, candidate)) {
+                        registry.add(candidate);
+                        displacedByChain.splice(index, 1);
+                    }
+                }
+            }
+            if (moduleRef !== undefined) {
+                let ids = this.#moduleBindingIds.get(moduleRef);
+                if (ids === undefined) {
+                    ids = [];
+                    this.#moduleBindingIds.set(moduleRef, ids);
+                }
+                ids.push(binding.id);
+            }
+            return binding.id;
+        };
+        return new BindingEntry(token, commitBinding);
+    }
+    unbind(tokenOrId) {
+        this.#assertNotDisposed();
+        this.#unbindSync(tokenOrId);
+    }
+    /** Remove bindings from registry + scope and collect [binding, instance] pairs for deactivation. */
+    #collectDeactivationPairs(tokenOrId) {
+        if (typeof tokenOrId === "string") {
+            const binding = this.#registry.removeById(tokenOrId);
+            return binding === undefined ? [] : this.#drainSingletons([binding]);
+        }
+        // Dropping the whole token in one pass: removing each binding by id instead would re-scan and
+        // re-index the token's binding list once per binding.
+        return this.#drainSingletons(this.#registry.removeByToken(tokenOrId));
+    }
+    /** Drain singleton scope entries for a set of already-removed bindings. */
+    #drainSingletons(bindings) {
+        const pairs = [];
+        for (const binding of bindings) {
+            if (this.#scope.hasSingleton(binding.id)) {
+                pairs.push([binding, this.#scope.getSingleton(binding.id)]);
+                this.#scope.deleteSingleton(binding.id);
+            }
+        }
+        return pairs;
+    }
+    #unbindSync(tokenOrId) {
+        const reader = this.#getMetadataReader();
+        for (const [binding, instance] of this.#collectDeactivationPairs(tokenOrId)) {
+            this.#lifecycle.runDeactivationSync(binding, instance, reader);
+        }
+    }
+    async unbindAsync(tokenOrId) {
+        this.#assertNotDisposed();
+        const reader = this.#getMetadataReader();
+        for (const [binding, instance] of this.#collectDeactivationPairs(tokenOrId)) {
+            await this.#lifecycle.runDeactivation(binding, instance, reader);
+        }
+    }
+    unbindAll() {
+        this.#assertNotDisposed();
+        const reader = this.#getMetadataReader();
+        for (const [binding, instance] of this.#drainSingletons(this.#registry.clear())) {
+            this.#lifecycle.runDeactivationSync(binding, instance, reader);
+        }
+    }
+    async unbindAllAsync() {
+        this.#assertNotDisposed();
+        const reader = this.#getMetadataReader();
+        for (const [binding, instance] of this.#drainSingletons(this.#registry.clear())) {
+            await this.#lifecycle.runDeactivation(binding, instance, reader);
+        }
+    }
+    rebind(token) {
+        this.#assertNotDisposed();
+        if (!this.#registry.has(token)) {
+            throw new RebindUnboundTokenError(tokenName(token));
+        }
+        // Unbind existing (sync — if async deactivation, will throw AsyncDeactivationError)
+        this.#unbindSync(token);
+        return this.#createBindToBuilder(token);
+    }
+    // ── Module ────────────────────────────────────────────────────────────────
+    load(...modules) {
+        this.#assertNotDisposed();
+        this.#loadSyncModules(modules);
+    }
+    #loadSyncModules(modules) {
+        // Collect all modules in topological order (dedup by identity)
+        const toLoad = this.#collectModuleDeps(modules);
+        for (const module of toLoad) {
+            if (!isSyncModule(module)) {
+                throw new AsyncModuleLoadError(module.name);
+            }
+            const moduleRef = module;
+            const existing = this.#moduleRefs.get(moduleRef);
+            if (existing !== undefined) {
+                this.#moduleRefs.set(moduleRef, existing + 1);
+                continue;
+            }
+            this.#moduleRefs.set(moduleRef, 1);
+            const builder = this.#createModuleBuilder(moduleRef);
+            module[MODULE_SETUP](builder);
+        }
+    }
+    #collectModuleDeps(modules) {
+        const seen = new Set();
+        const result = [];
+        const visit = (module) => {
+            const moduleRef = module;
+            if (seen.has(moduleRef)) {
+                return;
+            }
+            seen.add(moduleRef);
+            // We'll collect deps during setup via the builder's import()
+            result.push(module);
+        };
+        for (const module of modules) {
+            visit(module);
+        }
+        return result;
+    }
+    async loadAsync(...modules) {
+        this.#assertNotDisposed();
+        for (const module of modules) {
+            await this.#loadOneModuleAsync(module);
+        }
+    }
+    async #loadOneModuleAsync(module) {
+        const moduleRef = module;
+        const existing = this.#moduleRefs.get(moduleRef);
+        if (existing !== undefined) {
+            this.#moduleRefs.set(moduleRef, existing + 1);
+            return;
+        }
+        this.#moduleRefs.set(moduleRef, 1);
+        if (isSyncModule(module)) {
+            const builder = this.#createModuleBuilder(moduleRef);
+            module[MODULE_SETUP](builder);
+        }
+        else {
+            const importPromises = [];
+            const builder = this.#createAsyncModuleBuilder(moduleRef, importPromises);
+            await module[MODULE_SETUP](builder);
+            // Await nested async imports triggered inside the setup callback
+            if (importPromises.length > 0) {
+                await Promise.all(importPromises);
+            }
+        }
+    }
+    #createModuleBuilder(moduleRef) {
+        return {
+            bind: (token) => this.#createBindToBuilder(token, moduleRef),
+            import: (...modules) => {
+                this.#loadSyncModules(modules);
+            },
+        };
+    }
+    #createAsyncModuleBuilder(moduleRef, importPromises) {
+        return {
+            bind: (token) => this.#createBindToBuilder(token, moduleRef),
+            import: (...modules) => {
+                for (const module of modules) {
+                    importPromises.push(this.#loadOneModuleAsync(module));
+                }
+            },
+        };
+    }
+    unload(...modules) {
+        this.#assertNotDisposed();
+        for (const module of modules) {
+            this.#unloadModuleSync(module);
+        }
+    }
+    /** Unregister module bindings and collect [binding, instance] pairs for deactivation. */
+    #removeModuleBindings(ref) {
+        this.#moduleRefs.delete(ref);
+        const ids = this.#moduleBindingIds.get(ref) ?? [];
+        this.#moduleBindingIds.delete(ref);
+        const pairs = [];
+        for (const id of ids) {
+            const binding = this.#registry.getById(id);
+            if (binding !== undefined) {
+                this.#registry.removeById(id);
+                if (this.#scope.hasSingleton(id)) {
+                    pairs.push([binding, this.#scope.getSingleton(id)]);
+                    this.#scope.deleteSingleton(id);
+                }
+            }
+        }
+        return pairs;
+    }
+    #unloadModuleSync(ref) {
+        const count = this.#moduleRefs.get(ref) ?? 0;
+        if (count <= 1) {
+            const reader = this.#getMetadataReader();
+            for (const [binding, instance] of this.#removeModuleBindings(ref)) {
+                this.#lifecycle.runDeactivationSync(binding, instance, reader);
+            }
+        }
+        else {
+            this.#moduleRefs.set(ref, count - 1);
+        }
+    }
+    async unloadAsync(...modules) {
+        this.#assertNotDisposed();
+        for (const module of modules) {
+            await this.#unloadModuleAsync(module);
+        }
+    }
+    async #unloadModuleAsync(ref) {
+        const count = this.#moduleRefs.get(ref) ?? 0;
+        if (count <= 1) {
+            const reader = this.#getMetadataReader();
+            for (const [binding, instance] of this.#removeModuleBindings(ref)) {
+                await this.#lifecycle.runDeactivation(binding, instance, reader);
+            }
+        }
+        else {
+            this.#moduleRefs.set(ref, count - 1);
+        }
+    }
+    loadAutoRegistered(registry) {
+        this.#assertNotDisposed();
+        const entries = registry.entries();
+        for (const { target, scope } of entries) {
+            const builder = this.#createBindToBuilder(target);
+            const bindingBuilder = builder.toSelf();
+            if (scope === "singleton") {
+                bindingBuilder.singleton();
+            }
+            else if (scope === "scoped") {
+                bindingBuilder.scoped();
+            }
+            else {
+                bindingBuilder.transient();
+            }
+        }
+        return entries.length;
+    }
+    // ── Lifecycle hooks ────────────────────────────────────────────────────────
+    onActivation(token, handler) {
+        this.#assertNotDisposed();
+        this.#lifecycle.registerActivation(token, handler);
+    }
+    onDeactivation(token, handler) {
+        this.#assertNotDisposed();
+        this.#lifecycle.registerDeactivation(token, handler);
+    }
+    // ── Resolution ────────────────────────────────────────────────────────────
+    resolve(token, options) {
+        this.#assertNotDisposed();
+        if (options === undefined) {
+            return this.#resolver.resolveFromContext(token, [], []);
+        }
+        return this.#resolver.resolve(token, options, [], []);
+    }
+    resolveAsync(token, options) {
+        this.#assertNotDisposed();
+        if (options === undefined) {
+            return this.#resolver.resolveAsyncFromContext(token, [], []);
+        }
+        return this.#resolver.resolveAsync(token, options, [], []);
+    }
+    resolveOptional(token, options) {
+        this.#assertNotDisposed();
+        return this.#resolver.resolveOptional(token, options, [], []);
+    }
+    resolveOptionalAsync(token, options) {
+        this.#assertNotDisposed();
+        return this.#resolver.resolveOptionalAsync(token, options, [], []);
+    }
+    resolveAll(token, options) {
+        this.#assertNotDisposed();
+        return this.#resolver.resolveAll(token, options, [], []);
+    }
+    resolveAllAsync(token, options) {
+        this.#assertNotDisposed();
+        return this.#resolver.resolveAllAsync(token, options, [], []);
+    }
+    // ── Child ─────────────────────────────────────────────────────────────────
+    createChild() {
+        this.#assertNotDisposed();
+        return new DefaultContainer(this);
+    }
+    // ── Dispose ───────────────────────────────────────────────────────────────
+    async dispose() {
+        if (this.#disposed) {
+            return;
+        }
+        this.#disposed = true;
+        // Deactivate all singletons in this container (own only)
+        const reader = this.#getMetadataReader();
+        for (const [id, instance] of this.#scope.getAllSingletons()) {
+            const binding = this.#registry.getById(id);
+            if (binding !== undefined) {
+                await this.#lifecycle.runDeactivation(binding, instance, reader);
+            }
+        }
+        this.#scope.clearAll();
+    }
+    [Symbol.asyncDispose]() {
+        return this.dispose();
+    }
+    [Symbol.dispose]() {
+        throw new SyncDisposalNotSupportedError();
+    }
+    // ── Initialization ────────────────────────────────────────────────────────
+    async initializeAsync() {
+        this.#assertNotDisposed();
+        const allBindings = this.#registry.allBindings();
+        for (const binding of allBindings) {
+            if (binding.kind === "alias") {
+                continue;
+            }
+            const scope = effectiveBindingScope(binding);
+            if (scope === "singleton" && !this.#scope.hasSingleton(binding.id)) {
+                if (binding.predicate !== undefined) {
+                    continue;
+                }
+                // Has activation — need to resolve
+                if (binding.kind === "constant" && binding.onActivation === undefined) {
+                    continue;
+                }
+                const slotOptions = bindingSlotToResolveOptions(binding.slot);
+                await this.resolveAsync(binding.token, slotOptions);
+            }
+        }
+    }
+    // ── Validate ──────────────────────────────────────────────────────────────
+    validate() {
+        this.#assertNotDisposed();
+        const reader = this.#getMetadataReader();
+        const allBindings = this.#registry.allBindings();
+        for (const binding of allBindings) {
+            if (!this.#isSingletonStaticAnalyzableBinding(binding)) {
+                continue;
+            }
+            this.#validateSingletonBindingGraph(binding, reader);
+        }
+    }
+    #isSingletonStaticAnalyzableBinding(binding) {
+        if (effectiveBindingScope(binding) !== "singleton") {
+            return false;
+        }
+        return binding.kind === "class" || binding.kind === "resolved" || binding.kind === "resolved-async";
+    }
+    /**
+     * DFS over explicit constructor / `toResolved*` dependency edges. Follows `toAlias` chains to the
+     * terminal binding for scope checks (SPEC §6.9).
+     *
+     * @remarks A `toDynamic*` dependency is scope-checked like any other — its declared scope is what
+     * makes it captive — but the DFS does not descend into the factory, whose body is opaque.
+     */
+    #validateSingletonBindingGraph(root, reader) {
+        const rootName = tokenName(root.token);
+        const dfs = (current, pathNames, pathBindingIds) => {
+            if (pathBindingIds.has(current.id)) {
+                return;
+            }
+            const extendedPathIds = new Set(pathBindingIds);
+            extendedPathIds.add(current.id);
+            for (const edge of this.#collectStaticDependencyEdges(current, reader)) {
+                const { terminal, depTokenName } = edge;
+                const depScope = this.#validationScopeFromTerminal(terminal);
+                if (depScope === "opaque") {
+                    continue;
+                }
+                if (depScope === "scoped" || depScope === "transient") {
+                    throw new ScopeViolationError({
+                        consumerToken: rootName,
+                        consumerScope: "singleton",
+                        dependencyToken: depTokenName,
+                        dependencyScope: depScope,
+                        path: [...pathNames, depTokenName],
+                    });
+                }
+                if (terminal.kind === "class" || terminal.kind === "resolved" || terminal.kind === "resolved-async") {
+                    dfs(terminal, [...pathNames, depTokenName], extendedPathIds);
+                }
+            }
+        };
+        dfs(root, [rootName], new Set());
+    }
+    #validationScopeFromTerminal(terminal) {
+        switch (terminal.kind) {
+            case "constant":
+                return "singleton";
+            // A factory's *body* is not statically analyzable, but the scope it was bound with is
+            // declared like any other — so the captive-dependency check applies. The DFS below still
+            // refuses to descend into the factory; only this edge is judged.
+            case "dynamic":
+            case "dynamic-async":
+                return terminal.scope;
+            case "class":
+            case "resolved":
+            case "resolved-async":
+                return terminal.scope;
+            case "alias":
+                throw new InternalError("validate: expected terminal binding after alias resolution");
+            default: {
+                const exhaustive = terminal;
+                return exhaustive;
+            }
+        }
+    }
+    #followAliasChainToTerminal(binding, options) {
+        const cyclePath = [];
+        const seenAliasIds = new Set();
+        let current = binding;
+        while (current !== undefined && current.kind === "alias") {
+            if (seenAliasIds.has(current.id)) {
+                throw new CircularDependencyError(cyclePath);
+            }
+            seenAliasIds.add(current.id);
+            cyclePath.push(tokenName(current.token));
+            const nextToken = current.target;
+            const next = this.#resolver.peekBindingForValidate(nextToken, options);
+            if (next === undefined) {
+                return undefined;
+            }
+            current = next.binding;
+        }
+        return current;
+    }
+    #collectStaticDependencyEdges(binding, reader) {
+        const edges = [];
+        const pushTerminal = (terminal, displayName) => {
+            if (terminal === undefined) {
+                return;
+            }
+            edges.push({ terminal, depTokenName: displayName });
+        };
+        if (binding.kind === "class") {
+            const meta = reader.getConstructorMetadata(binding.target);
+            if (meta === undefined) {
+                return edges;
+            }
+            for (const param of meta.params) {
+                const paramOptions = injectionSlotToResolveOptions(param);
+                if (param.optional) {
+                    continue;
+                }
+                const tokenRef = param.token;
+                if (param.multi) {
+                    const candidates = this.#resolver.peekCandidateBindingsForValidate(tokenRef, paramOptions);
+                    for (const cand of candidates) {
+                        const term = this.#followAliasChainToTerminal(cand, paramOptions);
+                        pushTerminal(term, term !== undefined ? tokenName(term.token) : "");
+                    }
+                    continue;
+                }
+                const found = paramOptions === undefined
+                    ? this.#resolver.peekBindingForValidate(tokenRef, undefined)
+                    : this.#resolver.peekBindingForValidate(tokenRef, paramOptions);
+                if (found === undefined) {
+                    continue;
+                }
+                const term = this.#followAliasChainToTerminal(found.binding, paramOptions);
+                pushTerminal(term, term !== undefined ? tokenName(term.token) : "");
+            }
+            return edges;
+        }
+        if (binding.kind === "resolved" || binding.kind === "resolved-async") {
+            for (const dep of binding.deps) {
+                const depOptions = injectionSlotToResolveOptions(dep);
+                if (dep.optional) {
+                    continue;
+                }
+                const tokenRef = dep.token;
+                if (dep.multi) {
+                    const candidates = this.#resolver.peekCandidateBindingsForValidate(tokenRef, depOptions);
+                    for (const cand of candidates) {
+                        const term = this.#followAliasChainToTerminal(cand, depOptions);
+                        pushTerminal(term, term !== undefined ? tokenName(term.token) : "");
+                    }
+                    continue;
+                }
+                const found = depOptions === undefined
+                    ? this.#resolver.peekBindingForValidate(tokenRef, undefined)
+                    : this.#resolver.peekBindingForValidate(tokenRef, depOptions);
+                if (found === undefined) {
+                    continue;
+                }
+                const term = this.#followAliasChainToTerminal(found.binding, depOptions);
+                pushTerminal(term, term !== undefined ? tokenName(term.token) : "");
+            }
+        }
+        return edges;
+    }
+    // ── Introspection ─────────────────────────────────────────────────────────
+    has(token, options) {
+        this.#assertNotDisposed();
+        return this.#inspector.has(token, options, () => this.#parent?.has(token, options) ?? false);
+    }
+    hasOwn(token, options) {
+        this.#assertNotDisposed();
+        return this.#inspector.hasOwn(token, options);
+    }
+    lookupBindings(token) {
+        this.#assertNotDisposed();
+        return this.#inspector.lookupBindings(token);
+    }
+    inspect() {
+        this.#assertNotDisposed();
+        return this.#inspector.inspect();
+    }
+    generateDependencyGraph(options) {
+        this.#assertNotDisposed();
+        return buildDependencyGraph(this.#registry, this.#getMetadataReader(), options, this.#parent === undefined ? undefined : this.#parent.#registry);
+    }
+    // ── Internal ──────────────────────────────────────────────────────────────
+    #assertNotDisposed() {
+        if (this.#disposed) {
+            throw new DisposedContainerError();
+        }
+    }
+}
+// ── Container static ──────────────────────────────────────────────────────────
+/**
+ * @since 0.3.16-canary.0
+ */
+export const Container = {
+    create() {
+        return new DefaultContainer();
+    },
+    fromModules(...modules) {
+        const container = new DefaultContainer();
+        container.load(...modules);
+        return container;
+    },
+    async fromModulesAsync(...modules) {
+        const container = new DefaultContainer();
+        await container.loadAsync(...modules);
+        return container;
+    },
+};
+//# sourceMappingURL=container.js.map