@codefast/di 0.10.0 → 0.11.0

package/dist/lifecycle/scope-manager.js

@@ -1,6 +1,6 @@
-import { NO_INSTANCE } from "#/core/binding";
-import { tokenName } from "#/core/token";
-import { MissingScopeContextError } from "#/errors/errors";
+import { NO_INSTANCE } from "#core/binding";
+import { tokenName } from "#core/token";
+import { MissingScopeContextError } from "#errors/errors";
 /**
  * One container's instance caches — singletons, in-flight async creations, and the scoped cache.
  *
@@ -39,22 +39,39 @@ export class ScopeManager {
         }
         binding.instance = instance;
     }
+    // A removal only clears the instance; the list keeps its entry until a read compacts it, so a
+    // teardown of a hundred singletons is a hundred field writes, not a hundred splices.
+    #compacted = true;
     /** Every binding in this container holding a cached singleton. */
     cachedSingletons() {
-        return this.#singletonBindings ?? EMPTY_BINDINGS;
+        const tracked = this.#singletonBindings;
+        if (tracked === undefined) {
+            return EMPTY_BINDINGS;
+        }
+        if (!this.#compacted) {
+            // Latest materialization wins the position: walk from the end keeping each live binding once.
+            const seen = new Set();
+            const live = [];
+            for (let index = tracked.length - 1; index >= 0; index -= 1) {
+                const binding = tracked[index];
+                if (binding.instance !== NO_INSTANCE && !seen.has(binding)) {
+                    seen.add(binding);
+                    live.push(binding);
+                }
+            }
+            live.reverse();
+            this.#singletonBindings = live;
+            this.#compacted = true;
+            return live;
+        }
+        return tracked;
     }
     deleteSingleton(binding) {
         if (binding.instance === NO_INSTANCE) {
             return false;
         }
         binding.instance = NO_INSTANCE;
-        const tracked = this.#singletonBindings;
-        if (tracked !== undefined) {
-            const index = tracked.indexOf(binding);
-            if (index !== -1) {
-                tracked.splice(index, 1);
-            }
-        }
+        this.#compacted = false;
         return true;
     }
     /** Swaps a re-slotted binding's tracked entry, so teardown pairs the instance with the live object. */
