@codefast/di 0.11.0 → 0.13.0

package/dist/container/{binding-builders.js → binding-chain.js}

@@ -1,17 +1,17 @@
-import { clearBindingFrame, NO_ACTIVATION_STAMP, DEFAULT_BINDING_SLOT, generateBindingId, NO_INSTANCE, UNREGISTERED_ORDER, withSlotCriterion, } from "#core/binding";
+import { clearBindingFrame, NO_ACTIVATION_STAMP, DEFAULT_BINDING_SLOT, generateBindingId, NO_INSTANCE, withSlotCriterion, } from "#core/binding";
 import { mergingConstraintRequirements } from "#core/constraint-requirement";
 import { slotName } from "#core/tag";
 import { tokenName } from "#core/token";
-import { ChainAlreadyRegisteredError, ChainNotRegisteredError, ManyBindingSlotError, SelfBindingRequiresClassError, } from "#errors/errors";
+import { ChainAlreadyRegisteredError, ChainNotRegisteredError, ManyBindingSlotError, SelfBindingRequiresClassError, } from "#errors";
 import { normalizeToDescriptor } from "#injection/descriptor";
 // ── BindingChain ─────────────────────────────────────────────────────────────────────────────────────────────────────
 /**
  * The one builder behind `bind()` and every `to*()` return type — and the binding it registers.
  *
  * @remarks The binding fields come first, in the order every binding shares, and the chain's own
- * bookkeeping follows as private fields; `to*()` fills the fields in place and hands this object to
- * the registry, so a plain bind is one allocation. Refinements write the registered object: a scope
- * or hook in place, a slot or predicate through the registry so its indexes follow.
+ * bookkeeping follows as a private field. The slot steps write the fields before anything registers;
+ * `to*()` fills the strategy in place and hands this object to the registry once, so a bind is one
+ * allocation and one add. A scope or hook afterwards writes the registered object in place.
  *
  * @since 0.5.0-canary.8
  */
