@codefast/di 0.5.0-canary.7 → 0.5.0-canary.9

package/src/resolution/instantiation-plan.ts

@@ -1,28 +1,21 @@
 /**
- * Compiler for the resolver's Dagger-style instantiation plans: a transient
- * class or resolved-factory binding whose dependency subgraph is pure static
- * (class/constant/cached-singleton deps, no activation hooks or postConstruct)
- * compiles once into a nested-constructor/factory closure, cycle-checked at
- * compile time.
+ * Compiles a transient class or resolved-factory binding into a nested-constructor closure.
  *
- * Compilation is cold-path — it runs once per (binding, cache version). The
- * closures it returns ARE the hot path and touch nothing but their captures.
- * Anything dynamic refuses to compile so the runtime cycle guard stays in
- * charge and error semantics never change.
+ * @see `ARCHITECTURE.md` — the escape contract every dependency the compiler cannot inline must honour.
  */
 import type { Binding } from "#/binding";
+import { NO_INSTANCE } from "#/binding";
 import type { ConstructorInvocation } from "#/constructor-type";
-import type { InjectionDescriptor } from "#/decorators/inject";
 import { AsyncResolutionError } from "#/errors";
 import type { ConstructorMetadata } from "#/metadata/metadata-types";
+import type { DependencySlot } from "#/resolution/resolve-options";
 import { injectionSlotToResolveOptions } from "#/resolution/resolve-options";
-import type { ScopeManager } from "#/resolution/scope";
-import { SINGLETON_MISS } from "#/resolution/scope";
 import type { Token } from "#/token";
 import { tokenName } from "#/token";
-import type { BindingScope, Constructor } from "#/types";
+import type { Constructor, ResolutionFrame, ResolveOptions } from "#/types";
 
-// Bail out of pathological graphs — the runtime path handles them correctly.
+// Past this depth a dependency escapes to the runtime path rather than inlining further —
+// compiled closures nest one JS frame per level, and pathological graphs are the runtime's job.
 const PLAN_DEPTH_LIMIT = 32;
 
 /**
@@ -41,13 +34,20 @@ export const PLAN_RETRY: unique symbol = Symbol("di:plan-retry");
 export type InstantiationPlanCompileResult = (() => unknown) | null | typeof PLAN_RETRY;
 
 /**
- * A dependency's terminal binding plus the scope cache of the resolver that owns it.
+ * What compiling one *dependency* can yield.
+ *
+ * @remarks No `null`: a dependency escapes rather than failing, so "no plan" is only ever a
+ * verdict on a plan's root.
+ */
+type DependencyCompileResult = (() => unknown) | typeof PLAN_RETRY;
+
+/**
+ * A dependency's terminal binding — all a compiled thunk needs.
  *
  * @since 0.5.0-canary.7
  */
 export interface InstantiationPlanDependencyEntry {
   readonly binding: Binding;
-  readonly ownerScope: ScopeManager;
 }
 
 /**
@@ -64,10 +64,26 @@ export interface InstantiationPlanHost {
   getConstructorMetadata(target: Constructor): ConstructorMetadata | undefined;
   /** Options-less lookup with alias hops folded; `null` when the fast lane can't answer. */
   lookupDependencyEntry(token: Token<unknown> | Constructor): InstantiationPlanDependencyEntry | null;
-  /** Full runtime resolve — used by singleton thunks for the first materialization. */
-  resolveFallback(token: Token<unknown> | Constructor): unknown;
+  /** The frame the interpreted path pushes for this binding, so escapes can replay it. */
+  getResolutionFrame(binding: Binding): ResolutionFrame;
+  /** Runtime resolve for an escaped dependency, seeded with the ancestors above it. */
+  resolveEscaped(
+    token: Token<unknown> | Constructor,
+    options: ResolveOptions | undefined,
+    arity: EscapeArity,
+    resolutionPath: Array<string>,
+    resolutionStack: Array<ResolutionFrame>,
+  ): unknown;
 }
 
+/**
+ * Which resolve an escaped dependency replays — mirrors how the interpreted path dispatches
+ * a constructor param.
+ *
+ * @since 0.5.0-canary.8
+ */
+export type EscapeArity = "all" | "optional" | "single";
+
 /**
  * @since 0.3.16-canary.1
  */