@@ -112,10 +129,11 @@ export class ScopeManager {
     clearAll() {
         const tracked = this.#singletonBindings;
         if (tracked !== undefined) {
-            for (const binding of tracked) {
-                binding.instance = NO_INSTANCE;
+            for (let index = 0; index < tracked.length; index += 1) {
+                tracked[index].instance = NO_INSTANCE;
             }
             tracked.length = 0;
+            this.#compacted = true;
         }
         this.#inflight?.clear();
         this.#scoped?.clear();

package/dist/metadata/metadata-reader-token.d.ts

@@ -1,5 +1,5 @@
-import type { Token } from "#/core/token";
-import type { MetadataReader } from "#/metadata/metadata-types";
+import type { Token } from "#core/token";
+import type { MetadataReader } from "#metadata/metadata-types";
 /**
  * The token a custom `MetadataReader` is bound to for a container to pick up.
  *

package/dist/metadata/metadata-reader-token.js

@@ -1,4 +1,4 @@
-import { token } from "#/core/token";
+import { token } from "#core/token";
 /**
  * The token a custom `MetadataReader` is bound to for a container to pick up.
  *

package/dist/metadata/metadata-types.d.ts

@@ -1,6 +1,6 @@
-import type { Constructor } from "#/core/types";
-import type { InjectionDescriptor } from "#/injection/descriptor";
-import type { DependencySlot } from "#/injection/resolve-options";
+import type { Constructor } from "#core/types";
+import type { InjectionDescriptor } from "#injection/descriptor";
+import type { DependencySlot } from "#injection/resolve-options";
 /**
  * One constructor parameter's declaration.
  *

package/dist/metadata/symbol-metadata-reader.d.ts

@@ -1,6 +1,6 @@
-import type { Constructor } from "#/core/types";
-import type { InjectionDescriptor } from "#/injection/descriptor";
-import type { ConstructorMetadata, LifecycleMetadata, MetadataReader } from "#/metadata/metadata-types";
+import type { Constructor } from "#core/types";
+import type { InjectionDescriptor } from "#injection/descriptor";
+import type { ConstructorMetadata, LifecycleMetadata, MetadataReader } from "#metadata/metadata-types";
 type AccessorEntry = {
     readonly key: string | symbol;
     readonly descriptor: InjectionDescriptor;

package/dist/metadata/symbol-metadata-reader.js

@@ -1,4 +1,4 @@
-import { INJECT_ACCESSOR_KEY, INJECTABLE_KEY, LIFECYCLE_KEY, METADATA_SYMBOL } from "#/metadata/metadata-keys";
+import { INJECT_ACCESSOR_KEY, INJECTABLE_KEY, LIFECYCLE_KEY, METADATA_SYMBOL } from "#metadata/metadata-keys";
 /**
  * The default `MetadataReader`, reading decorator metadata stored under `Symbol.metadata`.
  *

package/dist/metadata/verifying-metadata-reader.d.ts

@@ -1,14 +1,15 @@
 /**
  * Wraps a foreign {@link MetadataReader} so its answers are verified before anything dereferences
- * them.
+ * them, and asked for once per class.
  */
-import type { MetadataReader } from "#/metadata/metadata-types";
+import type { MetadataReader } from "#metadata/metadata-types";
 /**
- * The reader a container should hand its resolver: verified when it came from outside.
+ * The reader a container should hand its resolver: verified and memoized when it came from outside.
  *
  * @remarks The decorator reader writes the metadata it later reads, so there is nothing to check and
  * nothing to pay — a container that supplies no reader of its own is left on the same code path it
- * has always taken. A supplied reader is a claim, and only its callers can be charged for checking.
+ * has always taken. A supplied reader is a claim, and only its callers can be charged for checking;
+ * it is asked about a class once, however many containers read through it.
  *
  * @since 0.6.0
  */

package/dist/metadata/verifying-metadata-reader.js

@@ -1,17 +1,34 @@
 /**
  * Wraps a foreign {@link MetadataReader} so its answers are verified before anything dereferences
- * them.
+ * them, and asked for once per class.
  */
-import { defaultMetadataReader } from "#/metadata/symbol-metadata-reader";
-import { verifyAccessorMetadata, verifyConstructorMetadata, verifyLifecycleMetadata, } from "#/resolution/cache/class-introspector";
+import { defaultMetadataReader } from "#metadata/symbol-metadata-reader";
+import { verifyAccessorMetadata, verifyConstructorMetadata, verifyLifecycleMetadata, } from "#resolution/cache/class-introspector";
 // Wrapping a wrapper would stack a layer per child container, so each one is remembered.
 const verifyingReaders = new WeakSet();
+// One wrapper per foreign reader, so every container handed that reader shares its answers.
+const wrapperByReader = new WeakMap();
+// `null` records a verified "no metadata", so an absent answer is not asked for again either.
+function memoized(ask) {
+    const answers = new WeakMap();
+    return (target) => {
+        const known = answers.get(target);
+        if (known !== undefined) {
+            return known === null ? undefined : known;
+        }
+        // Stored only after `ask` returns, so an answer that fails verification is asked for, and fails, again.
+        const answer = ask(target);
+        answers.set(target, answer ?? null);
+        return answer;
+    };
+}
 /**
- * The reader a container should hand its resolver: verified when it came from outside.
+ * The reader a container should hand its resolver: verified and memoized when it came from outside.
  *
  * @remarks The decorator reader writes the metadata it later reads, so there is nothing to check and
  * nothing to pay — a container that supplies no reader of its own is left on the same code path it
- * has always taken. A supplied reader is a claim, and only its callers can be charged for checking.
+ * has always taken. A supplied reader is a claim, and only its callers can be charged for checking;
+ * it is asked about a class once, however many containers read through it.
  *
  * @since 0.6.0
  */
@@ -19,13 +36,18 @@ export function verifyingMetadataReader(reader) {
     if (reader === defaultMetadataReader || verifyingReaders.has(reader)) {
         return reader;
     }
+    const existing = wrapperByReader.get(reader);
+    if (existing !== undefined) {
+        return existing;
+    }
     const verifying = {
-        getConstructorMetadata: (target) => verifyConstructorMetadata(reader, target),
-        getLifecycleMetadata: (target) => verifyLifecycleMetadata(reader, target),
+        getConstructorMetadata: memoized((target) => verifyConstructorMetadata(reader, target)),
+        getLifecycleMetadata: memoized((target) => verifyLifecycleMetadata(reader, target)),
         ...(reader.getAccessorMetadata === undefined
             ? {}
-            : { getAccessorMetadata: (target) => verifyAccessorMetadata(reader, target) }),
+            : { getAccessorMetadata: memoized((target) => verifyAccessorMetadata(reader, target)) }),
     };
     verifyingReaders.add(verifying);
+    wrapperByReader.set(reader, verifying);
     return verifying;
 }

package/dist/resolution/async-fan-out.d.ts

@@ -0,0 +1,12 @@
+/** Settles the concurrent dependencies of one async level and reports a failure in declaration order. */
+/**
+ * Applies `apply` to every dependency's settled value, or rejects with the first failure in declaration order.
+ *
+ * @remarks Siblings start concurrently, and `Promise.all` alone would report whichever rejection
+ * settles first — a fact about microtask depth, not about the graph. The synchronous lanes report
+ * the first failing dependency in declaration order, so this does too: the happy path is `Promise.all`,
+ * and only a failure waits for every sibling to settle and then picks the earliest one that did not.
+ *
+ * @since 0.11.0
+ */
+export declare function settleInOrder<Result>(pending: ReadonlyArray<unknown>, apply: (values: Array<unknown>) => Result): Promise<Result>;

package/dist/resolution/async-fan-out.js

@@ -0,0 +1,26 @@
+/** Settles the concurrent dependencies of one async level and reports a failure in declaration order. */
+/**
+ * Applies `apply` to every dependency's settled value, or rejects with the first failure in declaration order.
+ *
+ * @remarks Siblings start concurrently, and `Promise.all` alone would report whichever rejection
+ * settles first — a fact about microtask depth, not about the graph. The synchronous lanes report
+ * the first failing dependency in declaration order, so this does too: the happy path is `Promise.all`,
+ * and only a failure waits for every sibling to settle and then picks the earliest one that did not.
+ *
+ * @since 0.11.0
+ */
+export function settleInOrder(pending, apply) {
+    return Promise.all(pending).then(apply, () => firstRejectionInOrder(pending));
+}
+function firstRejectionInOrder(pending) {
+    return Promise.allSettled(pending).then((results) => {
+        for (let index = 0; index < results.length; index += 1) {
+            const result = results[index];
+            if (result.status === "rejected") {
+                throw result.reason;
+            }
+        }
+        // Unreachable: this branch only runs once `Promise.all` has rejected, so a rejection is settled.
+        throw new Error("settleInOrder: a rejected fan-out settled with no rejection");
+    });
+}

package/dist/resolution/cache/activation-need.d.ts

@@ -4,10 +4,10 @@
  * @remarks Versioned on the lifecycle manager plus the own registry, since `onActivation` can be
  * registered at any time and a rebind mints binding ids the memo must not keep forever.
  */
-import type { Binding } from "#/core/binding";
-import type { BindingRegistry } from "#/core/registry";
-import type { LifecycleManager } from "#/lifecycle/lifecycle-manager";
-import type { ClassIntrospector } from "#/resolution/cache/class-introspector";
+import type { Binding } from "#core/binding";
+import type { BindingRegistry } from "#core/registry";
+import type { LifecycleManager } from "#lifecycle/lifecycle-manager";
+import type { ClassIntrospector } from "#resolution/cache/class-introspector";
 /**
  * A per-binding cache of whether activation work — hooks or `@postConstruct` — is needed on resolve.
  *
@@ -17,7 +17,6 @@ export declare class ActivationNeedCache {
     #private;
     constructor(lifecycle: LifecycleManager, classes: ClassIntrospector, registry: BindingRegistry);
     /** Whether an answer the early returns could not give has had to allocate the memo. */
-    get isMemoBuilt(): boolean;
     needsActivation<Value>(binding: Binding<Value>): boolean;
     /**
      * Settles a class binding's answer once its lifecycle metadata has actually been read, which

package/dist/resolution/cache/activation-need.js

@@ -1,13 +1,10 @@
+import { NO_ACTIVATION_STAMP } from "#core/binding";
 /**
  * A per-binding cache of whether activation work — hooks or `@postConstruct` — is needed on resolve.
  *
  * @since 0.5.0-canary.8
  */
 export class ActivationNeedCache {
-    // Allocated by the first answer the early returns cannot give, so a hook-free container that
-    // resolves no class or alias never pays for it.
-    #needByBindingId;
-    #version = -1;
     #lifecycle;
     #classes;
     #registry;
@@ -17,9 +14,6 @@ export class ActivationNeedCache {
         this.#registry = registry;
     }
     /** Whether an answer the early returns could not give has had to allocate the memo. */
-    get isMemoBuilt() {
-        return this.#needByBindingId !== undefined;
-    }
     needsActivation(binding) {
         // The chain writes a binding's own hook in place with no version anything here can see, so it
         // is read fresh on every call; the memo covers only container hooks and lifecycle metadata.
@@ -32,19 +26,18 @@ export class ActivationNeedCache {
         if (lifecycleVersion === 0 && binding.kind !== "class" && binding.kind !== "alias") {
             return false;
         }
-        // The registry version evicts entries for binding ids a rebind has retired.
-        const version = lifecycleVersion + this.#registry.version;
-        if (this.#version !== version) {
-            this.#needByBindingId?.clear();
-            this.#version = version;
+        // The stamp is the version pair the answer was computed under, doubled, plus the answer: a
+        // registry or lifecycle mutation moves the version and retires every stamp at once.
+        const stampBase = (lifecycleVersion + this.#registry.version) * 2;
+        const stamp = binding.activationStamp;
+        if (stamp === stampBase) {
+            return false;
         }
-        const memo = (this.#needByBindingId ??= new Map());
-        const cached = memo.get(binding.identifier);
-        if (cached !== undefined) {
-            return cached;
+        if (stamp === stampBase + 1) {
+            return true;
         }
         const needsActivation = binding.kind === "class" ? this.#classNeedsActivation(binding) : this.#nonClassNeedsActivation(binding);
-        memo.set(binding.identifier, needsActivation);
+        binding.activationStamp = needsActivation ? stampBase + 1 : stampBase;
         return needsActivation;
     }
     /**
@@ -59,7 +52,7 @@ export class ActivationNeedCache {
             return needsActivation;
         }
         this.#classes.discoverPostConstruct(binding.target);
-        this.#needByBindingId?.delete(binding.identifier);
+        binding.activationStamp = NO_ACTIVATION_STAMP;
         return this.needsActivation(binding);
     }
     // Own hooks are answered before the memo, so both computations cover the memoizable rest only.

package/dist/resolution/cache/binding-lookup-cache.d.ts

@@ -4,11 +4,11 @@
  * @remarks Each cache links to its parent's, so a child answers from its own chain without walking
  * the container hierarchy again.
  */
-import type { Binding } from "#/core/binding";
-import type { BindingRegistry } from "#/core/registry";
-import type { BindingTag } from "#/core/tag";
-import type { Token } from "#/core/token";
-import type { Constructor } from "#/core/types";
+import type { Binding } from "#core/binding";
+import type { BindingRegistry } from "#core/registry";
+import type { BindingTag } from "#core/tag";
+import type { Token } from "#core/token";
+import type { Constructor } from "#core/types";
 /**
  * A token's terminal binding with alias hops already folded, plus the container that owns it.
  *
@@ -34,13 +34,6 @@ export interface CollectionEntry {
     values: ReadonlyArray<unknown> | undefined;
     activationVersion: number;
 }
-/**
- * Alias folding gives up past this many hops and defers to the full resolve loop, whose
- * Set-based traversal detects genuine cycles exactly rather than by an arbitrary cap.
- *
- * @since 0.5.0-canary.8
- */
-export declare const ALIAS_HOP_LIMIT = 32;
 /**
  * A version-stamped cache of binding lookups by token and criterion across the container chain.
  *

package/dist/resolution/cache/binding-lookup-cache.js

@@ -1,12 +1,5 @@
-import { getOrInsertComputed } from "#/core/map-upsert";
-import { stateEpoch } from "#/core/state-epoch";
-/**
- * Alias folding gives up past this many hops and defers to the full resolve loop, whose
- * Set-based traversal detects genuine cycles exactly rather than by an arbitrary cap.
- *
- * @since 0.5.0-canary.8
- */
-export const ALIAS_HOP_LIMIT = 32;
+import { getOrInsertComputed } from "#core/map-upsert";
+import { stateEpoch } from "#core/state-epoch";
 const newTagToEntryMap = () => new Map();
 const newNameToTagMap = () => new Map();
 /**
@@ -76,15 +69,19 @@ export class BindingLookupCache {
     }
     /** `null` when the token's shape needs the full selection path. */
     defaultEntry(token) {
+        // The repeat hit is the whole method, small enough for a hot caller to inline; the fill is the miss.
+        if (token === this.#lastToken && this.chainVersion() === this.#version) {
+            return this.#lastEntry;
+        }
+        return this.#defaultEntryMiss(token);
+    }
+    #defaultEntryMiss(token) {
         const version = this.chainVersion();
         if (version !== this.#version) {
             this.#byToken?.clear();
             this.#version = version;
             this.#lastToken = undefined;
         }
-        else if (token === this.#lastToken) {
-            return this.#lastEntry;
-        }
         let entry;
         if (this.#lastToken === undefined) {
             // First token this cache generation sees: answer from the walk and defer the map entirely.
@@ -159,7 +156,12 @@ export class BindingLookupCache {
     #findPairInChain(token, nameCriterion, tag) {
         const found = this.#registry.getPairTagged(token, nameCriterion, tag);
         if (found !== undefined) {
-            return found.predicate !== undefined || found.kind === "alias" ? null : { binding: found, owner: this.#owner };
+            // A predicate candidate at this level can win the more-specific rule's first step, which this
+            // lane cannot weigh; an alias carries options through the full path. Either declines to selection.
+            if (found.kind === "alias" || this.#registry.hasPredicateCandidate(token)) {
+                return null;
+            }
+            return { binding: found, owner: this.#owner };
         }
         if (this.#registry.has(token)) {
             return null;
@@ -180,19 +182,30 @@ export class BindingLookupCache {
     rememberCollection(token, entry) {
         (this.#collections ??= new Map()).set(token, entry);
     }
+    /**
+     * Follows alias hops to the terminal entry, or declines with `null` on a cycle, which the full
+     * resolve loop reports.
+     *
+     * @remarks The origin and the current token are compared by hand and the set holds only what lies
+     * between them, so the common one-hop alias allocates nothing and any chain is folded exactly.
+     */
     #foldAliases(token) {
         let current = token;
-        for (let hop = 0; hop < ALIAS_HOP_LIMIT; hop += 1) {
+        let visited;
+        for (;;) {
             const entry = this.#findDefaultInChain(current);
-            if (entry === null) {
+            if (entry === null || entry.binding.kind !== "alias") {
+                return entry;
+            }
+            const next = entry.binding.target;
+            if (next === token || next === current || visited?.has(next) === true) {
                 return null;
             }
-            if (entry.binding.kind !== "alias") {
-                return entry;
+            if (current !== token) {
+                (visited ??= new Set()).add(current);
             }
-            current = entry.binding.target;
+            current = next;
         }
-        return null;
     }
     #findDefaultInChain(token) {
         const fast = this.#registry.getFastDefault(token);

package/dist/resolution/cache/class-introspector.d.ts

@@ -3,11 +3,11 @@
  *
  * @remarks Metadata cannot change once a class is defined, so nothing here needs version stamping.
  */
-import type { AmbientResolution } from "#/ambient/active-container";
-import type { Container } from "#/container/container";
-import type { Constructor } from "#/core/types";
-import type { InjectionDescriptor } from "#/injection/descriptor";
-import type { ConstructorMetadata, LifecycleMetadata, MetadataReader } from "#/metadata/metadata-types";
+import type { AmbientResolution } from "#ambient/active-container";
+import type { Container } from "#container/container";
+import type { Constructor } from "#core/types";
+import type { InjectionDescriptor } from "#injection/descriptor";
+import type { ConstructorMetadata, LifecycleMetadata, MetadataReader } from "#metadata/metadata-types";
 /**
  * A reader's constructor metadata for a class, verified the first time this process asks.
  *
@@ -54,6 +54,17 @@ export declare class ClassIntrospector {
     #private;
     constructor(reader: MetadataReader, container: Container, inherited: ClassIntrospector | undefined);
     constructorMetadata(target: Constructor): ConstructorMetadata | undefined;
+    /**
+     * The nearest ancestor's own constructor metadata, for a subclass that declares none of its own.
+     *
+     * @remarks Constructor metadata is never borrowed down the chain, so a subclass with an implicit
+     * constructor would be built with zero arguments; this lets the resolver name the base whose
+     * declared deps the subclass silently drops.
+     */
+    inheritedConstructorMetadata(target: Constructor): {
+        base: Constructor;
+        metadata: ConstructorMetadata;
+    } | undefined;
     /**
      * Whether the class has a `@postConstruct` hook, or `undefined` until {@link discoverPostConstruct}.
      *