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

package/src/resolution/activation-need.ts

@@ -0,0 +1,81 @@
+/**
+ * Per binding: does resolving it have to go through the activation pipeline?
+ *
+ * @remarks Versioned on the lifecycle manager, since `onActivation` can be registered at any time.
+ */
+import type { Binding } from "#/binding";
+import type { ClassIntrospector } from "#/resolution/class-introspector";
+import type { LifecycleManager } from "#/resolution/lifecycle";
+import type { BindingIdentifier } from "#/types";
+
+/**
+ * @since 0.5.0-canary.8
+ */
+export class ActivationNeedCache {
+  readonly #needByBindingId = new Map<BindingIdentifier, boolean>();
+  #version = -1;
+  readonly #lifecycle: LifecycleManager;
+  readonly #classes: ClassIntrospector;
+
+  constructor(lifecycle: LifecycleManager, classes: ClassIntrospector) {
+    this.#lifecycle = lifecycle;
+    this.#classes = classes;
+  }
+
+  needsActivation<const Value>(binding: Binding<Value>): boolean {
+    const lifecycleVersion = this.#lifecycle.activationVersion;
+    // No hooks registered anywhere and none on the binding: only classes can still surprise us,
+    // via a @postConstruct we have not looked for yet.
+    if (
+      lifecycleVersion === 0 &&
+      binding.kind !== "class" &&
+      binding.kind !== "alias" &&
+      binding.onActivation === undefined
+    ) {
+      return false;
+    }
+    if (this.#version !== lifecycleVersion) {
+      this.#needByBindingId.clear();
+      this.#version = lifecycleVersion;
+    }
+    const cached = this.#needByBindingId.get(binding.id);
+    if (cached !== undefined) {
+      return cached;
+    }
+    const needsActivation =
+      binding.kind === "class" ? this.#classNeedsActivation(binding) : this.#nonClassNeedsActivation(binding);
+    this.#needByBindingId.set(binding.id, needsActivation);
+    return needsActivation;
+  }
+
+  /**
+   * Settles a class binding's answer once its lifecycle metadata has actually been read, which
+   * only happens on the first instantiation.
+   *
+   * @returns the answer to use for this resolve — possibly now `false` where it was a
+   * conservative `true`.
+   */
+  refreshAfterFirstInstantiation<Value>(binding: Binding<Value>, needsActivation: boolean): boolean {
+    if (binding.kind !== "class" || this.#classes.knownPostConstruct(binding.target) !== undefined) {
+      return needsActivation;
+    }
+    this.#classes.discoverPostConstruct(binding.target);
+    this.#needByBindingId.delete(binding.id);
+    return this.needsActivation(binding);
+  }
+
+  #classNeedsActivation<const Value>(binding: Binding<Value> & { kind: "class" }): boolean {
+    if (this.#lifecycle.hasActivationHandlers(binding.token) || binding.onActivation !== undefined) {
+      return true;
+    }
+    // Unknown lifecycle metadata: activate once so the first instantiation can settle it.
+    return this.#classes.knownPostConstruct(binding.target) !== false;
+  }
+
+  #nonClassNeedsActivation<const Value>(binding: Binding<Value>): boolean {
+    if (binding.kind !== "alias" && binding.onActivation !== undefined) {
+      return true;
+    }
+    return this.#lifecycle.hasActivationHandlers(binding.token);
+  }
+}

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