@@ -80,8 +96,26 @@ export class InstantiationPlanCompiler {
 
   compile(binding: Binding & { kind: "class" | "resolved" }): InstantiationPlanCompileResult {
     return binding.kind === "class"
-      ? this.#compileClassPlan(binding, new Set(), 0)
-      : this.#compileResolvedPlan(binding, new Set(), 0);
+      ? this.#compileClassPlan(binding, new Set(), 0, [])
+      : this.#compileResolvedPlan(binding, new Set(), 0, []);
+  }
+
+  /**
+   * Re-entry into the runtime resolver for a dependency the plan can't see through.
+   *
+   * The ancestors are fixed at compile time, so the seeds are built once; each call copies
+   * them because the resolver pushes and pops on the arrays it is given.
+   */
+  #compileEscapeThunk(
+    token: Token<unknown> | Constructor,
+    ancestors: ReadonlyArray<Binding>,
+    arity: EscapeArity = "single",
+    options?: ResolveOptions,
+  ): () => unknown {
+    const host = this.#host;
+    const frames = ancestors.map((ancestor) => host.getResolutionFrame(ancestor));
+    const names = frames.map((frame) => frame.tokenName);
+    return () => host.resolveEscaped(token, options, arity, [...names], [...frames]);
   }
 
   // A resolved binding declares its deps as explicit descriptors — same rules as
