@codefast/di 0.6.2 → 0.7.1

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 {
@@ -73,7 +75,7 @@ export class SymbolMetadataReader implements MetadataReader {
         preDestroy: mergeUniqueNames(buckets.map((bucket) => bucket.preDestroy).reverse()),
       };
     }
-    (this.#lifecycleByClass ??= new WeakMap()).set(target, merged);
+    (this.#lifecycleByClass ??= new WeakMap<Constructor, LifecycleMetadata | null>()).set(target, merged);
     return merged ?? undefined;
   }
 
@@ -96,7 +98,7 @@ export class SymbolMetadataReader implements MetadataReader {
     } else {
       merged = buckets.flat();
     }
-    (this.#accessorsByClass ??= new WeakMap()).set(target, merged);
+    (this.#accessorsByClass ??= new WeakMap<Constructor, ReadonlyArray<AccessorEntry> | null>()).set(target, merged);
     return merged ?? undefined;
   }
 }
@@ -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

@@ -5,6 +5,7 @@
  * the container hierarchy again.
  */
 import type { Binding } from "#/core/binding";
+import { getOrInsertComputed } from "#/core/map-upsert";
 import type { BindingRegistry } from "#/core/registry";
 import type { BindingTag } from "#/core/tag";
 import type { Token } from "#/core/token";
@@ -38,6 +39,8 @@ const newNameToEntryMap = <Owner>(): Map<string, DefaultLookupEntry<Owner> | nul
 const newTagToEntryMap = <Owner>(): Map<BindingTag, DefaultLookupEntry<Owner> | null> => new Map();
 
 /**
+ * A version-stamped cache of binding lookups by token, name, and tag across the container chain.
+ *
  * @since 0.5.0-canary.9
  */
 export class BindingLookupCache<Owner> {
@@ -105,9 +108,9 @@ export class BindingLookupCache<Owner> {
       this.#byTokenAndName.clear();
       this.#namedVersion = version;
     }
-    // Computed, not eager: this runs on every named resolve, and `getOrInsert(token, new Map())`
-    // would allocate a Map per call only to discard it on the hit that follows.
-    const byName = this.#byTokenAndName.getOrInsertComputed(token, newNameToEntryMap);
+    // 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);
@@ -134,7 +137,7 @@ export class BindingLookupCache<Owner> {
     } else {
       // Keyed by the criterion object itself: criteria are interned, so identity is the slot
       // contract's own `Object.is` — the same exactness the registry's tagged index relies on.
-      const byTag = this.#byTokenAndTag.getOrInsertComputed(token, newTagToEntryMap);
+      const byTag = getOrInsertComputed(this.#byTokenAndTag, token, newTagToEntryMap);
       entry = byTag.get(tag);
       if (entry === undefined) {
         entry = this.#findTaggedInChain(token, tag);

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 {
@@ -210,7 +212,10 @@ export class ClassIntrospector {
       return cached === null ? undefined : cached;
     }
     const metadata = this.#reader.getConstructorMetadata(target);
-    (this.#constructorMetadata ??= new WeakMap()).set(target, metadata ?? null);
+    (this.#constructorMetadata ??= new WeakMap<Constructor, ConstructorMetadata | null>()).set(
+      target,
+      metadata ?? null,
+    );
     return metadata;
   }
 
@@ -225,7 +230,7 @@ export class ClassIntrospector {
 
   discoverPostConstruct(target: Constructor): void {
     const lifecycle = this.#reader.getLifecycleMetadata(target);
-    (this.#hasPostConstruct ??= new WeakMap()).set(
+    (this.#hasPostConstruct ??= new WeakMap<Constructor, boolean>()).set(
       target,
       lifecycle !== undefined && lifecycle.postConstruct !== undefined && lifecycle.postConstruct.length > 0,
     );
@@ -236,7 +241,7 @@ export class ClassIntrospector {
     let needsActiveContainer = this.#needsActiveContainer?.get(target);
     if (needsActiveContainer === undefined) {
       needsActiveContainer = (this.#reader.getAccessorMetadata?.(target)?.length ?? 0) > 0;
-      (this.#needsActiveContainer ??= new WeakMap()).set(target, needsActiveContainer);
+      (this.#needsActiveContainer ??= new WeakMap<Constructor, boolean>()).set(target, needsActiveContainer);
     }
     return needsActiveContainer;
   }

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

@@ -161,6 +161,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 {

package/src/resolution/resolver.ts

@@ -71,6 +71,8 @@ const ROOT_CONSTRAINT_CONTEXT = {
 };
 
 /**
+ * The resolution engine driving binding selection, instantiation, scoping, and lifecycle hooks.
+ *
  * @since 0.3.16-canary.0
  */
 export class DependencyResolver implements ResolverCallbacks {

package/src/resolution/select/constraints.ts

@@ -7,6 +7,8 @@ import type { BindingConstraint, Constructor } from "#/core/types";
 import { EmptyTagCriteriaError } from "#/errors/errors";
 
 /**
+ * Matches when the direct parent frame resolves the given token.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenParentIs(token: Token<unknown> | Constructor): BindingConstraint {
@@ -16,6 +18,8 @@ export function whenParentIs(token: Token<unknown> | Constructor): BindingConstr
 }
 
 /**
+ * Matches when there is no direct parent frame, or it resolves a different token.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenNoParentIs(token: Token<unknown> | Constructor): BindingConstraint {
@@ -25,6 +29,8 @@ export function whenNoParentIs(token: Token<unknown> | Constructor): BindingCons
 }
 
 /**
+ * Matches when at least one ancestor frame resolves the given token.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenAnyAncestorIs(token: Token<unknown> | Constructor): BindingConstraint {
@@ -34,6 +40,8 @@ export function whenAnyAncestorIs(token: Token<unknown> | Constructor): BindingC
 }
 
 /**
+ * Matches when no ancestor frame resolves the given token.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenNoAncestorIs(token: Token<unknown> | Constructor): BindingConstraint {
@@ -43,6 +51,8 @@ export function whenNoAncestorIs(token: Token<unknown> | Constructor): BindingCo
 }
 
 /**
+ * Matches when the direct parent slot carries the given name.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenParentNamed(name: string): BindingConstraint {
@@ -54,6 +64,8 @@ export function whenParentNamed(name: string): BindingConstraint {
 }
 
 /**
+ * Matches when at least one ancestor slot carries the given name.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenAnyAncestorNamed(name: string): BindingConstraint {
@@ -65,6 +77,8 @@ export function whenAnyAncestorNamed(name: string): BindingConstraint {
 }
 
 /**
+ * Matches when the direct parent slot carries the given tag pair.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenParentTagged(criterion: BindingTag): BindingConstraint {
@@ -73,6 +87,8 @@ export function whenParentTagged(criterion: BindingTag): BindingConstraint {
 }
 
 /**
+ * Matches when at least one ancestor slot carries the given tag pair.
+ *
  * @since 0.3.16-canary.0
  */
 export function whenAnyAncestorTagged(criterion: BindingTag): BindingConstraint {