@@ -23,8 +23,8 @@ export class BindingChain {
     frame = undefined;
     rootContext = undefined;
     activationStamp = NO_ACTIVATION_STAMP;
-    registrationOrder = UNREGISTERED_ORDER;
     instance = NO_INSTANCE;
+    scopedCacheKey = this.identifier;
     token;
     slot = DEFAULT_BINDING_SLOT;
     predicate = undefined;
@@ -38,10 +38,6 @@ export class BindingChain {
     deactivationHook = undefined;
     // The chain. Set by the first `to*()`, which is the only one a chain accepts.
     #isRegistered = false;
-    // Allocated only by a chain that actually displaces something — most never do.
-    #displacedByChain;
-    // Registry version after this chain's last write — a mismatch means someone else wrote in between.
-    #versionAfterLastWrite = -1;
     #registration;
     constructor(token, registration) {
         this.token = token;
@@ -51,13 +47,13 @@ export class BindingChain {
     get #binding() {
         return this;
     }
-    /** Loud failure for a refinement before `to*()`. */
+    /** Loud failure for a scope, a hook or `id()` before `to*()`. */
     #requireRegistered() {
         if (!this.#isRegistered) {
             throw new ChainNotRegisteredError(tokenName(this.token));
         }
     }
-    /** Loud failure for a second `to*()`, raised before the first one's fields can be overwritten. */
+    /** Loud failure for a slot step or a second `to*()` once registered, raised before a field is overwritten. */
     #requireUnregistered() {
         if (this.#isRegistered) {
             throw new ChainAlreadyRegisteredError(tokenName(this.token));
@@ -67,32 +63,22 @@ export class BindingChain {
         this.kind = kind;
         this.scope = scope;
         this.#isRegistered = true;
-        // A fresh registration parks nothing yet and restores nothing: one add, then the version.
         const registration = this.#registration;
-        const registry = registration.registry;
-        const displaced = registry.add(this.#binding);
+        const displaced = registration.registry.add(this.#binding);
         if (displaced !== undefined) {
             if (registration.deactivateDisplaced !== undefined) {
                 registration.deactivateDisplaced(displaced);
             }
             else {
-                this.#displacedByChain = [displaced];
                 registration.onDisplaced?.(displaced);
             }
         }
         if (registration.moduleBindingIds !== undefined) {
             registration.moduleBindingIds.push(this.identifier);
         }
-        this.#versionAfterLastWrite = registry.version;
         return this;
     }
-    /**
-     * Registers a declared module's bindings in list order, each a chain of its own that no step
-     * will ever refine.
-     *
-     * @remarks A displaced binding is handled as `to*()` handles it, never parked: nothing refines the
-     * chain, so nothing could restore it.
-     */
+    /** Registers a declared module's bindings in list order, each a chain of its own, handled as `to*()` handles one. */
     static registerDeclared(declarations, registration) {
         const { registry, moduleBindingIds, deactivateDisplaced, onDisplaced } = registration;
         for (let index = 0; index < declarations.length; index += 1) {
@@ -177,102 +163,67 @@ export class BindingChain {
         this.target = target;
         return this.#register("alias", "transient");
     }
-    // ── Refinement ─────────────────────────────────────────────────────────────────────────────────────────────────────
-    /**
-     * Whether this chain provably still owns the registry's last write with nothing parked.
-     *
-     * @remarks When it does, a refinement rewrites the live binding in place; otherwise `#reslot`
-     * re-checks liveness and restores what the new shape frees.
-     */
-    get #isProvablyLive() {
-        return this.#registration.registry.version === this.#versionAfterLastWrite && this.#displacedByChain === undefined;
-    }
-    /** Stamps this chain's last-write version after a mutation it made in place. */
-    #recordWrite() {
-        this.#versionAfterLastWrite = this.#registration.registry.version;
-    }
-    /** Bumps the registry for an index-neutral mutation (scope, hook) and records this chain's write. */
-    #touchAndRecordWrite() {
-        this.#registration.registry.touch();
-        this.#recordWrite();
-    }
-    // Slot and predicate are what the registry indexes on, so a re-slot takes the binding out of the
-    // registry, rewrites the two fields while it is out, and registers it again — same object, same id.
-    #reslot(slot, predicate) {
-        this.#requireRegistered();
-        this.#commit(() => {
-            this.slot = slot;
-            this.predicate = predicate;
-            // The frame reports the slot, so a resolve before this call memoized the previous one.
-            clearBindingFrame(this.#binding);
-        });
-        return this;
-    }
-    #withScope(scope) {
-        this.#requireRegistered();
-        if (this.scope !== scope) {
-            // An instance cached under the old scope must not survive the change — a later flip back
-            // to that scope would resurrect it.
-            this.#registration.scope.deleteSingleton(this.#binding);
-            this.#registration.scope.deleteScoped(this.identifier);
-            this.scope = scope;
-        }
-        // The frame reports the scope, so a resolve before this call memoized the previous one.
-        clearBindingFrame(this.#binding);
-        this.#touchAndRecordWrite();
-        return this;
-    }
-    // SPEC calls a candidate a binding that passes *all* of a chain's predicates, and the chain type
-    // reads as refinement, so a second `when()` narrows rather than replaces.
+    // ── Slot ───────────────────────────────────────────────────────────────────────────────────────────────────────────
+    // SPEC calls a candidate a binding that passes *all* of a chain's predicates, so a second `when()`
+    // narrows rather than replaces.
     when(predicate) {
-        this.#requireRegistered();
+        this.#requireUnregistered();
         const previous = this.predicate;
         // The composite carries both sides' requirements, so validate() still sees them.
-        const narrowed = previous === undefined
-            ? predicate
-            : mergingConstraintRequirements((ctx) => previous(ctx) && predicate(ctx), previous, predicate);
-        // The slot is unchanged, so a provably-live binding just takes the predicate in place.
-        if (this.#isProvablyLive) {
-            this.#registration.registry.setPredicate(this.#binding, narrowed);
-            this.#recordWrite();
-            return this;
-        }
-        return this.#reslot(this.slot, narrowed);
+        this.predicate =
+            previous === undefined
+                ? predicate
+                : mergingConstraintRequirements((ctx) => previous(ctx) && predicate(ctx), previous, predicate);
+        return this;
     }
     whenNamed(name) {
         return this.whenTagged(slotName.of(name));
     }
     whenTagged(criterion) {
-        this.#requireRegistered();
+        this.#requireUnregistered();
         if (this.isMany) {
             throw new ManyBindingSlotError(tokenName(this.token));
         }
-        return this.#reslot(withSlotCriterion(this.slot, criterion), this.predicate);
+        this.slot = withSlotCriterion(this.slot, criterion);
+        return this;
     }
     many() {
-        this.#requireRegistered();
+        this.#requireUnregistered();
         if (this.slot.tags.length !== 0) {
             throw new ManyBindingSlotError(tokenName(this.token));
         }
-        if (this.isMany) {
-            return this;
-        }
-        // A provably-live binding takes membership in place; the registry only moves it out of the lone
-        // map. Otherwise `#commit` re-checks liveness and restores what the freed slot lets back in.
-        if (this.#isProvablyLive) {
-            this.#registration.registry.setMany(this.#binding);
-            this.#recordWrite();
-            return this;
-        }
-        this.#commit(() => {
-            this.isMany = true;
-        });
+        this.isMany = true;
         return this;
     }
     whenDefault() {
-        // The default slot is what a fresh registration already has, so there is nothing to re-slot —
-        // but an unregistered chain must fail here exactly as it does in every other refinement.
+        // The default slot is what a fresh chain already has; the check keeps it a slot step like the others.
+        this.#requireUnregistered();
+        return this;
+    }
+    // ── Scope and lifecycle ────────────────────────────────────────────────────────────────────────────────────────────
+    #withScope(scope) {
         this.#requireRegistered();
