@codefast/di 0.10.1 → 0.11.0

package/dist/core/registry.js

@@ -1,4 +1,4 @@
-import { bindingSlotEquals, bindingSlotToString, writableMembership, writablePredicate } from "#core/binding";
+import { bindingSlotEquals, UNREGISTERED_ORDER, writableMembership, writablePredicate } from "#core/binding";
 import { getOrInsert } from "#core/map-upsert";
 import { advanceStateEpoch } from "#core/state-epoch";
 const NO_BINDINGS = Object.freeze([]);
@@ -16,15 +16,29 @@ 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();
+// Process-wide, so registration order compares across every registry a binding could be restored into.
+let registrationCounter = 0;
+/**
+ * @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;
+    // The binding the last `add` placed and where it landed: the fluent chain refines what it just
+    // registered, so a refinement that follows its own add re-slots without a map probe.
+    #lastAdded;
+    #lastAddedRecord;
     // Built on the first id-keyed read and maintained from then on: a bind-and-resolve container
     // never asks by id, so it never pays for the second map.
     #byId;
@@ -74,46 +88,62 @@ export class BindingRegistry {
      */
     add(binding) {
         this.#bump();
+        if (binding.registrationOrder === UNREGISTERED_ORDER) {
+            registrationCounter += 1;
+            binding.registrationOrder = registrationCounter;
+        }
         if (binding.kind === "constant") {
             this.#heldConstantBinding = true;
         }
         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) {
+                this.#lastAdded = binding;
+                this.#lastAddedRecord = record;
+                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);
+        this.#lastAdded = binding;
+        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);
+                this.#lastAddedRecord = undefined;
             }
             else {
-                this.#createRecord(key, [binding]);
+                this.#lastAddedRecord = this.#createRecord(key, [binding]);
             }
             return undefined;
         }
         // 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);
+            this.#lastAddedRecord = undefined;
             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);
+        this.#deleteLone(key);
         this.#byId?.set(binding.identifier, binding);
-        this.#createRecord(key, [lone, binding]);
+        this.#lastAddedRecord = this.#createRecord(key, occupant.registrationOrder < binding.registrationOrder ? [occupant, binding] : [binding, occupant]);
         return undefined;
     }
     /** Remove all bindings for a token. Returns removed bindings. */
     removeByToken(token) {
         this.#bump();
+        this.#lastAdded = undefined;
         const lone = this.#lone.get(token);
         if (lone !== undefined) {
-            this.#lone.delete(token);
+            this.#deleteLone(token);
             this.#byId?.delete(lone.identifier);
             return [lone];
         }
@@ -138,10 +168,11 @@ export class BindingRegistry {
             return undefined;
         }
         this.#bump();
+        this.#lastAdded = undefined;
         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 +210,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);
