@codefast/di 0.10.1 → 0.12.0

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

@@ -3,16 +3,18 @@
  *
  * @remarks One object plays every role: each builder step, the record the registry stores, and the
  * binding the resolver reads. The binding fields are declared first and in a fixed order, so every
- * binding in the process shares one hidden class; the return type of each step is what pins the
- * chain's order, so no runtime check has to.
+ * binding in the process shares one hidden class; the return type of each step pins the chain's
+ * order, slot before strategy, so the binding registers once and is never re-slotted.
  */
-import type { AliasBindingBuilder, BindingBuilder, BindingSlot, BindToBuilder, ConstantBindingBuilder, ScopedBindingBuilder, SingletonBindingBuilder, SingletonLifecycleBuilder, TransientBindingBuilder } from "#core/binding";
+import type { Binding, BindingSlot } from "#core/binding";
+import type { AliasBindingBuilder, BindingBuilder, BindToBuilder, ConstantBindingBuilder, ScopedBindingBuilder, SingletonBindingBuilder, SingletonLifecycleBuilder, TransientBindingBuilder } from "#core/binding-builders";
+import type { DeclaredBinding } from "#core/binding-declaration";
 import type { BindingRegistry } from "#core/registry";
 import type { BindingTag } from "#core/tag";
 import type { Token } from "#core/token";
 import type { ActivationHandler, BindingConstraint, BindingIdentifier, BindingKind, BindingScope, Constructor, DeactivationHandler, ResolutionContext, ResolutionFrame } from "#core/types";
 import type { InjectableDependency, InjectionDescriptor, ResolvedDependencyValue } from "#injection/descriptor";
-import type { ScopeManager } from "#lifecycle/scope-manager";
+import type { ScopeManager } from "#lifecycle/scopes";
 /**
  * Where a chain registers, and on whose behalf.
  *
@@ -25,24 +27,31 @@ export interface BindingRegistration {
     readonly registry: BindingRegistry;
     readonly scope: ScopeManager;
     readonly moduleBindingIds: Array<BindingIdentifier> | undefined;
+    /** Runs for a binding this registration displaces, deactivating it on the spot. */
+    readonly deactivateDisplaced?: ((binding: Binding) => void) | undefined;
+    /** Notes a displaced binding so the container can still tear it down, when nothing deactivates it on the spot. */
+    readonly onDisplaced?: ((binding: Binding) => void) | undefined;
 }
 /**
  * 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
  */
-export declare class BindingChain<Value, Names extends string = string> implements AliasBindingBuilder<Names>, BindingBuilder<Value, Names>, BindToBuilder<Value, Names>, ConstantBindingBuilder<Value, Names>, ScopedBindingBuilder<Value>, SingletonBindingBuilder<Value>, SingletonLifecycleBuilder<Value>, TransientBindingBuilder<Value> {
+export declare class BindingChain<Value, Names extends string = string> implements AliasBindingBuilder, BindingBuilder<Value>, BindToBuilder<Value, Names>, ConstantBindingBuilder<Value>, ScopedBindingBuilder<Value>, SingletonBindingBuilder<Value>, SingletonLifecycleBuilder<Value>, TransientBindingBuilder<Value> {
     #private;
     kind: BindingKind;
     readonly identifier: BindingIdentifier;
     inFlight: boolean;
     frame: ResolutionFrame | undefined;
+    rootContext: ResolutionContext | undefined;
+    activationStamp: number;
     instance: unknown;
+    scopedCacheKey: BindingIdentifier;
     readonly token: Token<Value, Names> | Constructor<Value>;
     slot: BindingSlot;
     predicate: BindingConstraint | undefined;
@@ -55,18 +64,20 @@ export declare class BindingChain<Value, Names extends string = string> implemen
     activationHook: ActivationHandler<Value> | undefined;
     deactivationHook: DeactivationHandler<Value> | undefined;
     constructor(token: Token<Value, Names> | Constructor<Value>, registration: BindingRegistration);
-    to(type: Constructor<Value>): BindingBuilder<Value, Names>;
-    toSelf(): BindingBuilder<Value, Names>;
-    toConstantValue(value: Value): ConstantBindingBuilder<Value, Names>;
-    toDynamic(factory: (ctx: ResolutionContext) => Value): BindingBuilder<Value, Names>;
-    toDynamicAsync(factory: (ctx: ResolutionContext) => Promise<Value>): BindingBuilder<Value, Names>;
+    /** Registers a declared module's bindings in list order, each a chain of its own, handled as `to*()` handles one. */
+    static registerDeclared(declarations: ReadonlyArray<DeclaredBinding>, registration: BindingRegistration): void;
+    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, Names>;
+    }) => 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, Names>;
-    toAlias(target: Token<Value> | Constructor<Value>): AliasBindingBuilder<Names>;
+    }) => Promise<Value>, deps: Deps): BindingBuilder<Value>;
+    toAlias(target: Token<Value> | Constructor<Value>): AliasBindingBuilder;
     when(predicate: BindingConstraint): this;
     whenNamed(name: Names): this;
     whenTagged(criterion: BindingTag): this;

package/dist/container/binding-chain.js

