@codefast/di 0.10.1 → 0.12.0

package/dist/core/registry.js

@@ -1,4 +1,4 @@
-import { bindingSlotEquals, bindingSlotToString, writableMembership, writablePredicate } from "#core/binding";
+import { bindingSlotEquals } from "#core/binding";
 import { getOrInsert } from "#core/map-upsert";
 import { advanceStateEpoch } from "#core/state-epoch";
 const NO_BINDINGS = Object.freeze([]);
@@ -16,12 +16,22 @@ function createTokenRecord(bindings) {
  *
  * @since 0.3.16-canary.0
  */
+/**
+ * One shared empty map answers every read of a registry nothing was bound into, so a container
+ * that only ever resolves through its parent — every per-request child — allocates no map.
+ */
+const EMPTY_LONE = new Map();
+const HELD_CONSTANT = 1;
+const HELD_ALIAS = 2;
+/**
+ * @since 0.11.0
+ */
 export class BindingRegistry {
     // Monotonic mutation counter — lets resolvers version-stamp lookup caches across a container chain.
     #version = 0;
     // The common token lives here and nowhere else: exactly one default-slot binding, so the hot read
     // of every resolve is a bare `Map.get` and a plain bind is one map write.
-    #lone = new Map();
+    #lone = EMPTY_LONE;
     // Every other token — several bindings, a tagged slot, a predicate — has a record here, and a
     // token is in exactly one of the two maps. Allocated by the first token that needs a record.
     #records;
@@ -30,9 +40,9 @@ export class BindingRegistry {
     #byId;
     // Set when the first tagged slot lands and never cleared, like the tagged maps it stands for.
     #taggedIndexBuilt = false;
-    // Set on the first constant registered and never cleared. Teardown only needs the negative answer
-    // to be exact, and that is what lets a container holding no constant skip its sweep entirely.
-    #heldConstantBinding = false;
+    // Kinds registered here at least once, never cleared: only the negative answers must be exact, so a
+    // container holding no constant skips its teardown sweep and one holding no alias skips its forwarding probe.
+    #heldKinds = 0;
     /** Monotonic version — increments on every mutation. */
     get version() {
         return this.#version;
@@ -45,7 +55,11 @@ export class BindingRegistry {
     }
     /** Whether a constant has ever been registered here, and so whether teardown has anything to sweep. */
     get hasHeldConstantBinding() {
-        return this.#heldConstantBinding;
+        return (this.#heldKinds & HELD_CONSTANT) !== 0;
+    }
+    /** Whether an alias has ever been registered here, and so whether a candidate list can hold one. */
+    get hasHeldAlias() {
+        return (this.#heldKinds & HELD_ALIAS) !== 0;
     }
     /** Whether the deferred tagged-slot index has had to be built. */
     get isTaggedIndexBuilt() {
@@ -75,18 +89,27 @@ export class BindingRegistry {
     add(binding) {
         this.#bump();
         if (binding.kind === "constant") {
-            this.#heldConstantBinding = true;
+            this.#heldKinds |= HELD_CONSTANT;
+        }
+        else if (binding.kind === "alias") {
+            this.#heldKinds |= HELD_ALIAS;
         }
         const key = binding.token;
-        const record = this.#records?.get(key);
-        if (record !== undefined) {
-            return this.#addToRecord(key, record, binding);
+        const records = this.#records;
+        if (records !== undefined) {
+            const record = records.get(key);
+            if (record !== undefined) {
+                return this.#addToRecord(key, record, binding);
+            }
         }
-        const lone = this.#lone.get(key);
-        if (lone === undefined) {
-            this.#byId?.set(binding.identifier, binding);
+        const occupant = this.#lone.get(key);
+        if (occupant === undefined) {
+            // The common bind: a fresh token taking the lone seat, one probe and one write.
+            if (this.#byId !== undefined) {
+                this.#byId.set(binding.identifier, binding);
+            }
             if (isDefaultSlotBinding(binding)) {
-                this.#lone.set(key, binding);
+                this.#setLone(key, binding);
             }
             else {
                 this.#createRecord(key, [binding]);
@@ -95,17 +118,17 @@ export class BindingRegistry {
         }
         // Same slot, last wins: the newcomer takes the lone seat and nothing else moves.
         if (isDefaultSlotBinding(binding)) {
-            this.#lone.set(key, binding);
+            this.#setLone(key, binding);
             if (this.#byId !== undefined) {
-                this.#byId.delete(lone.identifier);
+                this.#byId.delete(occupant.identifier);
                 this.#byId.set(binding.identifier, binding);
             }
-            return lone;
+            return occupant;
         }
-        // A second shape joins the token, which is what a record is for.
-        this.#lone.delete(key);
+        // A second shape joins the token, which is what a record is for; every add is the newest, so it goes last.
+        this.#deleteLone(key);
         this.#byId?.set(binding.identifier, binding);
-        this.#createRecord(key, [lone, binding]);
+        this.#createRecord(key, [occupant, binding]);
         return undefined;
     }
     /** Remove all bindings for a token. Returns removed bindings. */
@@ -113,7 +136,7 @@ export class BindingRegistry {
         this.#bump();
         const lone = this.#lone.get(token);
         if (lone !== undefined) {
-            this.#lone.delete(token);
+            this.#deleteLone(token);
             this.#byId?.delete(lone.identifier);
             return [lone];
         }
@@ -141,7 +164,7 @@ export class BindingRegistry {
         byId.delete(id);
         const key = binding.token;
         if (this.#lone.get(key)?.identifier === id) {
-            this.#lone.delete(key);
+            this.#deleteLone(key);
             return binding;
         }
         const record = this.#records?.get(key);
@@ -179,14 +202,6 @@ export class BindingRegistry {
     getRecorded(token) {
         return this.#records?.get(token)?.bindings ?? NO_BINDINGS;
     }
-    /** How many bindings a token holds, without materialising a lone binding's list. */
-    countBindings(token) {
-        const record = this.#records?.get(token);
-        if (record !== undefined) {
-            return record.bindings.length;
-        }
-        return this.#lone.has(token) ? 1 : 0;
-    }
     /** Get binding by ID. */
     getById(id) {
         return this.#ensureById().get(id);
@@ -214,26 +229,11 @@ export class BindingRegistry {
     clear() {
         this.#bump();
         const all = this.allBindings();
-        this.#lone.clear();
+        this.#clearLone();
         this.#records?.clear();
         this.#byId?.clear();
         return all;
     }
-    /** Whether a slot-based binding currently occupies `binding`'s slot, so adding it would displace. */
-    hasSlotOccupant(binding) {
-        if (isPurePredicateBinding(binding)) {
-            return false;
-        }
-        if (this.#lone.has(binding.token)) {
-            // The lone seat is the default slot, so only a default-slot newcomer collides with it.
-            return binding.slot.tags.length === 0;
-        }
-        const record = this.#records?.get(binding.token);
-        if (record === undefined) {
-            return false;
-        }
-        return this.#slotOccupant(record, binding.slot) !== undefined;
-    }
     /**
      * The binding indexed under one criterion.
      *
@@ -260,99 +260,42 @@ export class BindingRegistry {
     getMultiTagged(token, criterion) {
         return this.#records?.get(token)?.multi?.get(criterion);
     }
-    /** A token's lone default-slot binding — the first read of every synchronous resolve. */
-    getFastDefault(token) {
-        return this.#lone.get(token);
-    }
     /**
-     * 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`.
+     * Whether any binding for the token carries a `when()` predicate.
      *
-     * @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 Only a token that keeps a record can hold a predicate — a lone binding is default-slot
+     * with none — so an index fast lane consults this to decline to full selection when the
+     * more-specific rule's predicate step could apply.
      */
-    reslot(binding, rewrite) {
-        const key = binding.token;
-        if (this.#lone.get(key) === binding) {
-            this.#bump();
-            this.#lone.delete(key);
-        }
-        else {
-            const record = this.#records?.get(key);
-            const index = record === undefined ? -1 : record.bindings.indexOf(binding);
-            if (record === undefined || index === -1) {
-                return false;
+    hasPredicateCandidate(token) {
+        const bindings = this.getRecorded(token);
+        for (let index = 0; index < bindings.length; index += 1) {
+            if (bindings[index].predicate !== undefined) {
+                return true;
             }
-            this.#bump();
-            // Replaced, never spliced: a walk holding the current array must not lose its place.
-            record.bindings = record.bindings.toSpliced(index, 1);
-            this.#deindexSlot(record, binding);
-            this.#settle(key, record);
         }
-        rewrite();
-        return true;
+        return false;
     }
-    /**
-     * 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) {
-        this.#bump();
-        // Set before any (re)indexing so `#indexSlot` sees a member and leaves it out of every slot.
-        writableMembership(binding).isMany = true;
-        if (this.#promoteLoneToRecord(binding.token, binding)) {
-            return;
-        }
-        // A default occupant that becomes a member frees its slot, so drop the stale index entry. A
-        // member cannot collapse a record back to lone, so this path does not settle.
-        this.#clearDefaultOccupant(binding.token, binding);
+    /** The binding holding a token's default slot — lone or recorded — or `undefined` when none does. */
+    getDefaultSlotBinding(token) {
+        return this.#lone.get(token) ?? this.#records?.get(token)?.defaultOccupant;
     }
     /**
-     * Adds a predicate to a live binding in place.
+     * The token's default-slot alias, which forwards a request's criteria to its target, or `undefined`.
      *
-     * @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.
+     * @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.
      */
-    setPredicate(binding, predicate) {
-        this.#bump();
-        // Set before any (re)indexing: a predicate-only binding holds no default slot.
-        writablePredicate(binding).predicate = predicate;
-        if (this.#promoteLoneToRecord(binding.token, binding)) {
-            return;
-        }
-        // The binding may have vacated the default slot, and a narrowed record can collapse back to lone.
-        const record = this.#clearDefaultOccupant(binding.token, binding);
-        if (record !== undefined) {
-            this.#settle(binding.token, record);
-        }
-    }
-    /**
-     * Moves a binding still holding the lone seat into a fresh one-binding record, returning whether it did.
-     *
-     * @remarks Its field (`isMany` or `predicate`) is written before this call, so the founding
-     * `#indexSlot` files it under the slot it now holds.
-     */
-    #promoteLoneToRecord(key, binding) {
-        if (this.#lone.get(key) !== binding) {
-            return false;
-        }
-        this.#lone.delete(key);
-        this.#createRecord(key, [binding]);
-        return true;
-    }
-    /** Clears the default-slot index entry a binding has vacated, returning its record if one exists. */
-    #clearDefaultOccupant(key, binding) {
-        const record = this.#records?.get(key);
-        if (record?.defaultOccupant === binding) {
-            record.defaultOccupant = undefined;
+    defaultSlotAlias(token) {
+        if ((this.#heldKinds & HELD_ALIAS) === 0) {
+            return undefined;
         }
-        return record;
+        const occupant = this.getDefaultSlotBinding(token);
+        return occupant !== undefined && occupant.kind === "alias" ? occupant : undefined;
     }
-    /** Summarize available slot strings for a token (for error messages). */
-    availableSlotStrings(token) {
-        return this.getAll(token).map((binding) => bindingSlotToString(binding.slot));
+    /** A token's lone default-slot binding — the first read of every synchronous resolve. */
+    getFastDefault(token) {
+        return this.#lone.get(token);
     }
     #createRecord(key, bindings) {
         const record = createTokenRecord(bindings);
@@ -388,12 +331,10 @@ export class BindingRegistry {
         }
         // A selection may be walking this list inside a `when()` predicate. An append past the length it
         // read cannot shift it, so it lands in place; a displacement replaces the array instead.
-        if (displacedBinding === undefined) {
-            record.bindings.push(binding);
-        }
-        else {
-            record.bindings = [...record.bindings.filter((candidate) => candidate !== displacedBinding), binding];
+        if (displacedBinding !== undefined) {
+            record.bindings = record.bindings.filter((candidate) => candidate !== displacedBinding);
         }
+        record.bindings.push(binding);
         this.#byId?.set(binding.identifier, binding);
         this.#indexSlot(record, binding);
         this.#settle(key, record);
@@ -407,9 +348,23 @@ export class BindingRegistry {
         }
         else if (bindings.length === 1 && isDefaultSlotBinding(bindings[0])) {
             this.#records.delete(key);
-            this.#lone.set(key, bindings[0]);
+            this.#setLone(key, bindings[0]);
         }
     }
+    // Every write to the lone map goes through these three, so a cache of its entries has one place to follow them.
+    #setLone(key, binding) {
+        let lone = this.#lone;
+        if (lone === EMPTY_LONE) {
+            lone = this.#lone = new Map();
+        }
+        lone.set(key, binding);
+    }
+    #deleteLone(key) {
+        this.#lone.delete(key);
+    }
+    #clearLone() {
+        this.#lone.clear();
+    }
     #ensureById() {
         if (this.#byId === undefined) {
             const byId = new Map();
@@ -474,6 +429,10 @@ export class BindingRegistry {
         }
     }
 }
+/**
+ * Places a binding in its record by registration order: a fresh registration appends, and a binding a
+ * chain took out and put back returns to its place.
+ */
 /** A binding nothing has to be matched against: the default slot, no predicate, not a collection member. */
 function isDefaultSlotBinding(binding) {
     return binding.slot.tags.length === 0 && binding.predicate === undefined && !binding.isMany;

package/dist/core/state-epoch.d.ts

@@ -13,4 +13,21 @@ export declare function stateEpoch(): number;
  *
  * @since 0.10.0
  */
-export declare function advanceStateEpoch(): void;
+export declare function advanceStateEpoch(): void;
+/**
+ * The container-disposal counter, held in a cell so a hot reader dereferences a field rather than
+ * paying a cross-module call — apart from {@link stateEpoch} so a per-request child's `dispose()`
+ * does not invalidate the chain-version memo that keeps deep resolves cheap. A child compares it to
+ * learn whether an ancestor was disposed, re-walking the chain only after a disposal somewhere.
+ *
+ * @since 0.11.0
+ */
+export declare const disposeEpochRef: {
+    value: number;
+};
+/**
+ * Advances the dispose epoch; a container's teardown calls it so descendants re-check the chain.
+ *
+ * @since 0.11.0
+ */
+export declare function advanceDisposeEpoch(): void;

package/dist/core/state-epoch.js

@@ -18,4 +18,21 @@ export function stateEpoch() {
  */
 export function advanceStateEpoch() {
     epoch += 1;
+}
+/**
+ * The container-disposal counter, held in a cell so a hot reader dereferences a field rather than
+ * paying a cross-module call — apart from {@link stateEpoch} so a per-request child's `dispose()`
+ * does not invalidate the chain-version memo that keeps deep resolves cheap. A child compares it to
+ * learn whether an ancestor was disposed, re-walking the chain only after a disposal somewhere.
+ *
+ * @since 0.11.0
+ */
+export const disposeEpochRef = { value: 0 };
+/**
+ * Advances the dispose epoch; a container's teardown calls it so descendants re-check the chain.
+ *
+ * @since 0.11.0
+ */
+export function advanceDisposeEpoch() {
+    disposeEpochRef.value += 1;
 }

package/dist/core/tag.js

@@ -1,6 +1,6 @@
 /** Tag keys and the interned pairs they mint — the one way a slot criterion is built. */
 /**
- * How many distinct tag keys one mask bit is shared by.
+ * The bits a tag-key mask holds: the width of a 32-bit integer.
  *
  * @remarks Ids past this wrap, so two keys can share a bit. The mask is a prefilter only — a shared
  * bit costs a false positive that the identity comparison then rejects, never a false negative.

package/dist/decorators/inject.js

@@ -1,8 +1,9 @@
-import { getActiveContainer, getAmbientResolution } from "#ambient/active-container";
-import { MissingContainerContextError, StaticMemberDecoratorError } from "#errors/errors";
+import { getActiveContainer, getAmbientResolution } from "#ambient-container";
+import { decoratorMetadataOf } from "#decorators/metadata-record";
+import { MissingContainerContextError, StaticMemberDecoratorError } from "#errors";
+import { injectionSlotToResolveOptions } from "#injection/dependency-slot";
 import { buildInjectionDescriptor } from "#injection/descriptor";
-import { injectionSlotToResolveOptions } from "#injection/resolve-options";
-import { INJECT_ACCESSOR_KEY } from "#metadata/metadata-keys";
+import { INJECT_ACCESSOR_KEY } from "#metadata/keys";
 /**
  * The name of the class being constructed, or `undefined` when there is none to report.
  *
@@ -36,7 +37,7 @@ export function inject(token, options) {
         if (context.static) {
             throw new StaticMemberDecoratorError("inject", String(context.name));
         }
-        const meta = context.metadata;
+        const meta = decoratorMetadataOf(context, "inject");
         // Own bucket only: the metadata record inherits the base class's, and pushing into an inherited
         // array would register this accessor on the base class instead.
         if (!Object.hasOwn(meta, INJECT_ACCESSOR_KEY) || !Array.isArray(meta[INJECT_ACCESSOR_KEY])) {

package/dist/decorators/injectable.js

@@ -1,5 +1,6 @@
+import { decoratorMetadataOf } from "#decorators/metadata-record";
 import { normalizeToDescriptor } from "#injection/descriptor";
-import { INJECTABLE_KEY } from "#metadata/metadata-keys";
+import { INJECTABLE_KEY } from "#metadata/keys";
 /**
  * Creates an empty auto-register registry.
  *
@@ -23,6 +24,7 @@ export function createAutoRegisterRegistry() {
  */
 export function injectable(deps, options) {
     return function (target, context) {
+        const meta = decoratorMetadataOf(context, "injectable");
         const parameterMetadataList = (deps ?? []).map((dependency, index) => {
             const descriptor = normalizeToDescriptor(dependency);
             const baseParameterMetadata = {
@@ -44,7 +46,7 @@ export function injectable(deps, options) {
         });
         // Field decorators run before the class decorator — accessor @inject entries are
         // already on context.metadata by the time this runs.
-        context.metadata[INJECTABLE_KEY] = {
+        meta[INJECTABLE_KEY] = {
             params: parameterMetadataList,
         };
         if (options?.autoRegister !== undefined) {

package/dist/decorators/{lifecycle-decorators.js → lifecycle.js}

@@ -1,12 +1,18 @@
-import { StaticMemberDecoratorError } from "#errors/errors";
-import { LIFECYCLE_KEY } from "#metadata/metadata-keys";
+import { decoratorMetadataOf } from "#decorators/metadata-record";
+import { StaticMemberDecoratorError, SymbolKeyedLifecycleError } from "#errors";
+import { LIFECYCLE_KEY } from "#metadata/keys";
 /** Records the decorated method under one lifecycle phase; both decorators differ only in that phase. */
 function recordLifecycleMethod(phase) {
     return function (target, context) {
         if (context.static) {
             throw new StaticMemberDecoratorError(phase, String(context.name));
         }
-        const meta = context.metadata;
+        // The lifecycle reader keys methods by their string name, so a symbol-keyed method can never be
+        // found again — fail here, where the declaration is, rather than at resolve.
+        if (typeof context.name === "symbol") {
+            throw new SymbolKeyedLifecycleError(phase, String(context.name));
+        }
+        const meta = decoratorMetadataOf(context, phase);
         // Own bucket only: `context.metadata` inherits the base class's record, and writing through an
         // inherited bucket would register this hook on the base class instead.
         if (!Object.hasOwn(meta, LIFECYCLE_KEY)) {

package/dist/decorators/metadata-record.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns the metadata record a decorator context carries.
+ *
+ * @throws `MissingDecoratorMetadataError` when the transpiler handed none, which is how a runtime
+ * without `Symbol.metadata` shows up.
+ *
+ * @since 0.11.0
+ */
+export declare function decoratorMetadataOf(context: DecoratorContext, decoratorName: string): Record<string | symbol, unknown>;

package/dist/decorators/metadata-record.js

@@ -0,0 +1,20 @@
+/**
+ * The metadata record a decorator writes into, checked once for every decorator the library ships.
+ */
+import { MissingDecoratorMetadataError } from "#errors";
+/**
+ * Returns the metadata record a decorator context carries.
+ *
+ * @throws `MissingDecoratorMetadataError` when the transpiler handed none, which is how a runtime
+ * without `Symbol.metadata` shows up.
+ *
+ * @since 0.11.0
+ */
+export function decoratorMetadataOf(context, decoratorName) {
+    // Widened, not asserted: the lib types promise a record that a runtime without `Symbol.metadata` never hands over.
+    const metadata = context.metadata;
+    if (metadata === undefined || metadata === null) {
+        throw new MissingDecoratorMetadataError(decoratorName);
+    }
+    return metadata;
+}