@@ -213,8 +236,9 @@ export class BindingRegistry {
     /** Remove all bindings. Returns all removed. */
     clear() {
         this.#bump();
+        this.#lastAdded = undefined;
         const all = this.allBindings();
-        this.#lone.clear();
+        this.#clearLone();
         this.#records?.clear();
         this.#byId?.clear();
         return all;
@@ -260,6 +284,26 @@ export class BindingRegistry {
     getMultiTagged(token, criterion) {
         return this.#records?.get(token)?.multi?.get(criterion);
     }
+    /**
+     * Whether any binding for the token carries a `when()` predicate.
+     *
+     * @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.
+     */
+    hasPredicateCandidate(token) {
+        const bindings = this.getRecorded(token);
+        for (let index = 0; index < bindings.length; index += 1) {
+            if (bindings[index].predicate !== undefined) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /** 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;
+    }
     /** A token's lone default-slot binding — the first read of every synchronous resolve. */
     getFastDefault(token) {
         return this.#lone.get(token);
@@ -276,7 +320,8 @@ export class BindingRegistry {
         const key = binding.token;
         if (this.#lone.get(key) === binding) {
             this.#bump();
-            this.#lone.delete(key);
+            this.#lastAdded = undefined;
+            this.#deleteLone(key);
         }
         else {
             const record = this.#records?.get(key);
@@ -285,6 +330,7 @@ export class BindingRegistry {
                 return false;
             }
             this.#bump();
+            this.#lastAdded = undefined;
             // 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);
@@ -301,6 +347,18 @@ export class BindingRegistry {
         this.#bump();
         // Set before any (re)indexing so `#indexSlot` sees a member and leaves it out of every slot.
         writableMembership(binding).isMany = true;
+        if (binding === this.#lastAdded) {
+            // The chain refining what it just added: where the binding sits is known without a probe.
+            const record = this.#lastAddedRecord;
+            if (record === undefined) {
+                this.#deleteLone(binding.token);
+                this.#lastAddedRecord = this.#createRecord(binding.token, [binding]);
+            }
+            else if (record.defaultOccupant === binding) {
+                record.defaultOccupant = undefined;
+            }
+            return;
+        }
         if (this.#promoteLoneToRecord(binding.token, binding)) {
             return;
         }
@@ -338,7 +396,7 @@ export class BindingRegistry {
         if (this.#lone.get(key) !== binding) {
             return false;
         }
-        this.#lone.delete(key);
+        this.#deleteLone(key);
         this.#createRecord(key, [binding]);
         return true;
     }
@@ -350,10 +408,6 @@ export class BindingRegistry {
         }
         return record;
     }
-    /** Summarize available slot strings for a token (for error messages). */
-    availableSlotStrings(token) {
-        return this.getAll(token).map((binding) => bindingSlotToString(binding.slot));
-    }
     #createRecord(key, bindings) {
         const record = createTokenRecord(bindings);
         (this.#records ??= new Map()).set(key, record);
@@ -388,12 +442,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);
         }
+        insertInRegistrationOrder(record, binding);
         this.#byId?.set(binding.identifier, binding);
         this.#indexSlot(record, binding);
         this.#settle(key, record);
@@ -407,8 +459,22 @@ 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) {
@@ -474,6 +540,24 @@ 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.
+ */
+function insertInRegistrationOrder(record, binding) {
+    const { bindings } = record;
+    const order = binding.registrationOrder;
+    if (bindings.length === 0 || bindings.at(-1).registrationOrder < order) {
+        bindings.push(binding);
+        return;
+    }
+    let index = bindings.length - 1;
+    while (index > 0 && bindings[index - 1].registrationOrder > order) {
+        index -= 1;
+    }
+    // Replaced, never spliced: a walk holding the current array must not lose its place.
+    record.bindings = bindings.toSpliced(index, 0, binding);
+}
 /** 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, a constant of the machine.
  *
  * @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/decorator-metadata.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/decorator-metadata.js

@@ -0,0 +1,20 @@
+/**
+ * The metadata record a decorator writes into, checked once for every decorator the library ships.
+ */
+import { MissingDecoratorMetadataError } from "#errors/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;
+}

package/dist/decorators/inject.js

@@ -1,4 +1,5 @@
 import { getActiveContainer, getAmbientResolution } from "#ambient/active-container";
+import { decoratorMetadataOf } from "#decorators/decorator-metadata";
 import { MissingContainerContextError, StaticMemberDecoratorError } from "#errors/errors";
 import { buildInjectionDescriptor } from "#injection/descriptor";
 import { injectionSlotToResolveOptions } from "#injection/resolve-options";
@@ -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,3 +1,4 @@
+import { decoratorMetadataOf } from "#decorators/decorator-metadata";
 import { normalizeToDescriptor } from "#injection/descriptor";
 import { INJECTABLE_KEY } from "#metadata/metadata-keys";
 /**
@@ -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

@@ -1,4 +1,5 @@
-import { StaticMemberDecoratorError } from "#errors/errors";
+import { decoratorMetadataOf } from "#decorators/decorator-metadata";
+import { StaticMemberDecoratorError, SymbolKeyedLifecycleError } from "#errors/errors";
 import { LIFECYCLE_KEY } from "#metadata/metadata-keys";
 /** Records the decorated method under one lifecycle phase; both decorators differ only in that phase. */
 function recordLifecycleMethod(phase) {
@@ -6,7 +7,12 @@ function recordLifecycleMethod(phase) {
         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)) {