@codefast/di 0.11.0 → 0.12.0

package/dist/container/container.d.ts

@@ -1,11 +1,12 @@
-import type { BindToBuilder } from "#core/binding";
+import type { BindToBuilder } from "#core/binding-builders";
 import type { AsyncModule, SyncModule } from "#core/module";
 import type { Token } from "#core/token";
 import type { ActivationHandler, BindingIdentifier, Constructor, DeactivationHandler, ResolveOptions } from "#core/types";
 import type { AutoRegisterRegistry } from "#decorators/injectable";
 import type { ContainerGraphJson, GraphOptions } from "#introspection/dependency-graph";
+import type { ExplainOptions, ResolutionExplanation } from "#introspection/explanation";
 import type { BindingSnapshot, ContainerSnapshot } from "#introspection/inspector";
-import type { MetadataReader } from "#metadata/metadata-types";
+import type { MetadataReader } from "#metadata/types";
 /**
  * The public surface: binding, resolving, modules, lifecycle hooks, child scopes, and disposal.
  *
@@ -42,6 +43,14 @@ export interface Container {
     hasOwn<Names extends string = string>(token: Token<unknown, Names> | Constructor, options?: NoInfer<ResolveOptions<Names>>): boolean;
     lookupBindings<Value>(token: Token<Value> | Constructor<Value>): ReadonlyArray<BindingSnapshot>;
     inspect(): ContainerSnapshot;
+    /**
+     * Explains why a request selects the binding it does, reading each registry the way `resolve` does and deciding
+     * by the same rules, without instantiating anything.
+     *
+     * @remarks A `when()` predicate runs here as it would in `resolve`. `options.ancestors` names the resolutions the
+     * request is nested in, so a predicate that reads the parent sees the one it would.
+     */
+    explain<Names extends string = string>(token: Token<unknown, Names> | Constructor, options?: NoInfer<ExplainOptions<Names>>): ResolutionExplanation;
     generateDependencyGraph(options?: GraphOptions): ContainerGraphJson;
 }
 /**

package/dist/container/container.js

@@ -1,23 +1,23 @@
-import { BindingChain } from "#container/binding-builders";
-import { NO_INSTANCE } from "#core/binding";
-import { effectiveBindingScope } from "#core/binding-scope";
+import { BindingChain } from "#container/binding-chain";
+import { effectiveBindingScope, NO_INSTANCE } from "#core/binding";
 import { constraintRequirementsOf } from "#core/constraint-requirement";
 import { getOrInsert, getOrInsertComputed } from "#core/map-upsert";
 import { isSyncModule, MODULE_SETUP } from "#core/module";
 import { BindingRegistry } from "#core/registry";
 import { advanceDisposeEpoch, disposeEpochRef } from "#core/state-epoch";
 import { tokenName } from "#core/token";
-import { RESOLUTION_DIAGNOSTICS } from "#errors/diagnostics";
-import { AsyncModuleLoadError, CircularDependencyError, DisposedContainerError, InternalError, RebindUnboundTokenError, ScopeViolationError, SyncDisposalNotSupportedError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#errors/errors";
-import { injectionSlotToResolveOptions, bindingSlotToResolveOptions } from "#injection/resolve-options";
+import { AsyncModuleLoadError, CircularDependencyError, DisposedContainerError, InternalError, RebindUnboundTokenError, ScopeViolationError, SyncDisposalNotSupportedError, UnreachableConstraintError, UnreachableLifecycleHookError, } from "#errors";
+import { injectionSlotToResolveOptions, bindingSlotToResolveOptions } from "#injection/dependency-slot";
 import { buildDependencyGraph } from "#introspection/dependency-graph";
+import { RESOLUTION_DIAGNOSTICS } from "#introspection/diagnostics";
+import { explainRequest } from "#introspection/explanation";
 import { Inspector } from "#introspection/inspector";
-import { LifecycleManager } from "#lifecycle/lifecycle-manager";
-import { ScopeManager } from "#lifecycle/scope-manager";
-import { MetadataReaderToken } from "#metadata/metadata-reader-token";
-import { defaultMetadataReader } from "#metadata/symbol-metadata-reader";
-import { verifyingMetadataReader } from "#metadata/verifying-metadata-reader";
-import { ROOT_BRANCH } from "#resolution/path/resolution-path";
+import { LifecycleManager } from "#lifecycle/hooks";
+import { ScopeManager } from "#lifecycle/scopes";
+import { MetadataReaderToken } from "#metadata/reader-token";
+import { defaultMetadataReader } from "#metadata/symbol-reader";
+import { verifyingMetadataReader } from "#metadata/verifying-reader";
+import { ROOT_BRANCH } from "#resolution/path";
 import { DependencyResolver } from "#resolution/resolver";
 /** Whether a requirement's name is declared — on its token when it names one, on any token otherwise. */
 function isSlotNameDeclared(declared, requirement) {
@@ -76,6 +76,8 @@ class DefaultContainer {
     // unload of its module drains it, and dispose runs a constant's hook, which neither the registry nor the cache holds.
     #orphanedBindings;
     constructor(parent, options) {
+        // oxlint-disable-next-line typescript/unbound-method -- installed as this instance's own method, so `this` is it
+        this.resolve = parent === undefined ? DefaultContainer.#rootResolve : DefaultContainer.#childResolve;
         this.#parent = parent;
         this.#registry = new BindingRegistry();
         this.#scope = new ScopeManager(parent !== undefined);
@@ -152,13 +154,10 @@ class DefaultContainer {
             onDisplaced: (binding) => {
                 this.#recordDisplaced(binding);
             },
-            onRestored: (binding) => {
-                this.#orphanedBindings?.delete(binding.identifier);
-            },
         });
     }
-    // A displaced binding holding a cached instance or owing a constant's deactivation is remembered;
-    // a later restore takes it back out, and every other displaced binding is dropped as before.
+    // A displaced binding holding a cached instance or owing a constant's deactivation is remembered until
+    // dispose, an unbind of its id or its module's unload; every other displaced binding is dropped.
     #recordDisplaced(binding) {
         if (binding.instance !== NO_INSTANCE || this.#owesConstantDeactivation(binding)) {
             (this.#orphanedBindings ??= new Map()).set(binding.identifier, binding);
@@ -167,18 +166,17 @@ class DefaultContainer {
     /**
      * One registration per module load, holding that module's id list directly.
      *
-     * @remarks It borrows the container's own displacement callbacks, so a constant a module's bind
-     * displaces is parked for dispose exactly as one displaced by `bind()` is.
+     * @remarks It borrows the container's own displacement callback, so a constant a module's bind
+     * displaces is kept for dispose exactly as one displaced by `bind()` is.
      */
     #moduleRegistration(moduleRef) {
         this.#moduleBindingIds ??= new Map();
-        const { onDisplaced, onRestored } = this.#ownRegistration();
+        const { onDisplaced } = this.#ownRegistration();
         return {
             registry: this.#registry,
             scope: this.#scope,
             moduleBindingIds: getOrInsert(this.#moduleBindingIds, moduleRef, []),
             onDisplaced,
-            onRestored,
         };
     }
     #createBindToBuilder(token, registration = this.#ownRegistration()) {
@@ -198,13 +196,8 @@ class DefaultContainer {
         // re-index the token's binding list once per binding.
         return this.#drainSingletons(this.#registry.removeByToken(tokenOrId));
     }
-    /**
-     * Retires an id the registry no longer holds, returning the displaced binding still owed a teardown.
-     *
-     * @remarks Counts as a registry write, so no chain holding the binding parked can restore it.
-     */
+    /** Retires an id the registry no longer holds, returning the displaced binding still owed a teardown. */
     #retireNotLive(id) {
-        this.#registry.touch();
         const orphaned = this.#orphanedBindings?.get(id);
         if (orphaned !== undefined) {
             this.#orphanedBindings.delete(id);
@@ -217,18 +210,22 @@ class DefaultContainer {
         // ever cached — the hot-swap shape — owes no deactivation and hands the shared empty list back.
         let pairs;
         for (let index = 0; index < bindings.length; index += 1) {
-            const binding = bindings[index];
-            if (binding.instance !== NO_INSTANCE) {
-                (pairs ??= []).push(binding, binding.instance);
-                this.#scope.deleteSingleton(binding);
-            }
-            else if (this.#owesConstantDeactivation(binding)) {
-                (pairs ??= []).push(binding, binding.value);
-            }
-            this.#scope.deleteScoped(binding.identifier);
+            pairs = this.#drainSingleton(bindings[index], pairs);
         }
         return pairs ?? NO_DEACTIVATION_PAIRS;
     }
+    /** One binding's share of {@link DefaultContainer.#drainSingletons}, allocating `pairs` on the first pair owed. */
+    #drainSingleton(binding, pairs) {
+        if (binding.instance !== NO_INSTANCE) {
+            (pairs ??= []).push(binding, binding.instance);
+            this.#scope.deleteSingleton(binding);
+        }
+        else if (this.#owesConstantDeactivation(binding)) {
+            (pairs ??= []).push(binding, binding.value);
+        }
+        this.#scope.deleteScoped(binding.scopedCacheKey);
+        return pairs;
+    }
     /**
      * Whether a constant still owes its deactivation.
      *
@@ -246,10 +243,11 @@ class DefaultContainer {
             return;
         }
         const reader = this.#getMetadataReader();
+        const lifecycle = this.#lifecycle;
         let errors;
         for (let index = 0; index < pairs.length; index += 2) {
             try {
-                this.#lifecycle.runDeactivationSync(pairs[index], pairs[index + 1], reader);
+                lifecycle.runDeactivationSync(pairs[index], pairs[index + 1], reader);
             }
             catch (error) {
                 (errors ??= []).push(error);
@@ -264,10 +262,11 @@ class DefaultContainer {
             return;
         }
         const reader = this.#getMetadataReader();
+        const lifecycle = this.#lifecycle;
         let errors;
         for (let index = 0; index < pairs.length; index += 2) {
             try {
-                await this.#lifecycle.runDeactivation(pairs[index], pairs[index + 1], reader);
+                await lifecycle.runDeactivation(pairs[index], pairs[index + 1], reader);
             }
             catch (error) {
                 (errors ??= []).push(error);
@@ -317,14 +316,18 @@ class DefaultContainer {
         return new BindingChain(token, this.#rebindRegistration());
     }
     #displacingRegistration;
-    /** A registration whose displaced binding is deactivated instead of parked, for `rebind`. */
+    /** A registration whose displaced binding is deactivated on the spot instead of kept for dispose, for `rebind`. */
     #rebindRegistration() {
         return (this.#displacingRegistration ??= {
             registry: this.#registry,
             scope: this.#scope,
             moduleBindingIds: undefined,
+            // One binding at a time, so the hot-swap rebind that owes nothing allocates nothing.
             deactivateDisplaced: (binding) => {
-                this.#deactivatePairsSync(this.#drainSingletons([binding]));
+                const pairs = this.#drainSingleton(binding, undefined);
+                if (pairs !== undefined) {
+                    this.#deactivatePairsSync(pairs);
+                }
             },
         });
     }
@@ -530,9 +533,10 @@ class DefaultContainer {
         this.#assertNotDisposed();
         this.#lifecycle.registerDeactivation(token, handler);
     }
-    // ── Resolution ─────────────────────────────────────────────────────────────────────────────────────────────────────
-    resolve(token, options) {
-        this.#assertNotDisposed();
+    static #rootResolve(token, options) {
+        if (this.#disposed) {
+            throw new DisposedContainerError();
+        }
         const rootStack = this.#resolver.rootStack;
         // A resolve already holding the shared stack means this one is nested; it mints its own.
         if (rootStack.length !== 0) {
@@ -545,8 +549,28 @@ class DefaultContainer {
         }
         return this.#resolver.resolve(token, options, rootStack);
     }
+    // The root's body again behind the child's check, so neither role's compiled resolve carries the other's path.
+    static #childResolve(token, options) {
+        this.#assertChainLive();
+        const rootStack = this.#resolver.rootStack;
+        if (rootStack.length !== 0) {
+            return options === undefined
+                ? this.#resolver.resolveFromContext(token, [])
+                : this.#resolver.resolve(token, options, []);
+        }
+        if (options === undefined) {
+            return this.#resolver.resolveFromContext(token, rootStack);
+        }
+        return this.#resolver.resolve(token, options, rootStack);
+    }
     resolveAsync(token, options) {
-        this.#assertNotDisposed();
+        // Not `async`: the guard's throw becomes the rejection this method promises.
+        try {
+            this.#assertNotDisposed();
+        }
+        catch (disposedError) {
+            return Promise.reject(disposedError);
+        }
         if (options === undefined) {
             return this.#resolver.resolveAsyncFromRoot(token);
         }
@@ -560,7 +584,12 @@ class DefaultContainer {
             : this.#resolver.resolveOptional(token, options, []);
     }
     resolveOptionalAsync(token, options) {
-        this.#assertNotDisposed();
+        try {
+            this.#assertNotDisposed();
+        }
+        catch (disposedError) {
+            return Promise.reject(disposedError);
+        }
         return this.#resolver.resolveOptionalAsync(token, options, [], ROOT_BRANCH);
     }
     resolveAll(token, options) {
@@ -574,7 +603,12 @@ class DefaultContainer {
             : this.#resolver.resolveAll(token, options, []);
     }
     resolveAllAsync(token, options) {
-        this.#assertNotDisposed();
+        try {
+            this.#assertNotDisposed();
+        }
+        catch (disposedError) {
+            return Promise.reject(disposedError);
+        }
         if (options === undefined) {
             return this.#resolver.resolveRootCollectionAsync(token);
         }
@@ -583,7 +617,10 @@ class DefaultContainer {
     // ── Child ──────────────────────────────────────────────────────────────────────────────────────────────────────────
     createChild() {
         this.#assertNotDisposed();
-        return new DefaultContainer(this);
+        const child = new DefaultContainer(this);
+        // Born confirmed live: the parent's chain was checked just above, so the child's first read skips the walk.
+        child.#liveGeneration = disposeEpochRef.value;
+        return child;
     }
     // ── Dispose ────────────────────────────────────────────────────────────────────────────────────────────────────────
     dispose() {
@@ -879,33 +916,39 @@ class DefaultContainer {
         this.#assertNotDisposed();
         return this.#getInspector().inspect();
     }
+    explain(token, options) {
+        this.#assertNotDisposed();
+        return explainRequest([this.#registry, ...this.#ancestorRegistries()], token, options);
+    }
     generateDependencyGraph(options) {
         this.#assertNotDisposed();
-        const ancestorRegistries = [];
+        return buildDependencyGraph(this.#registry, this.#getMetadataReader(), options, this.#ancestorRegistries());
+    }
+    /** The registries above this container, nearest first — the order every chain walk reads them in. */
+    #ancestorRegistries() {
+        const registries = [];
         for (let ancestor = this.#parent; ancestor !== undefined; ancestor = ancestor.#parent) {
-            ancestorRegistries.push(ancestor.#registry);
+            registries.push(ancestor.#registry);
         }
-        return buildDependencyGraph(this.#registry, this.#getMetadataReader(), options, ancestorRegistries);
+        return registries;
     }
     // ── Internal ───────────────────────────────────────────────────────────────────────────────────────────────────────
-    // Hot guard, one call-free epoch read and one compare for every container, root or child. Every
-    // dispose anywhere — self-dispose included, since `#runDispose` bumps the epoch — moves the epoch,
-    // so an epoch unchanged since we last confirmed the chain live means it is still live. A moved epoch
-    // drops to the cold refresh, which walks self and ancestors and either re-confirms or throws.
-    // Hot guard. A root's whole answer is its own `#disposed`, kept the one field read it always was —
-    // the epoch is never read on the root path. A child adds a call-free epoch compare: an unchanged
-    // epoch means no container anywhere has been disposed since we last confirmed the chain live, so the
-    // ancestors need no walk; a moved epoch drops to the cold refresh that walks them and re-confirms or throws.
+    // Two field reads and no epoch on a live root. This and `#assertChainLive` each stay under V8's small-function
+    // size, so every entry point inlines both outright; the walk and the throw sit in `#confirmChainLive`.
     #assertNotDisposed() {
-        if (this.#disposed) {
-            throw new DisposedContainerError();
+        if (this.#disposed || this.#parent !== undefined) {
+            this.#assertChainLive();
         }
-        if (this.#parent !== undefined && disposeEpochRef.value !== this.#liveGeneration) {
-            this.#refreshAncestors();
+    }
+    // An unchanged dispose epoch means no container anywhere closed since this chain was last confirmed live;
+    // every dispose advances it, this container's own included, so a disposed container always reaches the walk.
+    #assertChainLive() {
+        if (disposeEpochRef.value !== this.#liveGeneration) {
+            this.#confirmChainLive();
         }
     }
-    #refreshAncestors() {
-        if (this.#parent.#isChainDisposed()) {
+    #confirmChainLive() {
+        if (this.#isChainDisposed()) {
             throw new DisposedContainerError();
         }
         this.#liveGeneration = disposeEpochRef.value;

package/dist/core/binding-builders.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The fluent chain's contract: the slot steps `bind()` offers before `to*()`, and the builder each `to*()` returns.
+ */
+import type { BindingTag } from "#core/tag";
+import type { Token } from "#core/token";
+import type { ActivationHandler, BindingConstraint, BindingIdentifier, Constructor, DeactivationHandler, ResolutionContext } from "#core/types";
+import type { InjectableDependency, ResolvedDependencyValue } from "#injection/descriptor";
+/**
+ * The slot steps of the fluent chain, taken before `to*()` so the binding registers once, in its final shape.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface SlotConstrainedBuilder<Names extends string = string> {
+    /** Narrows the binding to requests the predicate accepts, evaluated on every resolve. */
+    when(predicate: BindingConstraint): this;
+    /** Declares the binding's slot name, one of the names the token declares. */
+    whenNamed(name: Names): this;
+    /** Declares one criterion of the binding's slot, replacing any earlier criterion of the same key. */
+    whenTagged(criterion: BindingTag): this;
+    /** Keeps the binding on the default slot, the one an unconstrained request selects. */
+    whenDefault(): this;
+    /**
+     * Makes the binding a collection member: one of several the token's `resolveAll` returns, never
+     * what a single `resolve` selects, and outside slot last-wins. It keeps the default slot.
+     */
+    many(): this;
+}
+/**
+ * The first step of the fluent chain: the slot, then the `to*` strategy that registers the binding.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface BindToBuilder<Value, Names extends string = string> extends SlotConstrainedBuilder<Names> {
+    to(type: Constructor<Value>): BindingBuilder<Value>;
+    toSelf(): BindingBuilder<Value>;
+    toConstantValue(value: Value): ConstantBindingBuilder<Value>;
+    toDynamic(factory: (ctx: ResolutionContext) => Value): BindingBuilder<Value>;
+    toDynamicAsync(factory: (ctx: ResolutionContext) => Promise<Value>): BindingBuilder<Value>;
+    toResolved<const Deps extends ReadonlyArray<InjectableDependency>>(factory: (...args: {
+        [K in keyof Deps]: ResolvedDependencyValue<NoInfer<Deps>[K]>;
+    }) => Value, deps: Deps): BindingBuilder<Value>;
+    toResolvedAsync<const Deps extends ReadonlyArray<InjectableDependency>>(factory: (...args: {
+        [K in keyof Deps]: ResolvedDependencyValue<NoInfer<Deps>[K]>;
+    }) => Promise<Value>, deps: Deps): BindingBuilder<Value>;
+    toAlias(target: Token<Value> | Constructor<Value>): AliasBindingBuilder;
+}
+/**
+ * The scope-selection step of the fluent chain, which the binding enters once registered.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface BindingBuilder<Value> {
+    singleton(): SingletonBindingBuilder<Value>;
+    transient(): TransientBindingBuilder<Value>;
+    scoped(): ScopedBindingBuilder<Value>;
+    /** The identifier this binding is registered under. */
+    id(): BindingIdentifier;
+}
+/**
+ * The fluent chain for a constant — lifecycle hooks only, since the scope is fixed.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface ConstantBindingBuilder<Value> {
+    onActivation(fn: ActivationHandler<Value>): SingletonLifecycleBuilder<Value>;
+    onDeactivation(fn: DeactivationHandler<Value>): SingletonLifecycleBuilder<Value>;
+    /** The identifier this binding is registered under. */
+    id(): BindingIdentifier;
+}
+/**
+ * The fluent chain for an alias — nothing to add, since scoping belongs to the target.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface AliasBindingBuilder {
+    /** The identifier this binding is registered under. */
+    id(): BindingIdentifier;
+}
+/**
+ * The fluent chain after `singleton()`, where both lifecycle hooks stay available.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface SingletonBindingBuilder<Value> {
+    onActivation(fn: ActivationHandler<Value>): this;
+    onDeactivation(fn: DeactivationHandler<Value>): this;
+    id(): BindingIdentifier;
+}
+/**
+ * The fluent chain after `transient()`, where activation is the one lifecycle hook offered.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface TransientBindingBuilder<Value> {
+    onActivation(fn: ActivationHandler<Value>): this;
+    id(): BindingIdentifier;
+}
+/**
+ * The fluent chain after `scoped()`, sharing the `transient()` surface.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface ScopedBindingBuilder<Value> extends TransientBindingBuilder<Value> {
+}
+/**
+ * The fluent chain a constant enters once a lifecycle hook is added.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface SingletonLifecycleBuilder<Value> {
+    onActivation(fn: ActivationHandler<Value>): this;
+    onDeactivation(fn: DeactivationHandler<Value>): this;
+    id(): BindingIdentifier;
+}

package/dist/core/binding-declaration.d.ts

@@ -114,7 +114,14 @@ export declare function asDeclaredBinding(entry: BindingDeclaration, moduleName:
  * @throws `InvalidBindingDeclarationError` for no strategy, several, or a key the strategy does not allow.
  * @throws `ManyBindingSlotError` for a slot on a collection member.
  * @throws `SelfBindingRequiresClassError` for `toSelf` on a key that is not a class.
+ *
+ * @since 0.11.0
  */
 export declare function binding<Value, Names extends string, const Deps extends ReadonlyArray<InjectableDependency> = []>(key: Token<Value, Names>, definition: BindingDefinition<NoInfer<Value>, NoInfer<Names>, Deps>): BindingDeclaration;
+/**
+ * Declares one binding keyed by a class, the one kind of key `toSelf` accepts.
+ *
+ * @since 0.11.0
+ */
 export declare function binding<Value, const Deps extends ReadonlyArray<InjectableDependency> = []>(key: Constructor<Value>, definition: BindingDefinition<NoInfer<Value>, string, Deps> | SelfDefinition<NoInfer<Value>>): BindingDeclaration;
 export {};

package/dist/core/binding-declaration.js

@@ -1,7 +1,7 @@
 import { DEFAULT_BINDING_SLOT, withSlotCriterion } from "#core/binding";
 import { slotName } from "#core/tag";
 import { tokenName } from "#core/token";
-import { InvalidBindingDeclarationError, ManyBindingSlotError, SelfBindingRequiresClassError } from "#errors/errors";
+import { InvalidBindingDeclarationError, ManyBindingSlotError, SelfBindingRequiresClassError } from "#errors";
 import { normalizeToDescriptor } from "#injection/descriptor";
 // Only this module can mint the symbol, so an entry carrying it was made by `binding()`.
 const declarationBrand = Symbol("di:binding-declaration");
@@ -83,8 +83,9 @@ function slotOf(definition) {
     }
     return slot;
 }
-// The value type is erased here, once: the overloads above are what a caller is checked against.
 /**
+ * Implements both overloads with the value type erased once, since a caller is checked against the overloads above.
+ *
  * @since 0.11.0
  */
 export function binding(key, definition) {