@codefast/di 0.8.1 → 0.10.0

package/dist/core/binding.d.ts

@@ -55,7 +55,7 @@ export declare const DEFAULT_BINDING_SLOT: BindingSlot;
  */
 export declare function bindingSlotToString(slot: BindingSlot): string;
 interface BindingBase<Value> {
-    readonly id: BindingIdentifier;
+    readonly identifier: BindingIdentifier;
     /**
      * True while this binding's factory is executing on the current synchronous call stack.
      *
@@ -83,20 +83,25 @@ interface BindingBase<Value> {
     readonly token: Token<Value> | Constructor<Value>;
     readonly slot: BindingSlot;
     readonly predicate?: BindingConstraint | undefined;
+    /**
+     * Whether the binding is a collection member only: `resolveAll` includes it, `resolve` never
+     * selects it, and it neither displaces nor is displaced under slot last-wins.
+     */
+    readonly isMany: boolean;
 }
-type BindingBaseKeys = keyof BindingBase<unknown>;
 /**
  * The lifecycle hooks every kind but `alias` may carry.
  *
  * @remarks Declared as **methods**, not function-typed properties, so their parameters compare
  * bivariantly and `Binding<Value>` stays assignable to `Binding`. The engine erases the value type at
  * every lane boundary regardless; the public `ActivationHandler` / `DeactivationHandler` keep strict
- * checking, which is where a user's handler is actually verified. Not `readonly`: a fluent chain
- * refines both in place — see {@link RefinableBindingFields}.
+ * checking, which is where a user's handler is actually verified. Named apart from the fluent
+ * `onActivation()` / `onDeactivation()` steps because the chain that registers them is the binding
+ * itself, and a field cannot share a name with a method on the same object.
  */
 interface BindingLifecycleHooks<Value> {
-    onActivation?(ctx: ResolutionContext, instance: Value): Value | Promise<Value>;
-    onDeactivation?(instance: Value): void | Promise<void>;
+    activationHook?(ctx: ResolutionContext, instance: Value): Value | Promise<Value>;
+    deactivationHook?(instance: Value): void | Promise<void>;
 }
 /**
  * A binding that instantiates a constructor.
@@ -182,17 +187,6 @@ export interface AliasBinding<Value> extends BindingBase<Value> {
  * @since 0.3.16-canary.0
  */
 export type Binding<Value = unknown> = ClassBinding<Value> | DynamicBinding<Value> | DynamicAsyncBinding<Value> | ResolvedBinding<Value> | ResolvedAsyncBinding<Value> | ConstantBinding<Value> | AliasBinding<Value>;
-/** `Omit` applied per union member, since a bare `Omit` would collapse the union into one shape. */
-type DistributiveOmit<Union, Keys extends PropertyKey> = Union extends unknown ? Omit<Union, Keys> : never;
-/**
- * Builder-only payload before `id`, `token`, `slot`, and `predicate` are applied.
- *
- * @remarks Derived rather than listed: a new binding kind joins this the moment it joins
- * {@link Binding}, so the two unions cannot diverge.
- *
- * @since 0.3.16-canary.0
- */
-export type PartialBinding<Value> = DistributiveOmit<Binding<Value>, BindingBaseKeys>;
 /**
  * Returns a process-unique identifier for a new binding.
  *
@@ -200,45 +194,39 @@ export type PartialBinding<Value> = DistributiveOmit<Binding<Value>, BindingBase
  */
 export declare function generateBindingId(): BindingIdentifier;
 /**
- * The single construction site for bindings — one literal, one V8 hidden class.
- *
- * @remarks Field order is fixed and this is the only construction site, so every binding shares one
- * hidden class. Reordering the fields, or adding a second site, gives that up.
- *
- * @param source - the kind-specific payload, or an existing binding to re-slot
- * @param token - the key requests resolve the binding by
- * @param slot - the name + tags a request must match to select this binding
- * @param predicate - a custom constraint, or `undefined` for none
- * @param id - reuse a caller's id to keep a fluent chain's `id()` stable across refinements
+ * 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.5.0-canary.8
+ * @since 0.10.0
  */
