@codefast/di 0.7.0 → 0.8.0

package/dist/resolution/resolver.js

@@ -1,8 +1,8 @@
 import { NO_INSTANCE } from "#/core/binding";
-import { NO_TAG_KEYS } from "#/core/tag";
+import { NO_TAG_KEYS, slotNameCriterionOf } from "#/core/tag";
 import { tokenName } from "#/core/token";
 import { AsyncActivationError, AsyncResolutionError, CircularDependencyError, DisposedContainerError, InternalError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, TokenNotBoundError, } from "#/errors/errors";
-import { isNameOnlyOptions, resolveOptionsForSlot, singleTagOnlyOf } from "#/injection/resolve-options";
+import { resolveOptionsForSlot, singleCriterionForSlot, singleCriterionOnlyOf } from "#/injection/resolve-options";
 import { SCOPED_MISS } from "#/lifecycle/scope-manager";
 import { ActivationNeedCache } from "#/resolution/cache/activation-need";
 import { BindingLookupCache } from "#/resolution/cache/binding-lookup-cache";
@@ -24,6 +24,8 @@ const ROOT_CONSTRAINT_CONTEXT = {
     currentResolveOptions: undefined,
 };
 /**
+ * The resolution engine driving binding selection, instantiation, scoping, and lifecycle hooks.
+ *
  * @since 0.3.16-canary.0
  */
 export class DependencyResolver {
@@ -94,49 +96,47 @@ export class DependencyResolver {
         };
     }
     // ── Binding lookup ─────────────────────────────────────────────────────────────────────────────────────────────────
-    #findBinding(token, options, resolutionStack) {
+    /**
+     * Finds the binding a request selects in this container, walking up to the parent on a miss.
+     *
+     * @remarks `singleCriterion` is the request's lone criterion, folded once by the caller so alias
+     * hops and parent walks do not re-fold it — `undefined` when the request carries none or several.
+     */
+    #findBinding(token, options, resolutionStack, singleCriterion) {
         if (options === undefined) {
             const fastDefaultBinding = this.#registry.getFastDefault(token);
             if (fastDefaultBinding !== undefined) {
                 return { binding: fastDefaultBinding, owner: this };
             }
         }
