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

package/src/resolution/instantiation-plan.ts

@@ -0,0 +1,240 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+import type { Binding } 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 { 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";
+
+// Bail out of pathological graphs — the runtime path handles them correctly.
+const PLAN_DEPTH_LIMIT = 32;
+
+/**
+ * Compilation asked to retry later (class lifecycle metadata not discovered yet).
+ *
+ * @since 0.5.0-canary.7
+ */
+export const PLAN_RETRY: unique symbol = Symbol("di:plan-retry");
+
+/**
+ * A compiled plan, `null` for "not plannable under the current cache versions",
+ * or {@link PLAN_RETRY} when a first runtime resolve must discover metadata first.
+ *
+ * @since 0.5.0-canary.7
+ */
+export type InstantiationPlanCompileResult = (() => unknown) | null | typeof PLAN_RETRY;
+
+/**
+ * A dependency's terminal binding plus the scope cache of the resolver that owns it.
+ *
+ * @since 0.5.0-canary.7
+ */
+export interface InstantiationPlanDependencyEntry {
+  readonly binding: Binding;
+  readonly ownerScope: ScopeManager;
+}
+
+/**
+ * Everything the compiler needs from its resolver, expressed as behavior so the
+ * compiler stays independently testable and free of resolver internals.
+ *
+ * @since 0.5.0-canary.7
+ */
+export interface InstantiationPlanHost {
+  hasActivationHandlers(token: Token<unknown> | Constructor): boolean;
+  /** Cached postConstruct presence — `undefined` until a runtime resolve discovers it. */
+  knownPostConstruct(target: Constructor): boolean | undefined;
+  needsActiveContainer(target: Constructor): boolean;
+  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;
+}
+
+/**
+ * @since 0.3.16-canary.1
+ */
+export class InstantiationPlanCompiler {
+  readonly #host: InstantiationPlanHost;
+
+  constructor(host: InstantiationPlanHost) {
+    this.#host = host;
+  }
+
+  compile(binding: Binding & { kind: "class" | "resolved" }): InstantiationPlanCompileResult {
+    return binding.kind === "class"
+      ? this.#compileClassPlan(binding, new Set(), 0)
+      : this.#compileResolvedPlan(binding, new Set(), 0);
+  }
+
+  // A resolved binding declares its deps as explicit descriptors — same rules as
+  // class params, with the factory call (and its sync-only check) in place of `new`.
+  #compileResolvedPlan(
+    binding: Binding & { kind: "resolved" },
+    compileStack: Set<Binding["id"]>,
+    depth: number,
+  ): 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);
+    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) {
+          return thunk;
+        }
+        depThunks[index] = thunk;
+      }
+    } finally {
+      compileStack.delete(binding.id);
+    }
+    return () => {
+      const factoryResult = factory(...depThunks.map((thunk) => thunk()));
+      if (factoryResult instanceof Promise) {
+        throw new AsyncResolutionError(tokenDisplayName, tokenDisplayName);
+      }
+      return factoryResult;
+    };
+  }
+
+  #compileDescriptorThunk(
+    descriptor: InjectionDescriptor,
+    compileStack: Set<Binding["id"]>,
+    depth: number,
+  ): InstantiationPlanCompileResult {
+    if (descriptor.multi || descriptor.optional || injectionSlotToResolveOptions(descriptor) !== undefined) {
+      return null;
+    }
+    const entry = this.#host.lookupDependencyEntry(descriptor.token as Token<unknown> | Constructor);
+    if (entry === null) {
+      return null;
+    }
+    return this.#compileDepThunk(entry, compileStack, depth);
+  }
+
+  #compileClassPlan(
+    binding: Binding & { kind: "class" },
+    compileStack: Set<Binding["id"]>,
+    depth: number,
+  ): InstantiationPlanCompileResult {
+    if (depth > PLAN_DEPTH_LIMIT || compileStack.has(binding.id)) {
+      return null;
+    }
+    if (binding.onActivation !== undefined || this.#host.hasActivationHandlers(binding.token)) {
+      return null;
+    }
+    const target = binding.target;
+    const hasPostConstruct = this.#host.knownPostConstruct(target);
+    if (hasPostConstruct === undefined) {
+      return PLAN_RETRY;
+    }
+    if (hasPostConstruct || this.#host.needsActiveContainer(target)) {
+      return null;
+    }
+    const invokable = target as ConstructorInvocation;
+    const meta = this.#host.getConstructorMetadata(target);
+    if (meta === undefined) {
+      // Metadata-less classes with required params throw on the runtime path — keep them there.
+      return target.length === 0 ? () => new invokable() : null;
+    }
+    const params = meta.params;
+    if (params.length === 0) {
+      return () => new invokable();
+    }
+    const depThunks = new Array<() => unknown>(params.length);
+    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) {
+          return thunk;
+        }
+        depThunks[index] = thunk;
+      }
+    } finally {
+      compileStack.delete(binding.id);
+    }
+    switch (depThunks.length) {
+      case 1: {
+        const dep0 = depThunks[0]!;
+        return () => new invokable(dep0());
+      }
+      case 2: {
+        const dep0 = depThunks[0]!;
+        const dep1 = depThunks[1]!;
+        return () => new invokable(dep0(), dep1());
+      }
+      case 3: {
+        const dep0 = depThunks[0]!;
+        const dep1 = depThunks[1]!;
+        const dep2 = depThunks[2]!;
+        return () => new invokable(dep0(), dep1(), dep2());
+      }
+      default:
+        return () => new invokable(...depThunks.map((thunk) => thunk()));
+    }
+  }
+
+  #compileDepThunk(
+    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;
+      }
+      const value = binding.value;
+      return () => value;
+    }
+    const scope = (binding as Binding & { scope: BindingScope }).scope ?? "transient";
+    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;
+      return () => {
+        const cachedSingleton = ownerScope.peekSingleton(bindingId);
+        return cachedSingleton === SINGLETON_MISS ? host.resolveFallback(singletonToken) : cachedSingleton;
+      };
+    }
+    if (scope === "transient" && binding.kind === "class") {
+      return this.#compileClassPlan(binding as Binding & { kind: "class" }, compileStack, depth + 1);
+    }
+    // Dynamic/resolved/scoped deps keep the runtime path (and its cycle guard).
+    return null;
+  }
+}