@@ -0,0 +1,254 @@
+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";
+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 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
+ */
+export class BindingChain {
+    // The binding. Every field, every kind, written in this order and nowhere else: one hidden class.
+    kind = "constant";
+    identifier = generateBindingId();
+    inFlight = false;
+    frame = undefined;
+    rootContext = undefined;
+    activationStamp = NO_ACTIVATION_STAMP;
+    instance = NO_INSTANCE;
+    scopedCacheKey = this.identifier;
+    token;
+    slot = DEFAULT_BINDING_SLOT;
+    predicate = undefined;
+    isMany = false;
+    scope = "singleton";
+    target = undefined;
+    factory = undefined;
+    deps = undefined;
+    value = undefined;
+    activationHook = undefined;
+    deactivationHook = undefined;
+    // The chain. Set by the first `to*()`, which is the only one a chain accepts.
+    #isRegistered = false;
+    #registration;
+    constructor(token, registration) {
+        this.token = token;
+        this.#registration = registration;
+    }
+    /** This object as the registry and the resolver see it: the value type erased once, here. */
+    get #binding() {
+        return this;
+    }
+    /** 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 slot step or a second `to*()` once registered, raised before a field is overwritten. */
+    #requireUnregistered() {
+        if (this.#isRegistered) {
+            throw new ChainAlreadyRegisteredError(tokenName(this.token));
+        }
+    }
+    #register(kind, scope) {
+        this.kind = kind;
+        this.scope = scope;
+        this.#isRegistered = true;
+        const registration = this.#registration;
+        const displaced = registration.registry.add(this.#binding);
+        if (displaced !== undefined) {
+            if (registration.deactivateDisplaced !== undefined) {
+                registration.deactivateDisplaced(displaced);
+            }
+            else {
+                registration.onDisplaced?.(displaced);
+            }
+        }
+        if (registration.moduleBindingIds !== undefined) {
+            registration.moduleBindingIds.push(this.identifier);
+        }
+        return this;
+    }
+    /** 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) {
+            const declaration = declarations[index];
+            const binding = BindingChain.#fromDeclaration(declaration, registration);
+            const displaced = registry.add(binding);
+            if (displaced !== undefined) {
+                if (deactivateDisplaced === undefined) {
+                    onDisplaced?.(displaced);
+                }
+                else {
+                    deactivateDisplaced(displaced);
+                }
+            }
+            moduleBindingIds?.push(binding.identifier);
+        }
+    }
+    /**
+     * A registered chain in the shape a declaration's steps would have left.
+     *
+     * @remarks Typed `unknown` like the declaration it copies, so the value type is never asserted here.
+     */
+    static #fromDeclaration(declaration, registration) {
+        const chain = new BindingChain(declaration.token, registration);
+        chain.kind = declaration.kind;
+        chain.slot = declaration.slot;
+        chain.predicate = declaration.predicate;
+        chain.isMany = declaration.isMany;
+        chain.scope = declaration.scope;
+        chain.target = declaration.target;
+        chain.factory = declaration.factory;
+        chain.deps = declaration.deps;
+        chain.value = declaration.value;
+        chain.activationHook = declaration.activationHook;
+        chain.deactivationHook = declaration.deactivationHook;
+        chain.#isRegistered = true;
+        return chain.#binding;
+    }
+    // ── Registration ───────────────────────────────────────────────────────────────────────────────────────────────────
+    to(type) {
+        this.#requireUnregistered();
+        this.target = type;
+        return this.#register("class", "transient");
+    }
+    toSelf() {
+        this.#requireUnregistered();
+        if (typeof this.token !== "function") {
+            throw new SelfBindingRequiresClassError(tokenName(this.token));
+        }
+        this.target = this.token;
+        return this.#register("class", "transient");
+    }
+    toConstantValue(value) {
+        this.#requireUnregistered();
+        this.value = value;
+        return this.#register("constant", "singleton");
+    }
+    toDynamic(factory) {
+        this.#requireUnregistered();
+        this.factory = factory;
+        return this.#register("dynamic", "transient");
+    }
+    toDynamicAsync(factory) {
+        this.#requireUnregistered();
+        this.factory = factory;
+        return this.#register("dynamic-async", "transient");
+    }
+    toResolved(factory, deps) {
+        this.#requireUnregistered();
+        this.factory = factory;
+        this.deps = deps.map((dependency) => normalizeToDescriptor(dependency));
+        return this.#register("resolved", "transient");
+    }
+    toResolvedAsync(factory, deps) {
+        this.#requireUnregistered();
+        this.factory = factory;
+        this.deps = deps.map((dependency) => normalizeToDescriptor(dependency));
+        return this.#register("resolved-async", "transient");
+    }
+    toAlias(target) {
+        this.#requireUnregistered();
+        this.target = target;
+        return this.#register("alias", "transient");
+    }
+    // ── 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.#requireUnregistered();
+        const previous = this.predicate;
+        // The composite carries both sides' requirements, so validate() still sees them.
+        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.#requireUnregistered();
+        if (this.isMany) {
+            throw new ManyBindingSlotError(tokenName(this.token));
+        }
+        this.slot = withSlotCriterion(this.slot, criterion);
+        return this;
+    }
+    many() {
+        this.#requireUnregistered();
+        if (this.slot.tags.length !== 0) {
+            throw new ManyBindingSlotError(tokenName(this.token));
+        }
+        this.isMany = true;
+        return this;
+    }
+    whenDefault() {
+        // 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() {
+        return this.#withScope("singleton");
+    }
+    transient() {
+        return this.#withScope("transient");
+    }
+    scoped() {
+        return this.#withScope("scoped");
+    }
+    onActivation(fn) {
+        this.#requireRegistered();
+        this.activationHook = fn;
+        this.#registration.registry.touch();
+        return this;
+    }
+    onDeactivation(fn) {
+        this.#requireRegistered();
+        this.deactivationHook = fn;
+        this.#registration.registry.touch();
+        return this;
+    }
+    id() {
+        this.#requireRegistered();
+        return this.identifier;
+    }
+}

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;
 }
 /**