@codefast/di 0.11.0 → 0.13.0

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, 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 { SCOPED_MISS, 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,25 @@ 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);
+        }
+        const scopedInstance = this.#scope.takeScoped(binding.scopedCacheKey);
+        if (scopedInstance !== SCOPED_MISS) {
+            (pairs ??= []).push(binding, scopedInstance);
+        }
+        return pairs;
+    }
     /**
      * Whether a constant still owes its deactivation.
      *
@@ -246,10 +246,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 +265,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 +319,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 +536,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 +552,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 +587,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 +606,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 +620,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() {
@@ -600,6 +640,11 @@ class DefaultContainer {
         await this.#scope.settleInflight();
         const reader = this.#getMetadataReader();
         const errors = [];
+        // A scoped instance may hold this container's singletons and never the reverse, so it goes first, latest first.
+        const scopedTeardown = this.#scope.deactivateScoped(errors);
+        if (scopedTeardown !== undefined) {
+            await scopedTeardown;
+        }
         // Iterate a copy: a deactivation handler is user code, and the live list is what
         // materializing or dropping a singleton mutates. Reverse materialization order, so a
         // dependent tears down before the dependencies it may still reach through.
@@ -647,9 +692,6 @@ class DefaultContainer {
     [Symbol.asyncDispose]() {
         return this.dispose();
     }
-    [Symbol.dispose]() {
-        throw new SyncDisposalNotSupportedError();
-    }
     // ── Initialization ─────────────────────────────────────────────────────────────────────────────────────────────────
     async initializeAsync() {
         this.#assertNotDisposed();
@@ -692,8 +734,8 @@ class DefaultContainer {
             if (!this.#isBoundInChain(hookToken)) {
                 throw new UnreachableLifecycleHookError(tokenName(hookToken), phase);
             }
-            // A deactivation only ever runs for a singleton or constant, so a hook on a token whose every
-            // binding is scoped or transient can never fire — the builder blocks it, `container.onDeactivation` cannot.
+            // A deactivation never runs for a transient, so a hook on a token whose every binding is transient
+            // can never fire — the builder blocks it, `container.onDeactivation` cannot.
             if (phase === "onDeactivation" && !this.#hasDeactivatableBindingInChain(hookToken)) {
                 throw new UnreachableLifecycleHookError(tokenName(hookToken), phase, "no-deactivatable-binding");
             }
@@ -739,10 +781,10 @@ class DefaultContainer {
         const parent = this.#parent;
         return parent !== undefined && parent.#isBoundInChain(token);
     }
-    // Whether the token has a binding a deactivation hook can run for — a singleton or a constant.
+    // Whether the token has a binding a deactivation hook can run for — anything but a transient.
     #hasDeactivatableBindingInChain(token) {
         for (const binding of this.#registry.getAll(token)) {
-            if (effectiveBindingScope(binding) === "singleton") {
+            if (effectiveBindingScope(binding) !== "transient") {
                 return true;
             }
         }
@@ -756,22 +798,21 @@ class DefaultContainer {
         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.
+     * DFS over explicit constructor / `toResolved*` dependency edges, following `toAlias` chains to the terminal binding.
      *
-     * @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.
+     * @remarks Every binding reached is a singleton resolved from its owner's chain, so a required miss or a repeat
+     * on one path fails however the graph is entered; a `toDynamic*` edge is scope-checked, its factory not descended.
      */
     #validateSingletonBindingGraph(root, reader) {
         const rootName = tokenName(root.token);
