@codefast/di 0.9.0 → 0.10.0

package/dist/container/binding-builders.js

@@ -1,8 +1,8 @@
-import { clearBindingFrame, createBinding, createBindingSlot, DEFAULT_BINDING_SLOT, refinableFields, } from "#/core/binding";
+import { clearBindingFrame, createBindingSlot, DEFAULT_BINDING_SLOT, generateBindingId, NO_INSTANCE, } from "#/core/binding";
 import { mergingConstraintRequirements } from "#/core/constraint-requirement";
 import { slotName } from "#/core/tag";
 import { tokenName } from "#/core/token";
-import { ChainNotRegisteredError, SelfBindingRequiresClassError } from "#/errors/errors";
+import { ChainAlreadyRegisteredError, ChainNotRegisteredError, ManyBindingSlotError, SelfBindingRequiresClassError, } from "#/errors/errors";
 import { normalizeToDescriptor } from "#/injection/descriptor";
 /** One criterion per key: re-tagging the same key replaces it rather than asking for both values. */
 function updateSlotTag(slot, criterion) {
@@ -16,112 +16,139 @@ function updateSlotTag(slot, criterion) {
     }
     return createBindingSlot(tags);
 }
-/** Record a module's binding id, dropping the id the chain re-slotted away from. */
-function trackBindingForModule(ids, id, previousId) {
-    if (previousId !== undefined) {
-        const previousIndex = ids.indexOf(previousId);
-        if (previousIndex !== -1) {
-            ids.splice(previousIndex, 1);
-        }
-    }
-    ids.push(id);
-}
 // ── BindingChain ─────────────────────────────────────────────────────────────────────────────────────────────────────
 /**
- * The one builder behind `bind()` and every `to*()` return type. Each interface exposes only the
- * calls that are legal at that point in the chain; the runtime object is shared because every
- * refinement is the same operation — narrow the registered binding, keep its id.
+ * The one builder behind `bind()` and every `to*()` return type — and the binding it registers.
+ *
+ * @remarks The binding fields come first, in the order every binding shares, and the chain's own
+ * bookkeeping follows as private fields; `to*()` fills the fields in place and hands this object to
+ * the registry, so a plain bind is one allocation. Refinements write the registered object: a scope
+ * or hook in place, a slot or predicate through the registry so its indexes follow.
  *
  * @since 0.5.0-canary.8
  */
 export class BindingChain {
-    // Undefined until a `to*()` call registers the binding.
-    #binding;
+    // The binding. Every field, every kind, written in this order and nowhere else: one hidden class.
+    kind = "constant";
+    identifier = generateBindingId();
+    inFlight = false;
+    frame = undefined;
+    instance = NO_INSTANCE;
+    token;
+    slot = DEFAULT_BINDING_SLOT;
+    predicate = undefined;
+    isMany = false;
+    scope = "singleton";
+    target = undefined;
+    factory = undefined;
+    deps = undefined;
+    value = undefined;
+    activationHook = undefined;
+    deactivationHook = undefined;
+    // The chain. Set by the first `to*()`, which is the only one a chain accepts.
+    #isRegistered = false;
     // Allocated only by a chain that actually displaces something — most never do.
     #displacedByChain;
     // Registry version after this chain's last write — a mismatch means someone else wrote in between.
     #versionAfterLastWrite = -1;
-    #token;
     #registration;
     constructor(token, registration) {
-        this.#token = token;
+        this.token = token;
         this.#registration = registration;
     }
-    /** The registered binding, or a loud failure if no `to*()` has run yet. */
-    #registered() {
-        if (this.#binding === undefined) {
-            throw new ChainNotRegisteredError(tokenName(this.#token));
+    /** This object as the registry and the resolver see it: the value type erased once, here. */
+    get #binding() {
+        return this;
+    }
+    /** Loud failure for a refinement before `to*()`. */
+    #requireRegistered() {
+        if (!this.#isRegistered) {
+            throw new ChainNotRegisteredError(tokenName(this.token));
         }
-        return this.#binding;
-    }
-    #register(partial) {
-        // Each `to*()` starts its own registration, so anything a previous one displaced is not this
-        // registration's to restore.
-        this.#displacedByChain = undefined;
-        this.#binding = createBinding(partial, this.#token, DEFAULT_BINDING_SLOT, undefined);
-        this.#commit(this.#binding, undefined);
+    }
+    /** Loud failure for a second `to*()`, raised before the first one's fields can be overwritten. */
+    #requireUnregistered() {
+        if (this.#isRegistered) {
+            throw new ChainAlreadyRegisteredError(tokenName(this.token));
+        }
+    }
+    #register(kind, scope) {
+        this.kind = kind;
+        this.scope = scope;
+        this.#isRegistered = true;
+        this.#commit(undefined);
         return this;
     }
     // ── Registration ───────────────────────────────────────────────────────────────────────────────────────────────────
     to(type) {
-        return this.#register({ kind: "class", target: type, scope: "transient" });
+        this.#requireUnregistered();
+        this.target = type;
+        return this.#register("class", "transient");
     }
     toSelf() {
-        if (typeof this.#token !== "function") {
-            throw new SelfBindingRequiresClassError(tokenName(this.#token));
+        this.#requireUnregistered();
+        if (typeof this.token !== "function") {
+            throw new SelfBindingRequiresClassError(tokenName(this.token));
         }
-        return this.#register({ kind: "class", target: this.#token, scope: "transient" });
+        this.target = this.token;
+        return this.#register("class", "transient");
     }
     toConstantValue(value) {
-        return this.#register({ kind: "constant", scope: "singleton", value });
+        this.#requireUnregistered();
+        this.value = value;
+        return this.#register("constant", "singleton");
     }
     toDynamic(factory) {
-        return this.#register({ kind: "dynamic", factory, scope: "transient" });
+        this.#requireUnregistered();
+        this.factory = factory;
+        return this.#register("dynamic", "transient");
     }
     toDynamicAsync(factory) {
-        return this.#register({ kind: "dynamic-async", factory, scope: "transient" });
+        this.#requireUnregistered();
+        this.factory = factory;
+        return this.#register("dynamic-async", "transient");
     }
     toResolved(factory, deps) {
-        return this.#register({
-            kind: "resolved",
-            deps: deps.map((dependency) => normalizeToDescriptor(dependency)),
-            factory: factory,
-            scope: "transient",
-        });
+        this.#requireUnregistered();
+        this.factory = factory;
+        this.deps = deps.map((dependency) => normalizeToDescriptor(dependency));
+        return this.#register("resolved", "transient");
     }
     toResolvedAsync(factory, deps) {
-        return this.#register({
-            kind: "resolved-async",
-            deps: deps.map((dependency) => normalizeToDescriptor(dependency)),
-            factory: factory,
-            scope: "transient",
-        });
+        this.#requireUnregistered();
+        this.factory = factory;
+        this.deps = deps.map((dependency) => normalizeToDescriptor(dependency));
+        return this.#register("resolved-async", "transient");
     }
     toAlias(target) {
-        return this.#register({ kind: "alias", scope: "transient", target });
+        this.#requireUnregistered();
+        this.target = target;
+        return this.#register("alias", "transient");
     }
     // ── Refinement ─────────────────────────────────────────────────────────────────────────────────────────────────────
