@codefast/di 0.9.0 → 0.10.1

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 { 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";
 /**
  * The criterion set a binding registers under and a request matches against.
  *
@@ -55,14 +55,14 @@ 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.
      *
      * @remarks Both cycle guards that can use an `O(1)` flag read this — the sync transient-dynamic
      * lane and the async cascade lane — because synchronous code does not interleave, so the flag *is*
-     * exact path membership. Not optional: `createBinding` always sets it, and a field that may be
-     * absent is a field that can cost the shared hidden class. Resolver-owned; callers never set it.
+     * exact path membership. Not optional: the binding builder always initializes it, and a field that
+     * may be absent is a field that can cost the shared hidden class. Resolver-owned; callers never set it.
      */
     inFlight: boolean;
     /**
@@ -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
  */
@@ -257,6 +245,11 @@ export interface SlotConstrainedBuilder<Names extends string = string> {
     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;
 }

package/dist/core/binding.js

@@ -1,4 +1,4 @@
-import { NO_TAG_KEYS, slotName, tagKeyMaskOf } from "#/core/tag";
+import { NO_TAG_KEYS, slotName, tagKeyMaskOf } from "#core/tag";
 /**
  * Builds a slot from its criterion set, deriving the name view and key mask.
  *
@@ -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

@@ -1,5 +1,5 @@
 /** What a constraint needs to exist before it can ever match, so `validate()` can check for it. */
-import type { BindingConstraint } from "#/core/types";
+import type { BindingConstraint } from "#core/types";
 /**
  * Key the requirement is attached under.
  *

package/dist/core/module.d.ts

@@ -1,6 +1,6 @@
-import type { BindToBuilder } from "#/core/binding";
-import type { Token } from "#/core/token";
-import type { Constructor } from "#/core/types";
+import type { BindToBuilder } from "#core/binding";
+import type { Token } from "#core/token";
+import type { Constructor } from "#core/types";
 declare const SYNC_MODULE_BRAND: unique symbol;
 declare const ASYNC_MODULE_BRAND: unique symbol;
 /**

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 { Binding } from "#core/binding";
+import type { BindingTag } from "#core/tag";
+import type { Token } from "#core/token";
+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.
@@ -21,16 +27,30 @@ export declare class BindingRegistry {
     /**
      * Adds or replaces a binding using slot-aware last-wins. Returns the displaced binding, if any.
      *
-     * @remarks The binding is stored by reference — it must come from `createBinding`, which is
-     * what guarantees the single hidden class the resolver's hot reads depend on.
+     * @remarks The binding is stored by reference — it must come from the one binding builder, which
+     * is what guarantees the single hidden class the resolver's hot reads depend on.
      */
     add(binding: Binding): Binding | undefined;
     /** Remove all bindings for a token. Returns removed bindings. */
     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;
 }