-        const dfs = (current, pathNames, pathBindingIds) => {
+        const dfs = (current, view, pathNames, pathBindingIds) => {
             if (pathBindingIds.has(current.identifier)) {
-                return;
+                throw new CircularDependencyError(pathNames);
             }
             const extendedPathIds = new Set(pathBindingIds);
             extendedPathIds.add(current.identifier);
-            for (const edge of this.#collectStaticDependencyEdges(current, reader)) {
-                const { terminal, depTokenName } = edge;
+            for (const edge of this.#collectStaticDependencyEdges(current, view, reader, pathNames)) {
+                const { terminal, owner, depTokenName } = edge;
                 const depScope = this.#validationScopeFromTerminal(terminal);
                 if (depScope !== "singleton") {
                     throw new ScopeViolationError({
@@ -783,11 +824,11 @@ class DefaultContainer {
                     });
                 }
                 if (terminal.kind === "class" || terminal.kind === "resolved" || terminal.kind === "resolved-async") {
-                    dfs(terminal, [...pathNames, depTokenName], extendedPathIds);
+                    dfs(terminal, owner, [...pathNames, depTokenName], extendedPathIds);
                 }
             }
         };
-        dfs(root, [rootName], new Set());
+        dfs(root, this.#resolver, [rootName], new Set());
     }
     /**
      * The scope this edge is judged against.
@@ -802,32 +843,35 @@ class DefaultContainer {
         }
         return terminal.scope;
     }
-    #followAliasChainToTerminal(binding, options) {
+    /** Where an alias chain ends as `resolve` walks it from `view`: its terminal binding, or the names up to a miss. */
+    #followAliasChainToTerminal(entry, view, options) {
         const cyclePath = [];
         const seenAliasIds = new Set();
-        let current = binding;
-        while (current !== undefined && current.kind === "alias") {
-            if (seenAliasIds.has(current.identifier)) {
+        let current = entry;
+        while (current.binding.kind === "alias") {
+            const alias = current.binding;
+            if (seenAliasIds.has(alias.identifier)) {
                 throw new CircularDependencyError(cyclePath);
             }
-            seenAliasIds.add(current.identifier);
-            cyclePath.push(tokenName(current.token));
-            const nextToken = current.target;
-            const next = this.#resolver.peekBindingForValidate(nextToken, options);
+            seenAliasIds.add(alias.identifier);
+            cyclePath.push(tokenName(alias.token));
+            const next = view.peekBindingForValidate(alias.target, options);
             if (next === undefined) {
-                return undefined;
+                return { found: false, missingToken: alias.target, hopNames: cyclePath };
             }
-            current = next.binding;
+            current = next;
         }
-        return current;
+        return { found: true, terminal: current.binding, owner: current.owner };
     }
-    /** What one dependency could resolve to: every candidate for `injectAll`, else at most one. */
-    #peekDependencyCandidates(dep, options) {
+    /** What one dependency could resolve to from `view`: every candidate for `injectAll`, else at most one. */
+    #peekDependencyCandidates(dep, view, options) {
         if (dep.multi) {
-            return this.#resolver.peekCandidateBindingsForValidate(dep.token, options);
+            return view
+                .peekCandidateBindingsForValidate(dep.token, options)
+                .map((binding) => ({ binding, owner: view.ownerForValidate(binding) }));
         }
-        const found = this.#resolver.peekBindingForValidate(dep.token, options);
-        return found === undefined ? [] : [found.binding];
+        const found = view.peekBindingForValidate(dep.token, options);
+        return found === undefined ? [] : [found];
     }
     /** What a binding declares up front — a class's params, a factory's descriptors, else nothing. */
     #staticDependencies(binding, reader) {
@@ -839,15 +883,39 @@ class DefaultContainer {
         }
         return [];
     }
-    #collectStaticDependencyEdges(binding, reader) {
+    /**
+     * The bindings a singleton's declared dependencies resolve to, throwing the error `resolve` would for a required one
+     * nothing selects.
+     */
+    #collectStaticDependencyEdges(binding, view, reader, pathNames) {
         const edges = [];
         for (const dep of this.#staticDependencies(binding, reader)) {
             // An optional dependency that is absent peeks no candidate; one that is bound is captured like any other.
             const depOptions = injectionSlotToResolveOptions(dep);
-            for (const candidate of this.#peekDependencyCandidates(dep, depOptions)) {
-                const terminal = this.#followAliasChainToTerminal(candidate, depOptions);
-                if (terminal !== undefined) {
-                    edges.push({ terminal, depTokenName: tokenName(terminal.token) });
+            // A collection may be empty and an optional dependency absent, so only a required one can miss.
+            const required = !dep.multi && !dep.optional;
+            const candidates = this.#peekDependencyCandidates(dep, view, depOptions);
+            if (required && candidates.length === 0) {
+                const miss = view.missForValidate(dep.token, depOptions, [...pathNames, tokenName(dep.token)]);
+                if (miss !== undefined) {
+                    throw miss;
+                }
+            }
+            for (const candidate of candidates) {
+                const end = this.#followAliasChainToTerminal(candidate, view, depOptions);
+                if (end.found) {
+                    edges.push({ terminal: end.terminal, owner: end.owner, depTokenName: tokenName(end.terminal.token) });
+                    continue;
+                }
+                if (required) {
+                    const miss = view.missForValidate(end.missingToken, depOptions, [
+                        ...pathNames,
+                        ...end.hopNames,
+                        tokenName(end.missingToken),
+                    ]);
+                    if (miss !== undefined) {
+                        throw miss;
+                    }
                 }
             }
         }
@@ -879,33 +947,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,117 @@
+/**
+ * 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()`, where both lifecycle hooks stay available: a child deactivates what it cached.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface ScopedBindingBuilder<Value> {
+    onActivation(fn: ActivationHandler<Value>): this;
+    onDeactivation(fn: DeactivationHandler<Value>): this;
+    id(): BindingIdentifier;
+}
+/**
+ * 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

@@ -23,11 +23,11 @@ type SlotDefinition<Names extends string> = ({
 } & Never<"whenNamed" | "whenTagged">);
 /** How long an instance lives, and the hooks that lifetime allows. */
 type LifetimeDefinition<Value> = {
-    readonly scope: "singleton";
+    readonly scope: "singleton" | "scoped";
     readonly onActivation?: ActivationHandler<Value> | undefined;
     readonly onDeactivation?: DeactivationHandler<Value> | undefined;
 } | ({
-    readonly scope?: "transient" | "scoped" | undefined;
+    readonly scope?: "transient" | undefined;
     readonly onActivation?: ActivationHandler<Value> | undefined;
 } & Never<"onDeactivation">);
 type BuiltDefinition<Value, Deps extends ReadonlyArray<InjectableDependency>> = ({
@@ -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 {};