+        // Nothing a cache, a frame or the version answers for depends on a scope that did not change.
+        if (this.scope === scope) {
+            return this;
+        }
+        // An instance cached under the old scope must not survive the change — a later flip back to that
+        // scope would resurrect it. A child's scoped cache is out of reach here, so leaving `scoped` retires
+        // the key every child filed its instance under.
+        const registration = this.#registration;
+        if (this.instance !== NO_INSTANCE) {
+            registration.scope.deleteSingleton(this.#binding);
+        }
+        if (this.scope === "scoped") {
+            registration.scope.deleteScoped(this.scopedCacheKey);
+            this.scopedCacheKey = generateBindingId();
+        }
+        this.scope = scope;
+        // The frame reports the scope, so a resolve before this call memoized the previous one.
+        if (this.frame !== undefined || this.rootContext !== undefined) {
+            clearBindingFrame(this.#binding);
+        }
+        registration.registry.touch();
         return this;
     }
     singleton() {
@@ -287,78 +238,17 @@ export class BindingChain {
     onActivation(fn) {
         this.#requireRegistered();
         this.activationHook = fn;
-        this.#touchAndRecordWrite();
+        this.#registration.registry.touch();
         return this;
     }
     onDeactivation(fn) {
         this.#requireRegistered();
         this.deactivationHook = fn;
-        this.#touchAndRecordWrite();
+        this.#registration.registry.touch();
         return this;
     }
     id() {
         this.#requireRegistered();
         return this.identifier;
     }
-    // ── Registry ───────────────────────────────────────────────────────────────────────────────────────────────────────
-    /**
-     * Registers this binding; with `rewrite` given, first takes the live binding out, rewrites it, and
-     * registers it again.
-     *
-     * @remarks A `when*()` that follows `to*()` re-slots an already-live binding and can displace one
-     * the final shape would never conflict with. Those stay parked in `#displacedByChain` until the
-     * chain settles, then get restored.
-     */
-    #commit(rewrite) {
-        const { registry, moduleBindingIds } = this.#registration;
-        const registered = this.#binding;
-        if (rewrite !== undefined) {
-            // A registry someone else wrote since this chain's last write invalidates the parked
-            // snapshot: restoring it could undo an unbind or shadow a newer binding.
-            if (registry.version !== this.#versionAfterLastWrite) {
-                this.#displacedByChain = undefined;
-            }
-            if (!registry.reslot(registered, rewrite)) {
-                // The chain's binding is no longer live (unbound or displaced) — a refinement must not
-                // resurrect it, so the chain goes inert against the registry.
-                this.#displacedByChain = undefined;
-                this.#versionAfterLastWrite = registry.version;
-                return;
-            }
-        }
-        else {
-            // Each `to*()` starts its own registration, so anything a previous one displaced is not this
-            // registration's to restore.
-            this.#displacedByChain = undefined;
-        }
-        const displaced = registry.add(registered);
-        if (displaced !== undefined) {
-            if (this.#registration.deactivateDisplaced !== undefined && rewrite === undefined) {
-                this.#registration.deactivateDisplaced(displaced);
-            }
-            else {
-                (this.#displacedByChain ??= []).push(displaced);
-                this.#registration.onDisplaced?.(displaced);
-            }
-        }
-        if (rewrite !== undefined && this.#displacedByChain !== undefined) {
-            this.#restoreNonConflicting(this.#displacedByChain);
-        }
-        if (rewrite === undefined && moduleBindingIds !== undefined) {
-            moduleBindingIds.push(this.identifier);
-        }
-        this.#versionAfterLastWrite = registry.version;
-    }
-    #restoreNonConflicting(displaced) {
-        for (let index = displaced.length - 1; index >= 0; index -= 1) {
-            const candidate = displaced[index];
-            // A restore must never displace: a slot that has been re-occupied keeps its occupant, and
-            // the candidate stays parked.
-            if (!this.#registration.registry.hasSlotOccupant(candidate)) {
-                this.#registration.registry.add(candidate);
-                this.#registration.onRestored?.(candidate);
-                displaced.splice(index, 1);
-            }
-        }
-    }
 }

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.
  *
@@ -35,13 +36,20 @@ export interface Container {
     createChild(): Container;
     dispose(): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
-    [Symbol.dispose](): never;
     initializeAsync(): Promise<void>;
     validate(): void;
     has<Names extends string = string>(token: Token<unknown, Names> | Constructor, options?: NoInfer<ResolveOptions<Names>>): boolean;
     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;
 }
 /**