package/src/{lifecycle.ts → resolution/lifecycle.ts}

@@ -10,34 +10,41 @@ import type { ActivationHandler, Constructor, DeactivationHandler, ResolutionCon
  */
 export class LifecycleManager {
   // Container-level activation/deactivation hooks per token
-  private readonly _activationHooks = new Map<Token<unknown> | Constructor, Array<ActivationHandler<unknown>>>();
-  private readonly _deactivationHooks = new Map<Token<unknown> | Constructor, Array<DeactivationHandler<unknown>>>();
-  private _activationVersion = 0;
+  readonly #activationHooks = new Map<Token<unknown> | Constructor, Array<ActivationHandler<unknown>>>();
+  readonly #deactivationHooks = new Map<Token<unknown> | Constructor, Array<DeactivationHandler<unknown>>>();
+  #activationVersion = 0;
 
   registerActivation<const Value>(token: Token<Value> | Constructor<Value>, handler: ActivationHandler<Value>): void {
-    this._activationVersion += 1;
+    this.#activationVersion += 1;
     // ✓ TS6.0: Map.getOrInsert (ES2025)
-    const list = this._activationHooks.getOrInsert(token as Token<unknown> | Constructor, []);
+    const list = this.#activationHooks.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) {
+    if (this.#activationHooks.size === 0) {
       return false;
     }
-    const list = this._activationHooks.get(token as Token<unknown> | Constructor);
+    const list = this.#activationHooks.get(token as Token<unknown> | Constructor);
     return list !== undefined && list.length > 0;
   }
 
   get activationVersion(): number {
-    return this._activationVersion;
+    return this.#activationVersion;
+  }
+
+  /** Container-level activation handlers for a token — hot-path accessor, no copies. */
+  activationHandlersFor<const Value>(
+    token: Token<Value> | Constructor<Value>,
+  ): ReadonlyArray<ActivationHandler<unknown>> | undefined {
+    return this.#activationHooks.get(token as Token<unknown> | Constructor);
   }
 
   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.getOrInsert(token as Token<unknown> | Constructor, []);
     list.push(handler as DeactivationHandler<unknown>);
   }
 
@@ -72,7 +79,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);
@@ -118,7 +125,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);
@@ -140,7 +147,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);
@@ -180,7 +187,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);