-        else if (isNameOnlyOptions(options)) {
-            const namedBinding = this.#registry.getSimpleNamed(token, options.name);
-            if (namedBinding !== undefined && this.#matchesBindingFast(namedBinding, options, resolutionStack)) {
-                return { binding: namedBinding, owner: this };
+        else if (singleCriterion !== undefined) {
+            const indexed = this.#registry.getSimpleTagged(token, singleCriterion);
+            if (indexed !== undefined && this.#satisfiesPredicate(indexed, options, resolutionStack)) {
+                return { binding: indexed, owner: this };
             }
         }
-        else {
-            const singleTag = singleTagOnlyOf(options);
-            if (singleTag !== undefined) {
-                const tagged = this.#registry.getSimpleTagged(token, singleTag);
-                if (tagged !== undefined && this.#satisfiesPredicate(tagged, options, resolutionStack)) {
-                    return { binding: tagged, owner: this };
-                }
-            }
-            else if (options.name === undefined &&
-                // A threshold switches the data structure, never the semantics: under it the generic scan
-                // below beats walking the indexes, and both paths answer identically. Sized first, so a
-                // small list pays one length read and nothing else.
-                this.#registry.getAll(token).length > MULTI_TAG_INDEX_THRESHOLD &&
-                requestedTagKeyMask(options) !== NO_TAG_KEYS) {
-                // A name-less multi-tag request matches only name-less tagged slots, and every such slot
-                // lives in one of the two tag indexes — so their union is the whole candidate set and the
-                // token's full list never needs scanning. Selection still owns predicates and specificity.
-                const selected = this.#selectMultiTagged(token, options, resolutionStack);
-                if (selected !== undefined) {
-                    return { binding: selected, owner: this };
-                }
-                return this.#parent === undefined ? undefined : this.#parent.#findBinding(token, options, resolutionStack);
+        else if (
+        // A threshold switches the data structure, never the semantics: under it the generic scan
+        // below beats walking the indexes, and both paths answer identically. Sized first, so a
+        // small list pays one length read and nothing else.
+        this.#registry.getAll(token).length > MULTI_TAG_INDEX_THRESHOLD &&
+            requestedTagKeyMask(options) !== NO_TAG_KEYS) {
+            // A multi-criterion request matches only slots whose every criterion it carries, and every
+            // such slot is in the two tag indexes — their union is the whole candidate set, unscanned.
+            const selected = this.#selectMultiTagged(token, options, resolutionStack);
+            if (selected !== undefined) {
+                return { binding: selected, owner: this };
             }
+            return this.#parent === undefined
+                ? undefined
+                : this.#parent.#findBinding(token, options, resolutionStack, singleCriterion);
         }
         const bindings = this.#registry.getAll(token);
         if (bindings.length > 0) {
             // A lone candidate is its own selection: matching it is the whole decision, with no
             // specificity to weigh and no ambiguity to report.
             const selected = bindings.length === 1
-                ? this.#matchesBindingFast(bindings[0], options, resolutionStack)
+                ? matchesSlot(bindings[0].slot, options) && this.#satisfiesPredicate(bindings[0], options, resolutionStack)
                     ? bindings[0]
                     : undefined
                 : selectBinding(bindings, options, this.#makeConstraintContext(resolutionStack, options), tokenName(token));
@@ -145,7 +145,7 @@ export class DependencyResolver {
             }
         }
         if (this.#parent !== undefined) {
-            return this.#parent.#findBinding(token, options, resolutionStack);
+            return this.#parent.#findBinding(token, options, resolutionStack, singleCriterion);
         }
         return undefined;
     }
@@ -155,10 +155,12 @@ export class DependencyResolver {
      * @remarks Alias hops are followed iteratively with exact cycle detection — a revisited alias
      * token raises {@link CircularDependencyError} instead of overflowing the call stack.
      */
-    #requireBinding(token, options, resolutionStack) {
+    #requireBinding(token, options, resolutionStack, precomputedCriterion) {
+        // `null` is a caller's "folded: none" — only an absent precomputation re-folds.
+        const singleCriterion = precomputedCriterion === undefined ? singleCriterionOnlyOf(options) : (precomputedCriterion ?? undefined);
         let currentToken = token;
         let visitedAliasTokens;
-        let found = this.#findBinding(currentToken, options, resolutionStack);
+        let found = this.#findBinding(currentToken, options, resolutionStack, singleCriterion);
         while (found !== undefined && found.binding.kind === "alias") {
             const target = found.binding.target;
             visitedAliasTokens ??= new Set([currentToken]);
@@ -167,7 +169,7 @@ export class DependencyResolver {
             }
             visitedAliasTokens.add(target);
             currentToken = target;
-            found = this.#findBinding(currentToken, options, resolutionStack);
+            found = this.#findBinding(currentToken, options, resolutionStack, singleCriterion);
         }
         if (found === undefined) {
             // Thrown here rather than from a helper: the error captures this stack, and an error path is
@@ -183,7 +185,7 @@ export class DependencyResolver {
      * Binding lookup aligned with `resolve` — used by `Container.validate` without instantiating.
      */
     peekBindingForValidate(token, options) {
-        return this.#findBinding(token, options, []);
+        return this.#findBinding(token, options, [], singleCriterionOnlyOf(options));
     }
     /**
      * Mirrors {@link DependencyResolver.resolveAll} candidate selection only (no instantiation).
@@ -327,22 +329,14 @@ export class DependencyResolver {
             const entry = this.#lookup.defaultEntry(token);
             return entry === null ? null : { binding: entry.binding };
         },
-        // Exactly what #findBinding's named lane accepts, minus the half that reads a path: a predicate
-        // is the compiler's cue to leave the selection to the runtime.
-        lookupPathIndependentNamedEntry: (token, options) => {
-            const entry = this.#lookup.namedEntry(token, options.name);
-            if (entry === null || entry.binding.predicate !== undefined || !matchesSlot(entry.binding.slot, options)) {
+        // Exactly what #findBinding's single-criterion lane accepts, minus the half that reads a path:
+        // a predicate is the compiler's cue to leave the selection to the runtime.
+        lookupPathIndependentEntry: (token, options) => {
+            const singleCriterion = singleCriterionOnlyOf(options);
+            if (singleCriterion === undefined) {
                 return null;
             }
-            return { binding: entry.binding };
-        },
-        // The named rule verbatim, on the single-tag lane's memo.
-        lookupPathIndependentTaggedEntry: (token, options) => {
-            const singleTag = singleTagOnlyOf(options);
-            if (singleTag === undefined) {
-                return null;
-            }
-            const entry = this.#lookup.taggedEntry(token, singleTag);
+            const entry = this.#lookup.taggedEntry(token, singleCriterion);
             if (entry === null || entry.binding.predicate !== undefined || !matchesSlot(entry.binding.slot, options)) {
                 return null;
             }
@@ -398,40 +392,28 @@ export class DependencyResolver {
         this.#asyncPlanByBindingId.set(binding.id, compiled);
         return compiled;
     }
-    resolve(token, options, resolutionStack) {
-        // Name-only fast lane: memoized lookup, dispatching just the shapes whose
-        // semantics involve no resolution context (constants, cached singletons).
-        if (options !== undefined && isNameOnlyOptions(options)) {
-            const namedEntry = this.#lookup.namedEntry(token, options.name);
-            if (namedEntry !== null) {
-                const namedBinding = namedEntry.binding;
-                if (namedEntry.owner.#isPlainConstant(namedBinding)) {
-                    return namedBinding.value;
-                }
-                if (namedBinding.scope === "singleton" && namedBinding.instance !== NO_INSTANCE) {
-                    return namedBinding.instance;
-                }
-                // Everything else keeps the full path (context, activation, guards).
-            }
-        }
-        else if (options !== undefined) {
-            // Single-tag fast lane: the named lane's tagged twin, memoizing the chain walk.
-            const singleTag = singleTagOnlyOf(options);
-            if (singleTag !== undefined) {
-                const taggedEntry = this.#lookup.taggedEntry(token, singleTag);
-                if (taggedEntry !== null) {
-                    const taggedBinding = taggedEntry.binding;
-                    if (taggedEntry.owner.#isPlainConstant(taggedBinding)) {
-                        return taggedBinding.value;
+    resolve(token, options, resolutionStack, precomputedCriterion) {
+        // Single-criterion fast lane (a lone name folds here too): memoized lookup, dispatching just
+        // the shapes whose semantics involve no resolution context (constants, cached singletons).
+        let singleCriterion;
+        if (options !== undefined) {
+            singleCriterion =
+                precomputedCriterion === undefined ? singleCriterionOnlyOf(options) : (precomputedCriterion ?? undefined);
+            if (singleCriterion !== undefined) {
+                const indexedEntry = this.#lookup.taggedEntry(token, singleCriterion);
+                if (indexedEntry !== null) {
+                    const indexedBinding = indexedEntry.binding;
+                    if (indexedEntry.owner.#isPlainConstant(indexedBinding)) {
+                        return indexedBinding.value;
                     }
-                    if (taggedBinding.scope === "singleton" && taggedBinding.instance !== NO_INSTANCE) {
-                        return taggedBinding.instance;
+                    if (indexedBinding.scope === "singleton" && indexedBinding.instance !== NO_INSTANCE) {
+                        return indexedBinding.instance;
                     }
                     // Everything else keeps the full path (context, activation, guards).
                 }
             }
         }
-        const { binding, owner } = this.#requireBinding(token, options, resolutionStack);
+        const { binding, owner } = this.#requireBinding(token, options, resolutionStack, singleCriterion ?? null);
         // A singleton owned by a parent resolver is resolved there, so the parent caches it.
         if (binding.scope === "singleton" && owner !== this) {
             return owner.#resolveBinding(binding, options, resolutionStack, owner);
@@ -582,15 +564,15 @@ export class DependencyResolver {
             return this.resolveAll(dep.token, options, resolutionStack);
         }
         if (dep.optional) {
-            return this.resolveOptional(dep.token, options, resolutionStack);
+            return this.resolveOptional(dep.token, options, resolutionStack, singleCriterionForSlot(dep));
         }
         if (options === undefined) {
             return this.resolveFromContext(dep.token, resolutionStack);
         }
-        return this.resolve(dep.token, options, resolutionStack);
+        return this.resolve(dep.token, options, resolutionStack, singleCriterionForSlot(dep));
     }
-    resolveOptional(token, options, resolutionStack) {
-        const entry = this.#findBinding(token, options, resolutionStack);
+    resolveOptional(token, options, resolutionStack, precomputedCriterion) {
+        const entry = this.#findBinding(token, options, resolutionStack, precomputedCriterion === undefined ? singleCriterionOnlyOf(options) : (precomputedCriterion ?? undefined));
         if (entry === undefined) {
             return undefined;
         }
@@ -677,8 +659,17 @@ export class DependencyResolver {
         }
         return this.#resolveBindingAsync(binding, undefined, resolutionStack, branchDepth, owner);
     }
-    async resolveAsync(token, options, resolutionStack, branchDepth = UNOWNED_BRANCH) {
-        const { binding, owner } = this.#requireBinding(token, options, resolutionStack);
+    /**
+     * Instantiates one owned binding directly, bypassing selection.
+     *
+     * @remarks Warm-up must build the binding it inspected: re-selecting by the slot's own criteria
+     * could pick a different candidate whose criteria are a subset of them.
+     */
+    warmBindingAsync(binding, options) {
+        return this.#resolveBindingAsync(binding, options, [], ROOT_BRANCH, this);
+    }
+    async resolveAsync(token, options, resolutionStack, branchDepth = UNOWNED_BRANCH, precomputedCriterion) {
+        const { binding, owner } = this.#requireBinding(token, options, resolutionStack, precomputedCriterion);
         if (binding.scope === "singleton" && owner !== this) {
             return owner.#resolveBindingAsync(binding, options, resolutionStack, branchDepth, owner);
         }
@@ -836,15 +827,15 @@ export class DependencyResolver {
             return this.resolveAllAsync(dep.token, options, resolutionStack, branchDepth);
         }
         if (dep.optional) {
-            return this.resolveOptionalAsync(dep.token, options, resolutionStack, branchDepth);
+            return this.resolveOptionalAsync(dep.token, options, resolutionStack, branchDepth, singleCriterionForSlot(dep));
         }
         if (options === undefined) {
             return this.resolveAsyncFromContext(dep.token, resolutionStack, branchDepth);
         }
-        return this.resolveAsync(dep.token, options, resolutionStack, branchDepth);
+        return this.resolveAsync(dep.token, options, resolutionStack, branchDepth, singleCriterionForSlot(dep));
     }
-    async resolveOptionalAsync(token, options, resolutionStack, branchDepth = UNOWNED_BRANCH) {
-        const entry = this.#findBinding(token, options, resolutionStack);
+    async resolveOptionalAsync(token, options, resolutionStack, branchDepth = UNOWNED_BRANCH, precomputedCriterion) {
+        const entry = this.#findBinding(token, options, resolutionStack, precomputedCriterion === undefined ? singleCriterionOnlyOf(options) : (precomputedCriterion ?? undefined));
         if (entry === undefined) {
             return undefined;
         }
@@ -881,56 +872,34 @@ export class DependencyResolver {
         }
         return result;
     }
-    /** Every binding the chain's name indexes hold for one name, nearest container first. */
-    #namedBindingsFromChain(token, name) {
-        // A name resolves to at most one binding per registry, so a root container's answer is built
-        // whole rather than grown — the list is sized at its allocation.
-        const ownBinding = this.#registry.getSimpleNamed(token, name);
-        if (this.#parent === undefined) {
-            return ownBinding === undefined ? [] : [ownBinding];
-        }
-        const result = ownBinding === undefined ? [] : [ownBinding];
-        for (let current = this.#parent; current !== undefined; current = current.#parent) {
-            const binding = current.#registry.getSimpleNamed(token, name);
-            if (binding !== undefined) {
-                result.push(binding);
-            }
-        }
-        return result;
-    }
     /**
-     * The candidates an index can name outright, or `null` when the request needs full selection.
+     * The candidates the index can name outright, or `null` when the request needs full selection.
      *
-     * @remarks Kept off `#candidateBindings` so that method stays the size it was: a request neither
-     * index serves must not pay for the two that do.
+     * @remarks Kept off `#candidateBindings` so that method stays the size it was: a request the
+     * index cannot serve must not pay for the shape it does.
      * An index has matched the slot already, but a hit may still carry a predicate, and evaluating
      * that is the selection path's job.
      */
     #indexedCandidates(token, options, resolutionStack) {
-        if (isNameOnlyOptions(options)) {
-            const named = this.#namedBindingsFromChain(token, options.name);
-            return anyPredicate(named)
-                ? selectAllBindings(named, options, this.#makeConstraintContext(resolutionStack, options))
-                : named;
-        }
-        const singleTag = singleTagOnlyOf(options);
-        if (singleTag === undefined) {
+        const singleCriterion = singleCriterionOnlyOf(options);
+        if (singleCriterion === undefined) {
             return null;
         }
-        const tagged = this.#taggedBindingsFromChain(token, singleTag);
-        return anyPredicate(tagged)
-            ? selectAllBindings(tagged, options, this.#makeConstraintContext(resolutionStack, options))
-            : tagged;
+        const indexed = this.#taggedBindingsFromChain(token, singleCriterion);
+        return anyPredicate(indexed)
+            ? selectAllBindings(indexed, options, this.#makeConstraintContext(resolutionStack, options))
+            : indexed;
     }
     /**
-     * Every binding the chain's tag indexes hold for one tag, nearest container first.
+     * Every binding the chain's criterion indexes hold for one criterion, nearest container first.
      *
-     * @remarks A request for one tag and no name matches exactly the bindings the index keys, so this
-     * is the whole candidate set rather than a prefilter — a named or multi-tag slot cannot satisfy it.
+     * @remarks A request for exactly one criterion matches exactly the bindings the index keys, so
+     * this is the whole candidate set rather than a prefilter — a multi-criterion slot cannot satisfy
+     * it.
      */
     #taggedBindingsFromChain(token, tag) {
-        // A tag matches at most one binding per registry, so a root container's answer is built whole
-        // rather than grown — the shape `#namedBindingsFromChain` takes, for the same reason.
+        // A criterion matches at most one binding per registry, so a root container's answer is built
+        // whole rather than grown — the list is sized at its allocation.
         const ownBinding = this.#registry.getSimpleTagged(token, tag);
         if (this.#parent === undefined) {
             return ownBinding === undefined ? [] : [ownBinding];
@@ -977,14 +946,19 @@ export class DependencyResolver {
         }
         return buildConstraintContext(resolutionStack, options);
     }
-    /** Selection for a name-less multi-tag request, over the union of the two tag indexes. */
+    /** Selection for a multi-criterion request, over the union of the two tag indexes. */
     #selectMultiTagged(token, options, resolutionStack) {
         const candidates = [];
-        this.#gatherTagCandidates(token, options.tag, candidates);
+        const gathered = [];
+        if (options.name !== undefined) {
+            // Read, not minted: an unminted name has no criterion, so no slot can carry it.
+            this.#gatherTagCandidates(token, slotNameCriterionOf(options.name), candidates, gathered);
+        }
+        this.#gatherTagCandidates(token, options.tag, candidates, gathered);
         const listed = options.tags;
         if (listed !== undefined) {
             for (let index = 0; index < listed.length; index += 1) {
-                this.#gatherTagCandidates(token, listed[index], candidates);
+                this.#gatherTagCandidates(token, listed[index], candidates, gathered);
             }
         }
         if (candidates.length === 0) {
@@ -993,31 +967,24 @@ export class DependencyResolver {
         return selectBinding(candidates, options, this.#makeConstraintContext(resolutionStack, options), tokenName(token));
     }
     /** One request criterion's candidates: its exact single-tag binding, plus its first-tag bucket. */
-    #gatherTagCandidates(token, criterion, out) {
-        if (criterion === undefined) {
+    #gatherTagCandidates(token, criterion, out, gathered) {
+        // Distinct criteria never share a binding — a slot lives in exactly one bucket — so deduping
+        // by criterion covers a request repeating one across its spellings, without scanning `out`.
+        if (criterion === undefined || gathered.includes(criterion)) {
             return;
         }
-        // The includes probes only guard a request repeating a criterion across its two spellings.
+        gathered.push(criterion);
         const single = this.#registry.getSimpleTagged(token, criterion);
-        if (single !== undefined && !out.includes(single)) {
+        if (single !== undefined) {
             out.push(single);
         }
         const bucket = this.#registry.getMultiTagged(token, criterion);
         if (bucket !== undefined) {
             for (let index = 0; index < bucket.length; index += 1) {
-                const candidate = bucket[index];
-                if (!out.includes(candidate)) {
-                    out.push(candidate);
-                }
+                out.push(bucket[index]);
             }
         }
     }
-    #matchesBindingFast(binding, options, resolutionStack) {
-        if (!matchesSlot(binding.slot, options)) {
-            return false;
-        }
-        return this.#satisfiesPredicate(binding, options, resolutionStack);
-    }
     /** The predicate half of a match, for a lane whose index has already settled the slot. */
     #satisfiesPredicate(binding, options, resolutionStack) {
         const predicate = binding.predicate;