@@ -0,0 +1,132 @@
+/**
+ * Options-less token → terminal binding, memoized per container chain.
+ *
+ * @see `ARCHITECTURE.md` — why these caches form their own parent chain.
+ */
+import type { Binding } from "#/binding";
+import type { BindingRegistry } from "#/registry";
+import type { Token } from "#/token";
+import type { Constructor } from "#/types";
+
+/**
+ * A token's terminal binding with alias hops already folded, plus the container that owns it.
+ *
+ * @typeParam Owner - the resolver type, kept generic so this module stays free of resolver internals
+ *
+ * @since 0.5.0-canary.8
+ */
+export interface DefaultLookupEntry<Owner> {
+  readonly binding: Binding;
+  readonly owner: Owner;
+}
+
+/**
+ * Alias folding gives up past this many hops and defers to the full resolve loop, whose
+ * Set-based traversal detects genuine cycles exactly rather than by an arbitrary cap.
+ *
+ * @since 0.5.0-canary.8
+ */
+export const ALIAS_HOP_LIMIT = 32;
+
+/**
+ * @since 0.5.0-canary.8
+ */
+export class BindingLookupCache<Owner> {
+  readonly #byToken = new Map<Token<unknown> | Constructor, DefaultLookupEntry<Owner> | null>();
+  #version = -1;
+  readonly #byTokenAndName = new Map<Token<unknown> | Constructor, Map<string, DefaultLookupEntry<Owner> | null>>();
+  #namedVersion = -1;
+
+  readonly #registry: BindingRegistry;
+  readonly #owner: Owner;
+  readonly #parent: BindingLookupCache<Owner> | undefined;
+
+  constructor(registry: BindingRegistry, owner: Owner, parent: BindingLookupCache<Owner> | undefined) {
+    this.#registry = registry;
+    this.#owner = owner;
+    this.#parent = parent;
+  }
+
+  /** Summed registry versions of this cache's whole chain — the memo stamp. */
+  chainVersion(): number {
+    let version = this.#registry.version;
+    for (let cache = this.#parent; cache !== undefined; cache = cache.#parent) {
+      version += cache.#registry.version;
+    }
+    return version;
+  }
+
+  /** `null` when the token's shape needs the full selection path. */
+  defaultEntry(token: Token<unknown> | Constructor): DefaultLookupEntry<Owner> | null {
+    const version = this.chainVersion();
+    if (version !== this.#version) {
+      this.#byToken.clear();
+      this.#version = version;
+    }
+    let entry = this.#byToken.get(token);
+    if (entry === undefined) {
+      entry = this.#foldAliases(token);
+      this.#byToken.set(token, entry);
+    }
+    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;
+    }
+    // ✓ TS6.0: Map.getOrInsert (ES2025)
+    const byName = this.#byTokenAndName.getOrInsert(token, new Map<string, DefaultLookupEntry<Owner> | null>());
+    let entry = byName.get(name);
+    if (entry === undefined) {
+      entry = this.#findNamedInChain(token, name);
+      byName.set(name, entry);
+    }
+    return entry;
+  }
+
+  #foldAliases(token: Token<unknown> | Constructor): DefaultLookupEntry<Owner> | null {
+    let current = token;
+    for (let hop = 0; hop < ALIAS_HOP_LIMIT; hop += 1) {
+      const entry = this.#findDefaultInChain(current);
+      if (entry === null) {
+        return null;
+      }
+      if (entry.binding.kind !== "alias") {
+        return entry;
+      }
+      current = entry.binding.target;
+    }
+    return null;
+  }
+
+  #findDefaultInChain(token: Token<unknown> | Constructor): DefaultLookupEntry<Owner> | null {
+    const fast = this.#registry.getFastDefault(token);
+    if (fast !== undefined) {
+      return { binding: fast, owner: this.#owner };
+    }
+    // A level with non-fast bindings (multi-slot / predicate) needs full selection — bail.
+    if (this.#registry.has(token)) {
+      return null;
+    }
+    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);
+  }
+}

package/src/resolution/binding-select.ts

@@ -135,10 +135,7 @@ function matchesSlot(binding: Binding, options: ResolveOptions | undefined): boo
       }
     }
   } else if (hasRequestedTags) {
-    // Binding has no tags but options requires tags — no match for tagged slots
-    // But: default slot (no tags, no name) can match when options has tags if there are no tag-slotted bindings
-    // Actually per spec: resolveAll with tags only returns bindings that have those tags
-    // and resolve with tags requires exact match
+    // Requested tags require a tagged slot: an untagged binding never matches (SPEC §6.9).
     return false;
   }
 