package/src/resolution/resolution-path.ts

@@ -0,0 +1,77 @@
+/**
+ * Cycle-detection bookkeeping shared by every resolution path.
+ *
+ * The resolution path is a plain string array for cheap push/pop; past
+ * RESOLUTION_SET_THRESHOLD entries an O(1) membership Set is attached to the
+ * array itself (symbol-keyed) so very deep graphs keep bounded cycle checks.
+ */
+import { CircularDependencyError } from "#/errors";
+
+const RESOLUTION_SET_KEY: unique symbol = Symbol("di:resolution-set");
+/**
+ * Where the cycle check switches from a linear `Array.includes` scan to an attached Set.
+ *
+ * @remarks Re-measured on Node 26 / M3 Max over an async transient chain (ns/op at depth
+ * 16 / 32 / 64 / 128): a threshold of 128 gives 1275 / 3641 / 9645 / 26082, of 32 gives
+ * 1202 / 3285 / 7735 / 16837, of 16 gives 1299 / 3694 / 7449 / 15625. Switching at 32 wins
+ * the shallow-to-mid depths real graphs actually have while staying close to the best deep
+ * numbers; the previous value of 128 was the worst of the three almost everywhere.
+ *
+ * @since 0.5.0-canary.7
+ */
+export const RESOLUTION_SET_THRESHOLD = 32;
+type ResolutionPathWithSet = Array<string> & { [RESOLUTION_SET_KEY]?: Set<string> };
+
+/**
+ * Shared cycle guard for every transient resolution path: attaches the O(1) membership
+ * Set to the path array (lazily past RESOLUTION_SET_THRESHOLD, eagerly when `forceSet`),
+ * throws on a repeated token, then marks the token on both structures.
+ *
+ * Callers unmark with `resolutionPath.pop()` + `set?.delete(name)` on unwind.
+ */
+export function enterResolutionPath(
+  resolutionPath: Array<string>,
+  tokenDisplayName: string,
+  forceSet: true,
+): Set<string>;
+export function enterResolutionPath(
+  resolutionPath: Array<string>,
+  tokenDisplayName: string,
+  forceSet: boolean,
+): Set<string> | undefined;
+/**
+ * @since 0.5.0-canary.7
+ */
+export function enterResolutionPath(
+  resolutionPath: Array<string>,
+  tokenDisplayName: string,
+  forceSet: boolean,
+): Set<string> | undefined {
+  const pathWithSet = resolutionPath as ResolutionPathWithSet;
+  let resolutionSet = pathWithSet[RESOLUTION_SET_KEY];
+  if (resolutionSet === undefined && (forceSet || resolutionPath.length >= RESOLUTION_SET_THRESHOLD)) {
+    resolutionSet = new Set<string>(resolutionPath);
+    pathWithSet[RESOLUTION_SET_KEY] = resolutionSet;
+  }
+  if (resolutionSet === undefined ? resolutionPath.includes(tokenDisplayName) : resolutionSet.has(tokenDisplayName)) {
+    throw new CircularDependencyError([...resolutionPath, tokenDisplayName]);
+  }
+  resolutionPath.push(tokenDisplayName);
+  resolutionSet?.add(tokenDisplayName);
+  return resolutionSet;
+}
+
+/**
+ * Unwinds the innermost `enterResolutionPath` entry, keeping the attached membership Set in
+ * sync. Callers that already hold the entry's name can pop and delete directly; this exists for
+ * unwind paths that only have the path array — notably the async chain's shared settle callback,
+ * which serves every level and therefore cannot capture a per-level name.
+ *
+ * @since 0.5.0-canary.7
+ */
+export function exitResolutionPath(resolutionPath: Array<string>): void {
+  const tokenDisplayName = resolutionPath.pop();
+  if (tokenDisplayName !== undefined) {
+    (resolutionPath as ResolutionPathWithSet)[RESOLUTION_SET_KEY]?.delete(tokenDisplayName);
+  }
+}