@codefast/di 0.11.0 → 0.13.0

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) {
@@ -156,8 +157,8 @@ export function binding(key, definition) {
     if (kind === "alias" && (onActivation !== undefined || onDeactivation !== undefined)) {
         throw new InvalidBindingDeclarationError(name, "`toAlias` takes no lifecycle hook");
     }
-    if (onDeactivation !== undefined && kind !== "constant" && scope !== "singleton") {
-        throw new InvalidBindingDeclarationError(name, '`onDeactivation` needs `scope: "singleton"`');
+    if (onDeactivation !== undefined && kind !== "constant" && scope === "transient") {
+        throw new InvalidBindingDeclarationError(name, '`onDeactivation` needs `scope: "singleton"` or `scope: "scoped"`');
     }
     if (definition.many !== undefined && definition.many !== true) {
         throw new InvalidBindingDeclarationError(name, "`many` takes `true`");

package/dist/core/binding.d.ts

@@ -1,7 +1,7 @@
 import type { BindingTag, TagKeyMask } from "#core/tag";
 import type { Token } from "#core/token";
-import type { ActivationHandler, BindingIdentifier, BindingScope, Constructor, DeactivationHandler, ResolutionContext, ResolutionFrame, BindingConstraint } from "#core/types";
-import type { InjectableDependency, InjectionDescriptor, ResolvedDependencyValue } from "#injection/descriptor";
+import type { BindingConstraint, BindingIdentifier, BindingScope, Constructor, ResolutionContext, ResolutionFrame } from "#core/types";
+import type { InjectionDescriptor } from "#injection/descriptor";
 /**
  * The criterion set a binding registers under and a request matches against.
  *
@@ -106,13 +106,6 @@ interface BindingBase<Value> {
      * container resolving each binding once would build and never read again.
      */
     activationStamp: number;
-    /**
-     * Where the binding stands in registration order, or {@link UNREGISTERED_ORDER} before its first add.
-     *
-     * @remarks Registry-owned: stamped by the first `add` and kept through every re-slot and restore, so a
-     * binding taken out and put back returns to its place rather than behind later registrations.
-     */
-    registrationOrder: number;
     /**
      * Cached singleton instance, or {@link NO_INSTANCE}.
      *
@@ -120,6 +113,13 @@ interface BindingBase<Value> {
      * a field read replaces a keyed lookup on the hottest resolve shape there is.
      */
     instance: unknown;
+    /**
+     * The key every container's scoped cache files this binding's instance under.
+     *
+     * @remarks Chain-owned. It starts as the binding's id, and a scope verb that changes the scope mints a new one, so
+     * a scoped instance any child cached under an earlier scope is never found again. The id itself stays stable.
+     */
+    scopedCacheKey: BindingIdentifier;
     readonly token: Token<Value> | Constructor<Value>;
     readonly slot: BindingSlot;
     readonly predicate?: BindingConstraint | undefined;
@@ -228,40 +228,21 @@ export interface AliasBinding<Value> extends BindingBase<Value> {
  */
 export type Binding<Value = unknown> = ClassBinding<Value> | DynamicBinding<Value> | DynamicAsyncBinding<Value> | ResolvedBinding<Value> | ResolvedAsyncBinding<Value> | ConstantBinding<Value> | AliasBinding<Value>;
 /**
- * Returns a process-unique identifier for a new binding.
+ * The scope a binding resolves under.
  *
- * @since 0.3.16-canary.0
- */
-export declare function generateBindingId(): BindingIdentifier;
-/**
- * Writable view of the one selection field a chain may refine without re-registering: nothing
- * indexes on the predicate, so the registry rewrites it in place and re-homes the binding itself.
- *
- * @since 0.10.0
- */
-export interface PredicateField {
-    predicate: BindingConstraint | undefined;
-}
-/**
- * Narrows a registered binding to its predicate for the registry to rewrite.
+ * @remarks Every kind declares one — an alias declares `transient`, since it defers scoping to the
+ * binding it points at — so this is a field read, kept as a named function because it is the
+ * vocabulary validation and introspection speak.
  *
- * @since 0.10.0
+ * @since 0.3.16-canary.0
  */
-export declare function writablePredicate(binding: Binding): PredicateField;
+export declare function effectiveBindingScope(binding: Binding): BindingScope;
 /**
- * Writable view of collection membership, which the registry sets because it decides the binding's map.
- *
- * @since 0.10.0
- */
-export interface MembershipField {
-    isMany: boolean;
-}
-/**
- * Narrows a registered binding to its membership flag for the registry to set.
+ * Returns a process-unique identifier for a new binding.
  *
- * @since 0.10.0
+ * @since 0.3.16-canary.0
  */
-export declare function writableMembership(binding: Binding): MembershipField;
+export declare function generateBindingId(): BindingIdentifier;
 /**
  * The stamp of a binding whose activation need has not been computed under the current versions.
  *
@@ -269,121 +250,12 @@ export declare function writableMembership(binding: Binding): MembershipField;
  */
 export declare const NO_ACTIVATION_STAMP = -1;
 /**
- * The registration order of a binding no registry has added yet.
+ * Drops the memoized resolution frame, for a scope change that alters what the frame reports.
  *
- * @since 0.11.0
- */
-export declare const UNREGISTERED_ORDER = -1;
-/**
- * Drops the memoized resolution frame, for a refinement that changes what the frame reports.
- *
- * @remarks The frame derives from `scope` and `slot`, both of which a chain now writes in place on
- * the registered object, so every such refinement clears it.
+ * @remarks The frame derives from `scope` and `slot`; the slot is final once the binding registers, so
+ * only a scope written in place on the registered object clears it.
  *
  * @since 0.5.0-canary.9
  */
 export declare function clearBindingFrame<Value>(binding: Binding<Value>): void;
-/**
- * Common slot-constraint + id methods shared by all concrete binding builders.
- *
- * @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 identifier this binding is registered under. */
-    id(): BindingIdentifier;
-}
-/**
- * The `to*` step of the fluent chain, choosing what a token resolves to.
- *
- * @since 0.3.16-canary.0
- */
-export interface BindToBuilder<Value, Names extends string = string> {
-    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>;
-    toResolved<const Deps extends ReadonlyArray<InjectableDependency>>(factory: (...args: {
-        [K in keyof Deps]: ResolvedDependencyValue<NoInfer<Deps>[K]>;
-    }) => Value, deps: Deps): BindingBuilder<Value, Names>;
-    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>;
-}
-/**
- * The scope-selection step of the fluent chain.
- *
- * @since 0.3.16-canary.0
- */
-export interface BindingBuilder<Value, Names extends string = string> extends SlotConstrainedBuilder<Names> {
-    singleton(): SingletonBindingBuilder<Value>;
-    transient(): TransientBindingBuilder<Value>;
-    scoped(): ScopedBindingBuilder<Value>;
-}
-/**
- * The fluent chain for a constant — lifecycle hooks only, since the scope is fixed.
- *
- * @since 0.3.16-canary.0
- */
-export interface ConstantBindingBuilder<Value, Names extends string = string> extends SlotConstrainedBuilder<Names> {
-    onActivation(fn: ActivationHandler<Value>): SingletonLifecycleBuilder<Value>;
-    onDeactivation(fn: DeactivationHandler<Value>): SingletonLifecycleBuilder<Value>;
-}
-/**
- * The fluent chain for an alias — slot constraints only, since scoping belongs to the target.
- *
- * @since 0.3.16-canary.0
- */
-export interface AliasBindingBuilder<Names extends string = string> extends SlotConstrainedBuilder<Names> {
-}
-/**
- * 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;
-}
 export {};

package/dist/core/binding.js

@@ -108,6 +108,18 @@ export function bindingSlotToString(slot) {
     }
     return parts.join(",");
 }
+/**
+ * The scope a binding resolves under.
+ *
+ * @remarks Every kind declares one — an alias declares `transient`, since it defers scoping to the
+ * binding it points at — so this is a field read, kept as a named function because it is the
+ * vocabulary validation and introspection speak.
+ *
+ * @since 0.3.16-canary.0
+ */
+export function effectiveBindingScope(binding) {
+    return binding.scope;
+}
 // ── ID generation ────────────────────────────────────────────────────────────────────────────────────────────────────
 let bindingIdCounter = 0;
 /**
@@ -119,22 +131,6 @@ export function generateBindingId() {
     bindingIdCounter += 1;
     return bindingIdCounter;
 }
-/**
- * Narrows a registered binding to its predicate for the registry to rewrite.
- *
- * @since 0.10.0
- */
-export function writablePredicate(binding) {
-    return binding;
-}
-/**
- * Narrows a registered binding to its membership flag for the registry to set.
- *
- * @since 0.10.0
- */
-export function writableMembership(binding) {
-    return binding;
-}
 /**
  * The stamp of a binding whose activation need has not been computed under the current versions.
  *
@@ -142,16 +138,10 @@ export function writableMembership(binding) {
  */
 export const NO_ACTIVATION_STAMP = -1;
 /**
- * The registration order of a binding no registry has added yet.
- *
- * @since 0.11.0
- */
-export const UNREGISTERED_ORDER = -1;
-/**
- * Drops the memoized resolution frame, for a refinement that changes what the frame reports.
+ * Drops the memoized resolution frame, for a scope change that alters what the frame reports.
  *
- * @remarks The frame derives from `scope` and `slot`, both of which a chain now writes in place on
- * the registered object, so every such refinement clears it.
+ * @remarks The frame derives from `scope` and `slot`; the slot is final once the binding registers, so
+ * only a scope written in place on the registered object clears it.
  *
  * @since 0.5.0-canary.9
  */

package/dist/core/module.d.ts

@@ -1,4 +1,4 @@
-import type { BindToBuilder } from "#core/binding";
+import type { BindToBuilder } from "#core/binding-builders";
 import type { BindingDeclaration, DeclaredBinding } from "#core/binding-declaration";
 import type { Token } from "#core/token";
 import type { Constructor } from "#core/types";

package/dist/core/registry.d.ts

@@ -1,7 +1,7 @@
 import type { Binding } from "#core/binding";
 import type { BindingTag } from "#core/tag";
 import type { Token } from "#core/token";
-import type { BindingConstraint, BindingIdentifier, Constructor } from "#core/types";
+import type { BindingIdentifier, Constructor } from "#core/types";
 /**
  * @since 0.11.0
  */
@@ -11,6 +11,8 @@ export declare class BindingRegistry {
     get version(): number;
     /** Whether a constant has ever been registered here, and so whether teardown has anything to sweep. */
     get hasHeldConstantBinding(): boolean;
+    /** Whether an alias has ever been registered here, and so whether a candidate list can hold one. */
+    get hasHeldAlias(): boolean;
     /** Whether the deferred tagged-slot index has had to be built. */
     get isTaggedIndexBuilt(): boolean;
     /** Whether an id-keyed operation has had to build the id index. */
@@ -55,8 +57,6 @@ export declare class BindingRegistry {
     allBindings(): ReadonlyArray<Binding>;
     /** Remove all bindings. Returns all removed. */
     clear(): ReadonlyArray<Binding>;
-    /** Whether a slot-based binding currently occupies `binding`'s slot, so adding it would displace. */
-    hasSlotOccupant(binding: Binding): boolean;
     /**
      * The binding indexed under one criterion.
      *
@@ -83,28 +83,13 @@ export declare class BindingRegistry {
     hasPredicateCandidate(token: Token<unknown> | Constructor): boolean;
     /** The binding holding a token's default slot — lone or recorded — or `undefined` when none does. */
     getDefaultSlotBinding(token: Token<unknown> | Constructor): Binding | undefined;
-    /** A token's lone default-slot binding — the first read of every synchronous resolve. */
-    getFastDefault(token: Token<unknown> | Constructor): Binding | undefined;
     /**
-     * Takes a live binding out of every index, lets `rewrite` change its slot or predicate, and reports
-     * whether it was live; the caller registers it again with `add`.
+     * The token's default-slot alias, which forwards a request's criteria to its target, or `undefined`.
      *
-     * @remarks The binding keeps its object and its id, so the id index needs no touch and nothing
-     * that holds the object has to be told. `false` means the binding was unbound or displaced since
-     * it registered, and a refinement must not resurrect it.
+     * @remarks A registry that never held an alias answers without probing, so a request missing every slot of a
+     * token pays for forwarding only where forwarding can happen.
      */
-    reslot(binding: Binding, rewrite: () => void): boolean;
-    /**
-     * Marks a live binding as a collection member in place, moving it out of the lone map: a member is
-     * never the token's lone default answer, and nothing else indexes on membership.
-     */
-    setMany(binding: Binding): void;
-    /**
-     * Adds a predicate to a live binding in place.
-     *
-     * @remarks Only ever narrows — `when()` composes with any existing predicate — so the argument is
-     * never absent. Nothing indexes on the predicate, so the binding object and its id stay; a lone
-     * binding moves to a record because the lone map holds default-slot bindings with no predicate.
-     */
-    setPredicate(binding: Binding, predicate: BindingConstraint): void;
+    defaultSlotAlias(token: Token<unknown> | Constructor): Binding | undefined;
+    /** A token's lone default-slot binding — the first read of every synchronous resolve. */
+    getFastDefault(token: Token<unknown> | Constructor): Binding | undefined;
 }