@codefast/di 0.7.0 → 0.8.0

package/src/metadata/symbol-metadata-reader.ts

@@ -6,6 +6,8 @@ import type { ConstructorMetadata, LifecycleMetadata, MetadataReader } from "#/m
 type AccessorEntry = { readonly key: string | symbol; readonly descriptor: InjectionDescriptor };
 
 /**
+ * The default `MetadataReader`, reading decorator metadata stored under `Symbol.metadata`.
+ *
  * @since 0.3.16-canary.0
  */
 export class SymbolMetadataReader implements MetadataReader {
@@ -117,6 +119,8 @@ function mergeUniqueNames(lists: Array<ReadonlyArray<string>>): Array<string> {
 }
 
 /**
+ * The shared reader a container falls back to when given no custom `MetadataReader`.
+ *
  * @since 0.3.16-canary.0
  */
 export const defaultMetadataReader: SymbolMetadataReader = new SymbolMetadataReader();

package/src/resolution/cache/activation-need.ts

@@ -11,6 +11,8 @@ 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.
+ *
  * @since 0.5.0-canary.8
  */
 export class ActivationNeedCache {

package/src/resolution/cache/binding-lookup-cache.ts

@@ -31,14 +31,11 @@ export interface DefaultLookupEntry<Owner> {
  */
 export const ALIAS_HOP_LIMIT = 32;
 
-/**
- * @since 0.5.0-canary.8
- */
-const newNameToEntryMap = <Owner>(): Map<string, DefaultLookupEntry<Owner> | null> => new Map();
-
 const newTagToEntryMap = <Owner>(): Map<BindingTag, DefaultLookupEntry<Owner> | null> => new Map();
 
 /**
+ * A version-stamped cache of binding lookups by token and criterion across the container chain.
+ *
  * @since 0.5.0-canary.9
  */
 export class BindingLookupCache<Owner> {
@@ -49,8 +46,6 @@ export class BindingLookupCache<Owner> {
   // is tracked by the token slot rather than by the entry.
   #lastToken: Token<unknown> | Constructor | undefined;
   #lastEntry: DefaultLookupEntry<Owner> | null = null;
-  readonly #byTokenAndName = new Map<Token<unknown> | Constructor, Map<string, DefaultLookupEntry<Owner> | null>>();
-  #namedVersion = -1;
   readonly #byTokenAndTag = new Map<Token<unknown> | Constructor, Map<BindingTag, DefaultLookupEntry<Owner> | null>>();
   #taggedVersion = -1;
   // One entry in front of the tag map, and the map is not written until a second distinct request
@@ -99,24 +94,6 @@ export class BindingLookupCache<Owner> {
     return entry;
   }
 
-  /** `null` when the name's shape needs the full selection path. */
-  namedEntry(token: Token<unknown> | Constructor, name: string): DefaultLookupEntry<Owner> | null {
-    const version = this.chainVersion();
-    if (version !== this.#namedVersion) {
-      this.#byTokenAndName.clear();
-      this.#namedVersion = version;
-    }
-    // Computed, not eager: this runs on every named resolve, and the eager form would allocate a
-    // Map per call only to discard it on the hit that follows.
-    const byName = getOrInsertComputed(this.#byTokenAndName, token, newNameToEntryMap);
-    let entry = byName.get(name);
-    if (entry === undefined) {
-      entry = this.#findNamedInChain(token, name);
-      byName.set(name, entry);
-    }
-    return entry;
-  }
-
   /** `null` when the tag's shape needs the full selection path. */
   taggedEntry(token: Token<unknown> | Constructor, tag: BindingTag): DefaultLookupEntry<Owner> | null {
     const version = this.chainVersion();
@@ -175,21 +152,6 @@ export class BindingLookupCache<Owner> {
     return this.#parent === undefined ? null : this.#parent.#findDefaultInChain(token);
   }
 
-  #findNamedInChain(token: Token<unknown> | Constructor, name: string): DefaultLookupEntry<Owner> | null {
-    const named = this.#registry.getSimpleNamed(token, name);
-    if (named !== undefined) {
-      // Predicates need a live context; aliases carry options through the full path.
-      if (named.predicate !== undefined || named.kind === "alias") {
-        return null;
-      }
-      return { binding: named, owner: this.#owner };
-    }
-    if (this.#registry.has(token)) {
-      return null;
-    }
-    return this.#parent === undefined ? null : this.#parent.#findNamedInChain(token, name);
-  }
-
   #findTaggedInChain(token: Token<unknown> | Constructor, tag: BindingTag): DefaultLookupEntry<Owner> | null {
     const tagged = this.#registry.getSimpleTagged(token, tag);
     if (tagged !== undefined) {

package/src/resolution/cache/class-introspector.ts

@@ -188,6 +188,8 @@ export function verifyAccessorMetadata(
 }
 
 /**
+ * A per-class cache of constructor metadata and the activation facts derived from it.
+ *
  * @since 0.5.0-canary.8
  */
 export class ClassIntrospector {

package/src/resolution/context.ts

@@ -16,6 +16,8 @@ import { UNOWNED_BRANCH } from "#/resolution/path/resolution-path";
 // ── ResolutionContext implementation ─────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * The engine surface a resolution context calls back into to resolve further dependencies.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ResolverCallbacks {
@@ -60,6 +62,8 @@ export interface ResolverCallbacks {
 }
 
 /**
+ * The `ResolutionContext` handed to factories and hooks, backed by the engine's callbacks.
+ *
  * @since 0.3.16-canary.0
  */
 export class DefaultResolutionContext implements ResolutionContext {
@@ -312,6 +316,8 @@ class DefaultConstraintContext implements ConstraintContext {
 }
 
 /**
+ * Creates the resolution-stack frame for one in-flight resolve.
+ *
  * @since 0.3.16-canary.0
  */
 export function buildResolutionFrame(

package/src/resolution/plan/instantiation-plan.ts

@@ -12,7 +12,7 @@ import { tokenName } from "#/core/token";
 import type { Constructor, ResolutionFrame, ResolveOptions } from "#/core/types";
 import { AsyncResolutionError } from "#/errors/errors";
 import type { DependencySlot } from "#/injection/resolve-options";
-import { injectionSlotToResolveOptions, isNameOnlyOptions } from "#/injection/resolve-options";
+import { injectionSlotToResolveOptions } from "#/injection/resolve-options";
 import type { ConstructorMetadata } from "#/metadata/metadata-types";
 
 // Past this depth a dependency escapes to the runtime path rather than inlining further —
@@ -115,22 +115,13 @@ export interface InstantiationPlanHost {
   /** Options-less lookup with alias hops folded; `null` when the fast lane can't answer. */
   lookupDependencyEntry(token: Token<unknown> | Constructor): InstantiationPlanDependencyEntry | null;
   /**
-   * A name-only lookup a plan may bake in, or `null` when the answer is not the compiler's to make.
+   * A single-criterion lookup a plan may bake in, or `null` when the answer is not the compiler's
+   * to make.
    *
-   * @remarks Selection for a named request is an index hit *and* a predicate, and a predicate reads
+   * @remarks Selection for such a request is an index hit *and* a predicate, and a predicate reads
    * the resolution path — so only a candidate carrying none of one can be decided ahead of time.
    */
-  lookupPathIndependentNamedEntry(
-    token: Token<unknown> | Constructor,
-    options: ResolveOptions & { name: string },
-  ): InstantiationPlanDependencyEntry | null;
-  /**
-   * The named lookup's single-tag twin, or `null` under the same rule.
-   *
-   * @remarks Optional so a host predating it stays a valid host — a compiler given none simply
-   * escapes the dependency, which is exactly the pre-settlement behavior.
-   */
-  lookupPathIndependentTaggedEntry?(
+  lookupPathIndependentEntry(
     token: Token<unknown> | Constructor,
     options: ResolveOptions,
   ): InstantiationPlanDependencyEntry | null;
@@ -161,6 +152,8 @@ export interface InstantiationPlanHost {
 export type EscapeArity = "all" | "optional" | "single";
 
 /**
+ * The compiler that flattens a class or resolved binding's dependencies into an instantiation plan.
+ *
  * @since 0.3.16-canary.1
  */
 export class InstantiationPlanCompiler {
@@ -263,19 +256,11 @@ export class InstantiationPlanCompiler {
       return this.#compileEscapeThunk(token, ancestors, "optional", options);
     }
     if (options !== undefined) {
-      // A name the registry can settle without reading a path is a dependency like any other: it
-      // escapes only because it carries a criterion, not because anything about it is opaque.
-      if (isNameOnlyOptions(options)) {
-        const named = this.#host.lookupPathIndependentNamedEntry(token, options);
-        if (named !== null) {
-          return this.#compileDepThunk(named, compileStack, depth, ancestors, options);
-        }
-      } else {
-        // The host owns the whole single-tag decision, including whether the options qualify.
-        const tagged = this.#host.lookupPathIndependentTaggedEntry?.(token, options);
-        if (tagged !== null && tagged !== undefined) {
-          return this.#compileDepThunk(tagged, compileStack, depth, ancestors, options);
-        }
+      // A criterion the registry can settle without reading a path is a dependency like any other:
+      // it escapes only because the host cannot decide it ahead of time.
+      const indexed = this.#host.lookupPathIndependentEntry(token, options);
+      if (indexed !== null) {
+        return this.#compileDepThunk(indexed, compileStack, depth, ancestors, options);
       }
       return this.#compileEscapeThunk(token, ancestors, "single", options);
     }
@@ -539,17 +524,9 @@ export class InstantiationPlanCompiler {
       return this.#compileAsyncEscapeThunk(token, ancestors, "optional", options);
     }
     if (options !== undefined) {
-      if (isNameOnlyOptions(options)) {
-        const named = this.#host.lookupPathIndependentNamedEntry(token, options);
-        if (named !== null) {
-          return this.#compileAsyncDepThunk(named, compileStack, depth, ancestors, options);
-        }
-      } else {
-        // The host owns the whole single-tag decision, including whether the options qualify.
-        const tagged = this.#host.lookupPathIndependentTaggedEntry?.(token, options);
-        if (tagged !== null && tagged !== undefined) {
-          return this.#compileAsyncDepThunk(tagged, compileStack, depth, ancestors, options);
-        }
+      const indexed = this.#host.lookupPathIndependentEntry(token, options);
+      if (indexed !== null) {
+        return this.#compileAsyncDepThunk(indexed, compileStack, depth, ancestors, options);
       }
       return this.#compileAsyncEscapeThunk(token, ancestors, "single", options);
     }