-    // Slot and predicate are what the registry indexes on, so a re-slot rebuilds the binding and
-    // re-registers it — under the original id, keeping `id()` stable for the whole chain.
+    // Slot and predicate are what the registry indexes on, so a re-slot takes the binding out of the
+    // registry, rewrites the two fields while it is out, and registers it again — same object, same id.
     #reslot(slot, predicate) {
-        const previous = this.#registered();
-        this.#binding = createBinding(previous, previous.token, slot, predicate, previous.id);
-        this.#commit(this.#binding, previous.id);
-        // The tracked-singleton list holds object references, and the re-slot just replaced the object.
-        this.#registration.scope.replaceSingleton(previous, this.#binding);
+        this.#requireRegistered();
+        this.#commit(() => {
+            this.slot = slot;
+            this.predicate = predicate;
+            // The frame reports the slot, so a resolve before this call memoized the previous one.
+            clearBindingFrame(this.#binding);
+        });
         return this;
     }
     #withScope(scope) {
-        const binding = this.#registered();
-        if (binding.scope !== scope) {
+        this.#requireRegistered();
+        if (this.scope !== scope) {
             // An instance cached under the old scope must not survive the change — a later flip back
             // to that scope would resurrect it.
-            this.#registration.scope.deleteSingleton(binding);
-            this.#registration.scope.deleteScoped(binding.id);
-            refinableFields(binding).scope = scope;
+            this.#registration.scope.deleteSingleton(this.#binding);
+            this.#registration.scope.deleteScoped(this.identifier);
+            this.scope = scope;
         }
         // The frame reports the scope, so a resolve before this call memoized the previous one.
-        clearBindingFrame(binding);
+        clearBindingFrame(this.#binding);
         this.#registration.registry.touch();
         this.#versionAfterLastWrite = this.#registration.registry.version;
         return this;
@@ -129,26 +156,60 @@ export class BindingChain {
     // SPEC calls a candidate a binding that passes *all* of a chain's predicates, and the chain type
     // reads as refinement, so a second `when()` narrows rather than replaces.
     when(predicate) {
-        const binding = this.#registered();
-        const previous = binding.predicate;
-        if (previous === undefined) {
-            return this.#reslot(binding.slot, predicate);
-        }
+        this.#requireRegistered();
+        const previous = this.predicate;
         // The composite carries both sides' requirements, so validate() still sees them.
-        const composed = mergingConstraintRequirements((ctx) => previous(ctx) && predicate(ctx), previous, predicate);
-        return this.#reslot(binding.slot, composed);
+        const narrowed = previous === undefined
+            ? predicate
+            : mergingConstraintRequirements((ctx) => previous(ctx) && predicate(ctx), previous, predicate);
+        const { registry } = this.#registration;
+        // The slot is unchanged, so nothing has to be re-indexed or displaced. With the last registry
+        // write this chain's own and nothing parked, the binding is provably live and is rewritten in
+        // place; otherwise the re-slot path re-checks liveness and restores what the shape frees.
+        if (registry.version === this.#versionAfterLastWrite && this.#displacedByChain === undefined) {
+            registry.setPredicate(this.#binding, narrowed);
+            this.#versionAfterLastWrite = registry.version;
+            return this;
+        }
+        return this.#reslot(this.slot, narrowed);
     }
     whenNamed(name) {
         return this.whenTagged(slotName.of(name));
     }
     whenTagged(criterion) {
-        const binding = this.#registered();
-        return this.#reslot(updateSlotTag(binding.slot, criterion), binding.predicate);
+        this.#requireRegistered();
+        if (this.isMany) {
+            throw new ManyBindingSlotError(tokenName(this.token));
+        }
+        return this.#reslot(updateSlotTag(this.slot, criterion), this.predicate);
+    }
+    many() {
+        this.#requireRegistered();
+        if (this.slot.tags.length !== 0) {
+            throw new ManyBindingSlotError(tokenName(this.token));
+        }
+        if (this.isMany) {
+            return this;
+        }
+        const { registry } = this.#registration;
+        // With the last registry write this chain's own and nothing parked, the binding is provably live
+        // and displaced nobody, so membership is written in place and the registry only moves it out of
+        // the lone map. Otherwise it goes through the re-slot path, which re-checks liveness and restores
+        // an ordinary binding this chain's `to*()` displaced, now that the member frees its slot.
+        if (registry.version === this.#versionAfterLastWrite && this.#displacedByChain === undefined) {
+            registry.setMany(this.#binding);
+            this.#versionAfterLastWrite = registry.version;
+            return this;
+        }
+        this.#commit(() => {
+            this.isMany = true;
+        });
+        return this;
     }
     whenDefault() {
         // The default slot is what a fresh registration already has, so there is nothing to re-slot —
         // but an unregistered chain must fail here exactly as it does in every other refinement.
-        this.#registered();
+        this.#requireRegistered();
         return this;
     }
     singleton() {
@@ -161,40 +222,42 @@ export class BindingChain {
         return this.#withScope("scoped");
     }
     onActivation(fn) {
-        refinableFields(this.#registered()).onActivation = fn;
+        this.#requireRegistered();
+        this.activationHook = fn;
         this.#registration.registry.touch();
         this.#versionAfterLastWrite = this.#registration.registry.version;
         return this;
     }
     onDeactivation(fn) {
-        refinableFields(this.#registered()).onDeactivation = fn;
+        this.#requireRegistered();
+        this.deactivationHook = fn;
         this.#registration.registry.touch();
         this.#versionAfterLastWrite = this.#registration.registry.version;
         return this;
     }
     id() {
-        return this.#registered().id;
+        this.#requireRegistered();
+        return this.identifier;
     }
     // ── Registry ───────────────────────────────────────────────────────────────────────────────────────────────────────
     /**
-     * Registers `binding`, first removing `previousId` when the chain is re-slotting.
+     * Registers this binding; with `rewrite` given, first takes the live binding out, rewrites it, and
+     * registers it again.
      *
      * @remarks A `when*()` that follows `to*()` re-slots an already-live binding and can displace one
      * the final shape would never conflict with. Those stay parked in `#displacedByChain` until the
      * chain settles, then get restored.
      */
-    #commit(binding, previousId) {
+    #commit(rewrite) {
         const { registry, moduleBindingIds } = this.#registration;
-        // The registry is heterogeneous by design — one instance holds every value type — so the
-        // chain's `Binding<Value>` is erased once, here, rather than at each call site.
-        const registered = binding;
-        if (previousId !== undefined) {
+        const registered = this.#binding;
+        if (rewrite !== undefined) {
             // A registry someone else wrote since this chain's last write invalidates the parked
             // snapshot: restoring it could undo an unbind or shadow a newer binding.
             if (registry.version !== this.#versionAfterLastWrite) {
                 this.#displacedByChain = undefined;
             }
-            if (registry.removeById(previousId) === undefined) {
+            if (!registry.reslot(registered, rewrite)) {
                 // The chain's binding is no longer live (unbound or displaced) — a refinement must not
                 // resurrect it, so the chain goes inert against the registry.
                 this.#displacedByChain = undefined;
@@ -202,15 +265,20 @@ export class BindingChain {
                 return;
             }
         }
+        else {
+            // Each `to*()` starts its own registration, so anything a previous one displaced is not this
+            // registration's to restore.
+            this.#displacedByChain = undefined;
+        }
         const displaced = registry.add(registered);
         if (displaced !== undefined) {
             (this.#displacedByChain ??= []).push(displaced);
         }
-        if (previousId !== undefined && this.#displacedByChain !== undefined) {
+        if (rewrite !== undefined && this.#displacedByChain !== undefined) {
             this.#restoreNonConflicting(this.#displacedByChain);
         }
-        if (moduleBindingIds !== undefined) {
-            trackBindingForModule(moduleBindingIds, registered.id, previousId);
+        if (rewrite === undefined && moduleBindingIds !== undefined) {
+            moduleBindingIds.push(this.identifier);
         }
         this.#versionAfterLastWrite = registry.version;
     }

package/dist/container/container.d.ts

@@ -30,8 +30,8 @@ export interface Container {
     resolveAsync<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<ResolveOptions<Names>>): Promise<Value>;
     resolveOptional<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<ResolveOptions<Names>>): Value | undefined;
     resolveOptionalAsync<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<ResolveOptions<Names>>): Promise<Value | undefined>;
-    resolveAll<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<ResolveOptions<Names>>): Array<Value>;
-    resolveAllAsync<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<ResolveOptions<Names>>): Promise<Array<Value>>;
+    resolveAll<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<ResolveOptions<Names>>): ReadonlyArray<Value>;
+    resolveAllAsync<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<ResolveOptions<Names>>): Promise<ReadonlyArray<Value>>;
     createChild(): Container;
     dispose(): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;

package/dist/container/container.js

@@ -45,6 +45,7 @@ const APPLY_BINDING_SCOPE = {
         builder.transient();
     },
 };
+const NO_DEACTIVATION_PAIRS = Object.freeze([]);
 // ── DefaultContainer ─────────────────────────────────────────────────────────────────────────────────────────────────
 class DefaultContainer {
     #disposed = false;
@@ -74,6 +75,7 @@ class DefaultContainer {
         return (this.#inspector ??= new Inspector(this.#registry, this.#scope, this.#parent !== undefined, () => this.#disposed));
     }
     [RESOLUTION_DIAGNOSTICS]() {
+        const resolverCaches = this.#resolver.describeCaches();
         const builtSubsystems = [];
         if (this.#inspector !== undefined) {
             builtSubsystems.push("container.inspector");
@@ -81,6 +83,12 @@ class DefaultContainer {
         if (this.#moduleRefs !== undefined || this.#moduleBindingIds !== undefined) {
             builtSubsystems.push("container.moduleTables");
         }
+        if (this.#registry.isRecordMapBuilt) {
+            builtSubsystems.push("registry.records");
+        }
+        if (this.#registry.isIdIndexBuilt) {
+            builtSubsystems.push("registry.idIndex");
+        }
         if (this.#registry.isTaggedIndexBuilt) {
             builtSubsystems.push("registry.taggedIndex");
         }
@@ -90,7 +98,8 @@ class DefaultContainer {
         if (this.#lifecycle.isActivationTableBuilt) {
             builtSubsystems.push("lifecycle.activationHooks");
         }
-        return { ...this.#resolver.describeCaches(), scopedInstanceCount: this.#scope.scopedCount, builtSubsystems };
+        builtSubsystems.push(...resolverCaches.builtSubsystems);
+        return { ...resolverCaches, scopedInstanceCount: this.#scope.scopedCount, builtSubsystems };
     }
     #initResolver(configuredReader) {
         const parent = this.#parent;
@@ -100,7 +109,7 @@ class DefaultContainer {
     }
     /** What a container being constructed under this one inherits: a reader bound here, else this one's. */
     #readerForChild() {
-        if (this.#registry.getAll(MetadataReaderToken).length > 0) {
+        if (this.#registry.has(MetadataReaderToken)) {
             try {
                 return this.#resolver.resolve(MetadataReaderToken, undefined, []);
             }
@@ -144,9 +153,9 @@ class DefaultContainer {
     }
     /** Remove bindings from registry + scope and collect [binding, instance] pairs for deactivation. */
     #collectDeactivationPairs(tokenOrId) {
-        if (typeof tokenOrId === "string") {
+        if (typeof tokenOrId === "number") {
             const binding = this.#registry.removeById(tokenOrId);
-            return binding === undefined ? [] : this.#drainSingletons([binding]);
+            return binding === undefined ? NO_DEACTIVATION_PAIRS : this.#drainSingletons([binding]);
         }
         // Dropping the whole token in one pass: removing each binding by id instead would re-scan and
         // re-index the token's binding list once per binding.
@@ -154,18 +163,20 @@ class DefaultContainer {
     }
     /** Drain scope entries for already-removed bindings, and pair each one that still owes a deactivation. */
     #drainSingletons(bindings) {
-        const pairs = [];
+        // Allocated by the first pair owed: an unbind or rebind of a binding nothing ever cached — the
+        // hot-swap shape — owes no deactivation and hands the shared empty list back.
+        let pairs;
         for (const binding of bindings) {
             if (binding.instance !== NO_INSTANCE) {
-                pairs.push([binding, binding.instance]);
+                (pairs ??= []).push([binding, binding.instance]);
                 this.#scope.deleteSingleton(binding);
             }
             else if (this.#owesConstantDeactivation(binding)) {
-                pairs.push([binding, binding.value]);
+                (pairs ??= []).push([binding, binding.value]);
             }
-            this.#scope.deleteScoped(binding.id);
+            this.#scope.deleteScoped(binding.identifier);
         }
-        return pairs;
+        return pairs ?? NO_DEACTIVATION_PAIRS;
     }
     /**
      * Whether a constant still owes its deactivation.
@@ -176,7 +187,7 @@ class DefaultContainer {
      */
     #owesConstantDeactivation(binding) {
         return (binding.kind === "constant" &&
-            (binding.onDeactivation !== undefined || this.#lifecycle.hasDeactivationHandlers(binding.token)));
+            (binding.deactivationHook !== undefined || this.#lifecycle.hasDeactivationHandlers(binding.token)));
     }
     /** Runs every pair's deactivation even when one throws, then reports what threw. */
     #deactivatePairsSync(pairs) {
@@ -445,12 +456,18 @@ class DefaultContainer {
     resolveAll(token, options) {
         this.#assertNotDisposed();
         const rootStack = this.#resolver.rootStack;
+        if (options === undefined && rootStack.length === 0) {
+            return this.#resolver.resolveRootCollection(token);
+        }
         return rootStack.length === 0
             ? this.#resolver.resolveAll(token, options, rootStack)
             : this.#resolver.resolveAll(token, options, []);
     }
     resolveAllAsync(token, options) {
         this.#assertNotDisposed();
+        if (options === undefined) {
+            return this.#resolver.resolveRootCollectionAsync(token);
+        }
         return this.#resolver.resolveAllAsync(token, options, [], ROOT_BRANCH);
     }
     // ── Child ──────────────────────────────────────────────────────────────────────────────────────────────────────────
@@ -523,7 +540,7 @@ class DefaultContainer {
                 // A constant is already its own instance, so only an activation hook gives the warm-up
                 // something to run — and a container-level hook counts as one just as a per-binding hook does.
                 if (binding.kind === "constant" &&
-                    binding.onActivation === undefined &&
+                    binding.activationHook === undefined &&
                     !this.#lifecycle.hasActivationHandlers(binding.token)) {
                     continue;
                 }
@@ -607,11 +624,11 @@ class DefaultContainer {
     #validateSingletonBindingGraph(root, reader) {
         const rootName = tokenName(root.token);
         const dfs = (current, pathNames, pathBindingIds) => {
-            if (pathBindingIds.has(current.id)) {
+            if (pathBindingIds.has(current.identifier)) {
                 return;
             }
             const extendedPathIds = new Set(pathBindingIds);
-            extendedPathIds.add(current.id);
+            extendedPathIds.add(current.identifier);
             for (const edge of this.#collectStaticDependencyEdges(current, reader)) {
                 const { terminal, depTokenName } = edge;
                 const depScope = this.#validationScopeFromTerminal(terminal);
@@ -649,10 +666,10 @@ class DefaultContainer {
         const seenAliasIds = new Set();
         let current = binding;
         while (current !== undefined && current.kind === "alias") {
-            if (seenAliasIds.has(current.id)) {
+            if (seenAliasIds.has(current.identifier)) {
                 throw new CircularDependencyError(cyclePath);
             }
-            seenAliasIds.add(current.id);
+            seenAliasIds.add(current.identifier);
             cyclePath.push(tokenName(current.token));
             const nextToken = current.target;
             const next = this.#resolver.peekBindingForValidate(nextToken, options);
@@ -701,7 +718,7 @@ class DefaultContainer {
     // ── Introspection ──────────────────────────────────────────────────────────────────────────────────────────────────
     has(token, options) {
         this.#assertNotDisposed();
-        return this.#getInspector().has(token, options, () => this.#parent?.has(token, options) ?? false);
+        return this.#getInspector().hasOwn(token, options) || (this.#parent?.has(token, options) ?? false);
     }
     hasOwn(token, options) {
         this.#assertNotDisposed();