-export declare function createBinding<Value>(source: PartialBinding<Value> | Binding<Value>, token: Token<Value> | Constructor<Value>, slot: BindingSlot, predicate: BindingConstraint | undefined, id?: BindingIdentifier): Binding<Value>;
+export interface PredicateField {
+    predicate: BindingConstraint | undefined;
+}
 /**
- * Writable view of the only fields a fluent chain may refine after registration.
+ * Narrows a registered binding to its predicate for the registry to rewrite.
  *
- * @remarks No registry index is keyed on these, so a builder that owns the registered object
- * can write them directly instead of re-registering. `token`, `slot`, `predicate` and `id`
- * are excluded on purpose — changing those means re-indexing.
+ * @since 0.10.0
+ */
+export declare function writablePredicate(binding: Binding): PredicateField;
+/**
+ * Writable view of collection membership, which the registry sets because it decides the binding's map.
  *
- * @since 0.5.0-canary.8
+ * @since 0.10.0
  */
-export interface RefinableBindingFields<Value> {
-    onActivation: ActivationHandler<Value> | undefined;
-    onDeactivation: DeactivationHandler<Value> | undefined;
-    scope: BindingScope;
+export interface MembershipField {
+    isMany: boolean;
 }
 /**
- * Narrows a registered binding to the fields a fluent chain may still refine.
+ * Narrows a registered binding to its membership flag for the registry to set.
  *
- * @since 0.5.0-canary.8
+ * @since 0.10.0
  */
-export declare function refinableFields<Value>(binding: Binding<Value>): RefinableBindingFields<Value>;
+export declare function writableMembership(binding: Binding): MembershipField;
 /**
  * Drops the memoized resolution frame, for a refinement that changes what the frame reports.
  *
- * @remarks `scope` is the only field a chain writes in place that the frame derives from — a
- * re-slot builds a fresh binding, whose frame starts empty anyway.
+ * @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.
  *
  * @since 0.5.0-canary.9
  */
@@ -248,11 +236,21 @@ export declare function clearBindingFrame<Value>(binding: Binding<Value>): void;
  *
  * @since 0.3.16-canary.0
  */
-export interface SlotConstrainedBuilder {
+export interface SlotConstrainedBuilder<Names extends string = string> {
+    /** Narrows the binding to requests the predicate accepts, evaluated on every resolve. */
     when(predicate: BindingConstraint): this;
-    whenNamed(name: string): 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;
 }
 /**
@@ -260,26 +258,26 @@ export interface SlotConstrainedBuilder {
  *
  * @since 0.3.16-canary.0
  */
-export interface BindToBuilder<Value> {
-    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>;
+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>;
+    }) => 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>;
-    toAlias(target: Token<Value> | Constructor<Value>): AliasBindingBuilder;
+    }) => 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> extends SlotConstrainedBuilder {
+export interface BindingBuilder<Value, Names extends string = string> extends SlotConstrainedBuilder<Names> {
     singleton(): SingletonBindingBuilder<Value>;
     transient(): TransientBindingBuilder<Value>;
     scoped(): ScopedBindingBuilder<Value>;
@@ -289,7 +287,7 @@ export interface BindingBuilder<Value> extends SlotConstrainedBuilder {
  *
  * @since 0.3.16-canary.0
  */
-export interface ConstantBindingBuilder<Value> extends SlotConstrainedBuilder {
+export interface ConstantBindingBuilder<Value, Names extends string = string> extends SlotConstrainedBuilder<Names> {
     onActivation(fn: ActivationHandler<Value>): SingletonLifecycleBuilder<Value>;
     onDeactivation(fn: DeactivationHandler<Value>): SingletonLifecycleBuilder<Value>;
 }
@@ -298,7 +296,7 @@ export interface ConstantBindingBuilder<Value> extends SlotConstrainedBuilder {
  *
  * @since 0.3.16-canary.0
  */
-export interface AliasBindingBuilder extends SlotConstrainedBuilder {
+export interface AliasBindingBuilder<Names extends string = string> extends SlotConstrainedBuilder<Names> {
 }
 /**
  * The fluent chain after `singleton()`, where both lifecycle hooks stay available.

package/dist/core/binding.js

@@ -82,56 +82,30 @@ let bindingIdCounter = 0;
  * @since 0.3.16-canary.0
  */
 export function generateBindingId() {
-    return String(++bindingIdCounter);
+    bindingIdCounter += 1;
+    return bindingIdCounter;
 }
 /**
- * The single construction site for bindings — one literal, one V8 hidden class.
+ * Narrows a registered binding to its predicate for the registry to rewrite.
  *
- * @remarks Field order is fixed and this is the only construction site, so every binding shares one
- * hidden class. Reordering the fields, or adding a second site, gives that up.
- *
- * @param source - the kind-specific payload, or an existing binding to re-slot
- * @param token - the key requests resolve the binding by
- * @param slot - the name + tags a request must match to select this binding
- * @param predicate - a custom constraint, or `undefined` for none
- * @param id - reuse a caller's id to keep a fluent chain's `id()` stable across refinements
- *
- * @since 0.5.0-canary.8
+ * @since 0.10.0
  */
-export function createBinding(source, token, slot, predicate, id = generateBindingId()) {
-    const fields = source;
-    return {
-        kind: fields.kind,
-        id,
-        inFlight: false,
-        frame: undefined,
-        // An `in` probe, not `??`: a re-slotted singleton may legitimately hold a cached `undefined`.
-        instance: "instance" in fields ? fields.instance : NO_INSTANCE,
-        token,
-        slot,
-        predicate,
-        scope: fields.scope,
-        target: fields.target,
-        factory: fields.factory,
-        deps: fields.deps,
-        value: fields.value,
-        onActivation: fields.onActivation,
-        onDeactivation: fields.onDeactivation,
-    };
+export function writablePredicate(binding) {
+    return binding;
 }
 /**
- * Narrows a registered binding to the fields a fluent chain may still refine.
+ * Narrows a registered binding to its membership flag for the registry to set.
  *
- * @since 0.5.0-canary.8
+ * @since 0.10.0
  */
-export function refinableFields(binding) {
+export function writableMembership(binding) {
     return binding;
 }
 /**
  * Drops the memoized resolution frame, for a refinement that changes what the frame reports.
  *
- * @remarks `scope` is the only field a chain writes in place that the frame derives from — a
- * re-slot builds a fresh binding, whose frame starts empty anyway.
+ * @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.
  *
  * @since 0.5.0-canary.9
  */

package/dist/core/constraint-requirement.d.ts

@@ -12,23 +12,38 @@ export declare const CONSTRAINT_REQUIREMENT: unique symbol;
 /**
  * The slot name a constraint waits for on an ancestor.
  *
- * @remarks Only names are described. A tag criterion is interned, so a typo cannot produce one that
- * looks valid, while a name is a bare string that nothing checks.
+ * @remarks Only names are described, however spelled: a tag criterion of any other key is minted from
+ * a typed key, so a typo cannot produce one that looks valid, while a name is a bare string that
+ * nothing checks — through `whenNamed`'s reserved key included.
  *
  * @since 0.6.0
  */
 export interface ConstraintRequirement {
     readonly requires: "ancestorSlotName";
+    /** The token whose slot must carry the name, or `undefined` when the spelling named no token. */
+    readonly tokenName: string | undefined;
     readonly name: string;
     /** The helper that built the predicate, so a report can name what the caller wrote. */
     readonly helperName: string;
 }
 /**
- * Records what a predicate waits for. Called once, where the predicate is built.
+ * What a helper records about one waited-for slot name, before the discriminant is stamped on.
+ *
+ * @since 0.9.0
+ */
+export type SlotNameRequirement = Omit<ConstraintRequirement, "requires">;
+/**
+ * Records the one slot name a predicate waits for. Called once, where the predicate is built.
  *
  * @since 0.6.0
  */
-export declare function requiringAncestorSlotName(predicate: BindingConstraint, name: string, helperName: string): BindingConstraint;
+export declare function requiringAncestorSlotName(predicate: BindingConstraint, requirement: SlotNameRequirement): BindingConstraint;
+/**
+ * Records every slot name a predicate waits for — one per reserved criterion in a `…TaggedAll` list.
+ *
+ * @since 0.9.0
+ */
+export declare function requiringAncestorSlotNames(predicate: BindingConstraint, requirements: ReadonlyArray<SlotNameRequirement>): BindingConstraint;
 /**
  * The requirement a predicate carries, if it was built by a helper that records one.
  *

package/dist/core/constraint-requirement.js

@@ -8,13 +8,27 @@
  */
 export const CONSTRAINT_REQUIREMENT = Symbol("di:constraint-requirement");
 /**
- * Records what a predicate waits for. Called once, where the predicate is built.
+ * Records the one slot name a predicate waits for. Called once, where the predicate is built.
  *
  * @since 0.6.0
  */
-export function requiringAncestorSlotName(predicate, name, helperName) {
-    const requirement = { requires: "ancestorSlotName", name, helperName };
-    Object.defineProperty(predicate, CONSTRAINT_REQUIREMENT, { value: requirement, enumerable: false });
+export function requiringAncestorSlotName(predicate, requirement) {
+    return requiringAncestorSlotNames(predicate, [requirement]);
+}
+/**
+ * Records every slot name a predicate waits for — one per reserved criterion in a `…TaggedAll` list.
+ *
+ * @since 0.9.0
+ */
+export function requiringAncestorSlotNames(predicate, requirements) {
+    return attachRequirements(predicate, requirements.map((requirement) => ({ requires: "ancestorSlotName", ...requirement })));
+}
+/** One non-enumerable write per predicate: a second define on the same key would throw. */
+function attachRequirements(predicate, requirements) {
+    Object.defineProperty(predicate, CONSTRAINT_REQUIREMENT, {
+        value: requirements.length === 1 ? requirements[0] : requirements,
+        enumerable: false,
+    });
     return predicate;
 }
 /**
@@ -53,9 +67,5 @@ export function mergingConstraintRequirements(composite, left, right) {
     if (merged.length === 0) {
         return composite;
     }
-    Object.defineProperty(composite, CONSTRAINT_REQUIREMENT, {
-        value: merged.length === 1 ? merged[0] : merged,
-        enumerable: false,
-    });
-    return composite;
+    return attachRequirements(composite, merged);
 }

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 { BindingIdentifier, Constructor } from "#/core/types";
+import type { BindingConstraint, BindingIdentifier, Constructor } from "#/core/types";
 /**
  * One container's binding store, indexed by token, binding id, and slot for fast lookup.
  *
@@ -13,6 +13,12 @@ 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 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. */
+    get isIdIndexBuilt(): boolean;
+    /** Whether a token carrying more than one default-slot binding has had to build the record map. */
+    get isRecordMapBuilt(): boolean;
     /**
      * Registers a mutation the indexes don't care about (a fluent chain refining scope or an
      * activation hook in place), so version-stamped resolver caches still invalidate.
@@ -29,8 +35,22 @@ export declare class BindingRegistry {
     removeByToken(token: Token<unknown> | Constructor): Array<Binding>;
     /** Remove a specific binding by ID. Returns the removed binding or undefined. */
     removeById(id: BindingIdentifier): Binding | undefined;
-    /** Get all bindings for a token. */
+    /**
+     * Get all bindings for a token.
+     *
+     * @remarks Allocates a one-element list for a lone default-slot binding, so a hot path asks
+     * `getFastDefault()` first and reaches here only for a token that keeps a record.
+     */
     getAll(token: Token<unknown> | Constructor): ReadonlyArray<Binding>;
+    /**
+     * The bindings of a token that keeps a record, or none.
+     *
+     * @remarks For a caller whose lone-map probe has just missed: the record map is all that is left
+     * to ask, and a lone binding's one-element list is never materialised here.
+     */
+    getRecorded(token: Token<unknown> | Constructor): ReadonlyArray<Binding>;
+    /** How many bindings a token holds, without materialising a lone binding's list. */
+    countBindings(token: Token<unknown> | Constructor): number;
     /** Get binding by ID. */
     getById(id: BindingIdentifier): Binding | undefined;
     /** Check if any binding exists for token. */
@@ -48,6 +68,8 @@ export declare class BindingRegistry {
      * identity — where a value-keyed map answered by SameValueZero and parted from `Object.is` on ±0.
      */
     getSimpleTagged(token: Token<unknown> | Constructor, criterion: BindingTag): Binding | undefined;
+    /** The binding whose slot is exactly these two criteria, declared in either order, or `undefined`. */
+    getPairTagged(token: Token<unknown> | Constructor, first: BindingTag, second: BindingTag): Binding | undefined;
     /**
      * The multi-tag bindings whose slot's first criterion is `criterion`.
      *
@@ -55,9 +77,30 @@ export declare class BindingRegistry {
      * against the request — first-criterion bucketing only guarantees each candidate appears once.
      */
     getMultiTagged(token: Token<unknown> | Constructor, criterion: BindingTag): ReadonlyArray<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`.
+     *
+     * @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.
+     */
+    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;
     /** Summarize available slot strings for a token (for error messages). */
     availableSlotStrings(token: Token<unknown> | Constructor): Array<string>;
-    /** Whether the deferred tagged-slot index has had to be built. */
-    get isTaggedIndexBuilt(): boolean;
 }