package/src/resolution/class-introspector.ts

@@ -0,0 +1,74 @@
+/**
+ * Per-class decorator metadata, cached by constructor.
+ *
+ * @remarks Metadata cannot change once a class is defined, so nothing here needs version stamping.
+ */
+
+import type { ConstructorInvocation } from "#/constructor-type";
+import type { Container } from "#/container/container";
+import type { ConstructorMetadata, MetadataReader } from "#/metadata/metadata-types";
+import { runWithContainer } from "#/resolution/environment";
+import type { Constructor } from "#/types";
+
+/**
+ * @since 0.5.0-canary.8
+ */
+export class ClassIntrospector {
+  // Unallocated until the container resolves its first class binding — a container bound entirely
+  // to constants, factories or aliases never introspects one.
+  #constructorMetadata: WeakMap<Constructor, ConstructorMetadata | null> | undefined;
+  #hasPostConstruct: WeakMap<Constructor, boolean> | undefined;
+  #needsActiveContainer: WeakMap<Constructor, boolean> | undefined;
+  readonly #reader: MetadataReader;
+  readonly #container: Container;
+
+  constructor(reader: MetadataReader, container: Container) {
+    this.#reader = reader;
+    this.#container = container;
+  }
+
+  constructorMetadata(target: Constructor): ConstructorMetadata | undefined {
+    const cached = this.#constructorMetadata?.get(target);
+    if (cached !== undefined) {
+      return cached === null ? undefined : cached;
+    }
+    const metadata = this.#reader.getConstructorMetadata(target);
+    (this.#constructorMetadata ??= new WeakMap()).set(target, metadata ?? null);
+    return metadata;
+  }
+
+  /**
+   * Whether the class has a `@postConstruct` hook, or `undefined` until {@link discoverPostConstruct}.
+   *
+   * @remarks Callers treat unknown as "assume it does", so the first activation settles it.
+   */
+  knownPostConstruct(target: Constructor): boolean | undefined {
+    return this.#hasPostConstruct?.get(target);
+  }
+
+  discoverPostConstruct(target: Constructor): void {
+    const lifecycle = this.#reader.getLifecycleMetadata(target);
+    (this.#hasPostConstruct ??= new WeakMap()).set(
+      target,
+      lifecycle !== undefined && lifecycle.postConstruct !== undefined && lifecycle.postConstruct.length > 0,
+    );
+  }
+
+  /** True when the class has accessor injection, which reads the container during construction. */
+  needsActiveContainer(target: Constructor): boolean {
+    let needsActiveContainer = this.#needsActiveContainer?.get(target);
+    if (needsActiveContainer === undefined) {
+      needsActiveContainer = (this.#reader.getAccessorMetadata?.(target)?.length ?? 0) > 0;
+      (this.#needsActiveContainer ??= new WeakMap()).set(target, needsActiveContainer);
+    }
+    return needsActiveContainer;
+  }
+
+  instantiate(target: Constructor, deps: Array<unknown>): unknown {
+    const invokable = target as ConstructorInvocation;
+    if (!this.needsActiveContainer(target)) {
+      return new invokable(...deps);
+    }
+    return runWithContainer(this.#container, () => new invokable(...deps));
+  }
+}

package/src/resolution/diagnostics.ts

@@ -0,0 +1,43 @@
+/**
+ * Internal seam letting tests assert that an optimization is *active*, not merely that the result
+ * is correct.
+ *
+ * @remarks Timing belongs in the benchmark, which needs a quiet machine and twenty minutes; these
+ * are structural counts, so CI can hold the invariants that make the benchmark fast. Reached
+ * through a symbol from a module the package does not publish, so it is not public API.
+ */
+
+/**
+ * Key for the diagnostics accessor on a container.
+ *
+ * @remarks A symbol rather than a method name, so it cannot collide with the public surface or be
+ * reached by anyone who has not imported this module.
+ *
+ * @since 0.5.0-canary.8
+ */
+export const RESOLUTION_DIAGNOSTICS: unique symbol = Symbol("di:resolution-diagnostics");
+
+/**
+ * Structural facts about a container's resolution caches.
+ *
+ * @since 0.5.0-canary.8
+ */
+export interface ResolutionDiagnostics {
+  /** Bindings with a compiled instantiation plan. */
+  readonly compiledPlanCount: number;
+  /** Contexts held by the depth-indexed sync pool. */
+  readonly syncContextPoolSize: number;
+  /** Contexts returned to the async chain pool and available for reuse. */
+  readonly asyncContextPoolSize: number;
+  /** Deferred collaborators this container has had to build. */
+  readonly builtSubsystems: ReadonlyArray<string>;
+}
+
+/**
+ * A container that can report on its resolution caches.
+ *
+ * @since 0.5.0-canary.8
+ */
+export interface DiagnosableContainer {
+  [RESOLUTION_DIAGNOSTICS](): ResolutionDiagnostics;
+}

package/src/resolution/environment.ts

@@ -56,6 +56,7 @@ export interface ResolverCallbacks {
     token: Token<Value> | Constructor<Value>,
     resolutionPath: Array<string>,
     resolutionStack: Array<ResolutionFrame>,
+    callerContext?: DefaultResolutionContext,
   ): Promise<Value>;
   resolveAsync<const Value>(
     token: Token<Value> | Constructor<Value>,
@@ -105,6 +106,7 @@ export class DefaultResolutionContext implements ResolutionContext {
     currentOptions: ResolveOptions | undefined,
   ) {
     this.#resolver = resolver;
+    this.owner = resolver;
     this.#resolutionPath = resolutionPath;
     this.#resolutionStack = resolutionStack;
     this.#currentOptions = currentOptions;
@@ -112,6 +114,30 @@ export class DefaultResolutionContext implements ResolutionContext {
 
   #graph: ConstraintContext | undefined;
 
+  /**
+   * The unwind callback shared by every level of the async chain this context serves.
+   *
+   * @remarks A plain field, not a lazy accessor — a getter taking a factory would allocate that
+   * factory on every level, which is the allocation this exists to avoid.
+   */
+  chainSettle: (() => void) | undefined;
+
+  /**
+   * How many levels of the async chain are still in flight on this context.
+   *
+   * @remarks The chain's first level acquires the context and every level increments; the last
+   * one to settle returns it to the resolver's pool. Counting here rather than on the resolver
+   * is what lets two concurrent chains run without a shared counter to get wrong.
+   */
+  chainLevels = 0;
+
+  /**
+   * The resolver this context speaks to — an inner async level checks it before reusing this.
+   *
+   * @remarks A field, not a method, because the check runs on every hop of every chain.
+   */
+  owner: ResolverCallbacks;
+
   get graph(): ConstraintContext {
     if (this.#graph === undefined) {
       this.#graph = new DefaultConstraintContext(this.#resolutionPath, this.#resolutionStack, this.#currentOptions);
@@ -126,10 +152,13 @@ export class DefaultResolutionContext implements ResolutionContext {
     currentOptions: ResolveOptions | undefined,
   ): void {
     this.#resolver = resolver;
+    this.owner = resolver;
     this.#resolutionPath = resolutionPath;
     this.#resolutionStack = resolutionStack;
     this.#currentOptions = currentOptions;
     this.#graph = undefined;
+    this.chainSettle = undefined;
+    this.chainLevels = 0;
   }
 
   resolve<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value {
@@ -141,7 +170,8 @@ export class DefaultResolutionContext implements ResolutionContext {
 
   resolveAsync<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value> {
     if (options === undefined) {
-      return this.#resolver.resolveAsyncFromContext(token, this.#resolutionPath, this.#resolutionStack);
+      // Hand the callee this context: an inner level of the same chain reuses it as-is.
+      return this.#resolver.resolveAsyncFromContext(token, this.#resolutionPath, this.#resolutionStack, this);
     }
     return this.#resolver.resolveAsync(token, options, this.#resolutionPath, this.#resolutionStack);
   }