@@ -90,21 +124,20 @@ export class InstantiationPlanCompiler {
     binding: Binding & { kind: "resolved" },
     compileStack: Set<Binding["id"]>,
     depth: number,
+    ancestors: ReadonlyArray<Binding>,
   ): InstantiationPlanCompileResult {
-    if (depth > PLAN_DEPTH_LIMIT || compileStack.has(binding.id)) {
-      return null;
-    }
     if (binding.onActivation !== undefined || this.#host.hasActivationHandlers(binding.token)) {
       return null;
     }
     const factory = binding.factory;
     const tokenDisplayName = tokenName(binding.token);
     const depThunks = new Array<() => unknown>(binding.deps.length);
+    const depAncestors = [...ancestors, binding];
     compileStack.add(binding.id);
     try {
       for (let index = 0; index < binding.deps.length; index += 1) {
-        const thunk = this.#compileDescriptorThunk(binding.deps[index]!, compileStack, depth);
-        if (thunk === null || thunk === PLAN_RETRY) {
+        const thunk = this.#compileInjectionThunk(binding.deps[index]!, compileStack, depth, depAncestors);
+        if (thunk === PLAN_RETRY) {
           return thunk;
         }
         depThunks[index] = thunk;
@@ -121,29 +154,41 @@ export class InstantiationPlanCompiler {
     };
   }
 
-  #compileDescriptorThunk(
-    descriptor: InjectionDescriptor,
+  /**
+   * One dependency of a plan node — a constructor param or a `toResolved` descriptor.
+   *
+   * @remarks Anything but a plain required single dependency escapes to the runtime path.
+   */
+  #compileInjectionThunk(
+    descriptor: DependencySlot,
     compileStack: Set<Binding["id"]>,
     depth: number,
-  ): InstantiationPlanCompileResult {
-    if (descriptor.multi || descriptor.optional || injectionSlotToResolveOptions(descriptor) !== undefined) {
-      return null;
+    ancestors: ReadonlyArray<Binding>,
+  ): DependencyCompileResult {
+    const token = descriptor.token;
+    const options = injectionSlotToResolveOptions(descriptor);
+    if (descriptor.multi) {
+      return this.#compileEscapeThunk(token, ancestors, "all", options);
+    }
+    if (descriptor.optional) {
+      return this.#compileEscapeThunk(token, ancestors, "optional", options);
     }
-    const entry = this.#host.lookupDependencyEntry(descriptor.token as Token<unknown> | Constructor);
+    if (options !== undefined) {
+      return this.#compileEscapeThunk(token, ancestors, "single", options);
+    }
+    const entry = this.#host.lookupDependencyEntry(token);
     if (entry === null) {
-      return null;
+      return this.#compileEscapeThunk(token, ancestors);
     }
-    return this.#compileDepThunk(entry, compileStack, depth);
+    return this.#compileDepThunk(entry, compileStack, depth, ancestors);
   }
 
   #compileClassPlan(
     binding: Binding & { kind: "class" },
     compileStack: Set<Binding["id"]>,
     depth: number,
+    ancestors: ReadonlyArray<Binding>,
   ): InstantiationPlanCompileResult {
-    if (depth > PLAN_DEPTH_LIMIT || compileStack.has(binding.id)) {
-      return null;
-    }
     if (binding.onActivation !== undefined || this.#host.hasActivationHandlers(binding.token)) {
       return null;
     }
@@ -166,19 +211,12 @@ export class InstantiationPlanCompiler {
       return () => new invokable();
     }
     const depThunks = new Array<() => unknown>(params.length);
+    const depAncestors = [...ancestors, binding];
     compileStack.add(binding.id);
     try {
       for (let index = 0; index < params.length; index += 1) {
-        const param = params[index]!;
-        if (param.multi || param.optional || injectionSlotToResolveOptions(param) !== undefined) {
-          return null;
-        }
-        const entry = this.#host.lookupDependencyEntry(param.token);
-        if (entry === null) {
-          return null;
-        }
-        const thunk = this.#compileDepThunk(entry, compileStack, depth);
-        if (thunk === null || thunk === PLAN_RETRY) {
+        const thunk = this.#compileInjectionThunk(params[index]!, compileStack, depth, depAncestors);
+        if (thunk === PLAN_RETRY) {
           return thunk;
         }
         depThunks[index] = thunk;
@@ -211,30 +249,44 @@ export class InstantiationPlanCompiler {
     entry: InstantiationPlanDependencyEntry,
     compileStack: Set<Binding["id"]>,
     depth: number,
-  ): InstantiationPlanCompileResult {
-    const { binding, ownerScope } = entry;
-    if (binding.kind === "constant") {
-      if (binding.onActivation !== undefined || this.#host.hasActivationHandlers(binding.token)) {
-        return null;
+    ancestors: ReadonlyArray<Binding>,
+  ): DependencyCompileResult {
+    const { binding } = entry;
+    if (binding.kind === "constant" && binding.onActivation === undefined) {
+      if (!this.#host.hasActivationHandlers(binding.token)) {
+        const value = binding.value;
+        return () => value;
       }
-      const value = binding.value;
-      return () => value;
     }
-    const scope = (binding as Binding & { scope: BindingScope }).scope ?? "transient";
+    const scope = binding.scope;
     if (scope === "singleton") {
-      // Cached-singleton read with a full-resolve fallback for the first materialization.
-      const host = this.#host;
-      const bindingId = binding.id;
-      const singletonToken = binding.token;
+      // Cached-singleton read; the first materialization escapes so it sees the same ancestors
+      // (and therefore the same cycle detection) the interpreted path would have built.
+      const escape = this.#compileEscapeThunk(binding.token, ancestors);
+      const singletonBinding = binding;
       return () => {
-        const cachedSingleton = ownerScope.peekSingleton(bindingId);
-        return cachedSingleton === SINGLETON_MISS ? host.resolveFallback(singletonToken) : cachedSingleton;
+        const cached = singletonBinding.instance;
+        return cached === NO_INSTANCE ? escape() : cached;
       };
     }
-    if (scope === "transient" && binding.kind === "class") {
-      return this.#compileClassPlan(binding as Binding & { kind: "class" }, compileStack, depth + 1);
+    if (
+      scope === "transient" &&
+      binding.kind === "class" &&
+      depth < PLAN_DEPTH_LIMIT &&
+      !compileStack.has(binding.id)
+    ) {
+      const inlined = this.#compileClassPlan(
+        binding as Binding & { kind: "class" },
+        compileStack,
+        depth + 1,
+        ancestors,
+      );
+      if (inlined !== null) {
+        return inlined;
+      }
     }
-    // Dynamic/resolved/scoped deps keep the runtime path (and its cycle guard).
-    return null;
+    // Anything opaque — a factory, a scoped binding, an activation hook, a class the compiler
+    // declined — runs on the runtime path, seeded with this plan's ancestors.
+    return this.#compileEscapeThunk(binding.token, ancestors);
   }
 }

package/src/resolution/lifecycle.ts

@@ -9,23 +9,28 @@ import type { ActivationHandler, Constructor, DeactivationHandler, ResolutionCon
  * @since 0.3.16-canary.0
  */
 export class LifecycleManager {
-  // Container-level activation/deactivation hooks per token
-  readonly #activationHooks = new Map<Token<unknown> | Constructor, Array<ActivationHandler<unknown>>>();
-  readonly #deactivationHooks = new Map<Token<unknown> | Constructor, Array<DeactivationHandler<unknown>>>();
+  // Container-level activation/deactivation hooks per token — most containers register none, so
+  // both tables stay unallocated until the first hook arrives.
+  #activationHooks: Map<Token<unknown> | Constructor, Array<ActivationHandler<unknown>>> | undefined;
+  #deactivationHooks: Map<Token<unknown> | Constructor, Array<DeactivationHandler<unknown>>> | undefined;
   #activationVersion = 0;
 
+  // One-entry cache in front of the map: a resolve loop asks about the same token over and over,
+  // and registration is the only thing that can change the answer.
+  #cachedToken: Token<unknown> | Constructor | undefined;
+  #cachedHooks: Array<ActivationHandler<unknown>> | undefined;
+
   registerActivation<const Value>(token: Token<Value> | Constructor<Value>, handler: ActivationHandler<Value>): void {
     this.#activationVersion += 1;
+    this.#cachedToken = undefined;
+    this.#cachedHooks = undefined;
     // ✓ TS6.0: Map.getOrInsert (ES2025)
-    const list = this.#activationHooks.getOrInsert(token as Token<unknown> | Constructor, []);
+    const list = (this.#activationHooks ??= new Map()).getOrInsert(token as Token<unknown> | Constructor, []);
     list.push(handler as ActivationHandler<unknown>);
   }
 
   hasActivationHandlers<const Value>(token: Token<Value> | Constructor<Value>): boolean {
-    if (this.#activationHooks.size === 0) {
-      return false;
-    }
-    const list = this.#activationHooks.get(token as Token<unknown> | Constructor);
+    const list = this.activationHandlersFor(token);
     return list !== undefined && list.length > 0;
   }
 
@@ -37,14 +42,25 @@ export class LifecycleManager {
   activationHandlersFor<const Value>(
     token: Token<Value> | Constructor<Value>,
   ): ReadonlyArray<ActivationHandler<unknown>> | undefined {
-    return this.#activationHooks.get(token as Token<unknown> | Constructor);
+    const hooks = this.#activationHooks;
+    if (hooks === undefined) {
+      return undefined;
+    }
+    const key = token as Token<unknown> | Constructor;
+    if (key === this.#cachedToken) {
+      return this.#cachedHooks;
+    }
+    const list = hooks.get(key);
+    this.#cachedToken = key;
+    this.#cachedHooks = list;
+    return list;
   }
 
   registerDeactivation<const Value>(
     token: Token<Value> | Constructor<Value>,
     handler: DeactivationHandler<Value>,
   ): void {
-    const list = this.#deactivationHooks.getOrInsert(token as Token<unknown> | Constructor, []);
+    const list = (this.#deactivationHooks ??= new Map()).getOrInsert(token as Token<unknown> | Constructor, []);
     list.push(handler as DeactivationHandler<unknown>);
   }
 
@@ -57,18 +73,10 @@ export class LifecycleManager {
     let activatedInstance: Value = instance;
 
     // 1. @postConstruct() — after TC39 construction (constructor + accessor addInitializer callbacks)
-    if (binding.kind === "class") {
-      const lifecycle = metadataReader.getLifecycleMetadata(binding.target);
-      if (lifecycle?.postConstruct && lifecycle.postConstruct.length > 0) {
-        for (const methodName of lifecycle.postConstruct) {
-          const method = (activatedInstance as Record<string, unknown>)[methodName];
-          if (typeof method === "function") {
-            const hookResult = (method as () => unknown).call(activatedInstance);
-            if (hookResult instanceof Promise) {
-              await hookResult;
-            }
-          }
-        }
+    for (const methodName of lifecycleMethods(binding, metadataReader, "postConstruct")) {
+      const hookResult = callHook(activatedInstance, methodName);
+      if (hookResult instanceof Promise) {
+        await hookResult;
       }
     }
 
@@ -79,7 +87,7 @@ export class LifecycleManager {
     }
 
     // 3. container-level onActivation
-    const containerHooks = this.#activationHooks.get(binding.token as Token<unknown> | Constructor);
+    const containerHooks = this.#activationHooks?.get(binding.token as Token<unknown> | Constructor);
     if (containerHooks !== undefined) {
       for (const hook of containerHooks) {
         const activationResult = hook(resolutionContext, activatedInstance);
@@ -99,18 +107,9 @@ export class LifecycleManager {
     let activatedInstance: Value = instance;
 
     // 1. @postConstruct() — must be sync (instance fully constructed per TC39 order)
-    if (binding.kind === "class") {
-      const lifecycle = metadataReader.getLifecycleMetadata(binding.target);
-      if (lifecycle?.postConstruct && lifecycle.postConstruct.length > 0) {
-        for (const methodName of lifecycle.postConstruct) {
-          const method = (activatedInstance as Record<string, unknown>)[methodName];
-          if (typeof method === "function") {
-            const hookResult = (method as () => unknown).call(activatedInstance);
-            if (hookResult instanceof Promise) {
-              throw new AsyncActivationError(tokenName(binding.token), "postConstruct", methodName);
-            }
-          }
-        }
+    for (const methodName of lifecycleMethods(binding, metadataReader, "postConstruct")) {
+      if (callHook(activatedInstance, methodName) instanceof Promise) {
+        throw new AsyncActivationError(tokenName(binding.token), "postConstruct", methodName);
       }
     }
 
@@ -125,7 +124,7 @@ export class LifecycleManager {
 
     // 3. container-level onActivation (must be sync)
     const tokenDisplayName = tokenName(binding.token);
-    const containerHooks = this.#activationHooks.get(binding.token as Token<unknown> | Constructor);
+    const containerHooks = this.#activationHooks?.get(binding.token as Token<unknown> | Constructor);
     if (containerHooks !== undefined) {
       for (const hook of containerHooks) {
         const activationResult = hook(resolutionContext, activatedInstance);
@@ -147,7 +146,7 @@ export class LifecycleManager {
     const tokenKey = binding.token as Token<unknown> | Constructor;
 
     // 1. container-level onDeactivation
-    const containerHooks = this.#deactivationHooks.get(tokenKey);
+    const containerHooks = this.#deactivationHooks?.get(tokenKey);
     if (containerHooks !== undefined) {
       for (const hook of containerHooks) {
         const hookResult = hook(instance);
@@ -166,18 +165,10 @@ export class LifecycleManager {
     }
 
     // 3. @preDestroy() — all methods in declaration order
-    if (binding.kind === "class") {
-      const lifecycle = metadataReader.getLifecycleMetadata(binding.target);
-      if (lifecycle?.preDestroy && lifecycle.preDestroy.length > 0) {
-        for (const methodName of lifecycle.preDestroy) {
-          const method = (instance as Record<string, unknown>)[methodName];
-          if (typeof method === "function") {
-            const hookResult = (method as () => unknown).call(instance);
-            if (hookResult instanceof Promise) {
-              await hookResult;
-            }
-          }
-        }
+    for (const methodName of lifecycleMethods(binding, metadataReader, "preDestroy")) {
+      const hookResult = callHook(instance, methodName);
+      if (hookResult instanceof Promise) {
+        await hookResult;
       }
     }
   }
@@ -187,7 +178,7 @@ export class LifecycleManager {
     const tokenKey = binding.token as Token<unknown> | Constructor;
 
     // 1. container-level onDeactivation
-    const containerHooks = this.#deactivationHooks.get(tokenKey);
+    const containerHooks = this.#deactivationHooks?.get(tokenKey);
     if (containerHooks !== undefined) {
       for (const hook of containerHooks) {
         const hookResult = hook(instance);
@@ -206,19 +197,35 @@ export class LifecycleManager {
     }
 
     // 3. @preDestroy()
-    if (binding.kind === "class") {
-      const lifecycle = metadataReader.getLifecycleMetadata(binding.target);
-      if (lifecycle?.preDestroy && lifecycle.preDestroy.length > 0) {
-        for (const methodName of lifecycle.preDestroy) {
-          const method = (instance as Record<string, unknown>)[methodName];
-          if (typeof method === "function") {
-            const hookResult = (method as () => unknown).call(instance);
-            if (hookResult instanceof Promise) {
-              throw new AsyncDeactivationError(tokenDisplayName);
-            }
-          }
-        }
+    for (const methodName of lifecycleMethods(binding, metadataReader, "preDestroy")) {
+      if (callHook(instance, methodName) instanceof Promise) {
+        throw new AsyncDeactivationError(tokenDisplayName);
       }
     }
   }
+
+  /** Whether the deferred table behind `#activationHooks` has had to be built. */
+  get isBuilt(): boolean {
+    return this.#activationHooks !== undefined;
+  }
+}
+
+const NO_METHODS: ReadonlyArray<string> = [];
+
+/** The `@postConstruct` / `@preDestroy` methods a binding declares — only a class can declare any. */
+function lifecycleMethods<const Value>(
+  binding: Binding<Value>,
+  metadataReader: MetadataReader,
+  phase: "postConstruct" | "preDestroy",
+): ReadonlyArray<string> {
+  if (binding.kind !== "class") {
+    return NO_METHODS;
+  }
+  return metadataReader.getLifecycleMetadata(binding.target)?.[phase] ?? NO_METHODS;
+}
+
+/** Invokes a hook by name, tolerating a name whose member is not (or no longer) a method. */
+function callHook(instance: unknown, methodName: string): unknown {
+  const method = (instance as Record<string, unknown>)[methodName];
+  return typeof method === "function" ? (method as () => unknown).call(instance) : undefined;
 }