@codefast/di 0.5.0 → 0.6.0

package/src/resolution/binding-select.ts

@@ -1,154 +0,0 @@
-import type { Binding, BindingSlot } from "#/binding";
-import { AmbiguousBindingError } from "#/errors";
-import type { BindingTag, ConstraintContext, ResolveOptions } from "#/types";
-
-/**
- * Select a single candidate from a list of bindings using slot matching + predicates.
- * Returns undefined if no match, throws AmbiguousBindingError if multiple match.
- *
- * @since 0.3.16-canary.0
- */
-export function selectBinding(
-  bindings: ReadonlyArray<Binding>,
-  options: ResolveOptions | undefined,
-  ctx: ConstraintContext,
-  tokenDisplayName: string,
-): Binding | undefined {
-  const candidates = filterBindings(bindings, options, ctx);
-  if (candidates.length === 0) {
-    return undefined;
-  }
-  if (candidates.length === 1) {
-    return candidates[0];
-  }
-  // Most specific wins: a single matching predicate-carrying candidate beats
-  // predicate-less ones (a predicate is a deliberate specialization of the
-  // default). Two matching predicates are genuinely ambiguous.
-  let predicatedCandidate: Binding | undefined;
-  for (const candidate of candidates) {
-    if (candidate.predicate !== undefined) {
-      if (predicatedCandidate !== undefined) {
-        predicatedCandidate = undefined;
-        break;
-      }
-      predicatedCandidate = candidate;
-    }
-  }
-  if (predicatedCandidate !== undefined) {
-    return predicatedCandidate;
-  }
-  throw new AmbiguousBindingError(
-    tokenDisplayName,
-    candidates.map((c) => c.id),
-  );
-}
-
-/**
- * Select all candidates matching options + predicates.
- *
- * @since 0.3.16-canary.0
- */
-export function selectAllBindings(
-  bindings: ReadonlyArray<Binding>,
-  options: ResolveOptions | undefined,
-  ctx: ConstraintContext,
-): Array<Binding> {
-  return filterBindings(bindings, options, ctx, "all");
-}
-
-function filterBindings(
-  bindings: ReadonlyArray<Binding>,
-  options: ResolveOptions | undefined,
-  ctx: ConstraintContext,
-  selectionMode: "single" | "all" = "single",
-): Array<Binding> {
-  // `resolveAll` with no slot criterion takes every binding; `resolve` always matches the slot,
-  // where an absent criterion means "the default slot".
-  const requiresSlotMatch = selectionMode === "single" || (options !== undefined && hasSlotCriterion(options));
-  const result: Array<Binding> = [];
-  for (const binding of bindings) {
-    if ((!requiresSlotMatch || matchesSlot(binding.slot, options)) && matchesPredicate(binding, ctx)) {
-      result.push(binding);
-    }
-  }
-  return result;
-}
-
-function hasSlotCriterion(options: ResolveOptions): boolean {
-  return options.name !== undefined || options.tag !== undefined || (options.tags?.length ?? 0) > 0;
-}
-
-/**
- * Whether a binding's slot satisfies a request: names must be equal, and every tag the slot
- * declares must be among the tags requested (SPEC §6.9).
- *
- * @since 0.5.0-canary.9
- */
-export function matchesSlot(slot: BindingSlot, options: ResolveOptions | undefined): boolean {
-  const requestedName = options?.name;
-  const requestedTags = options?.tags;
-  const singleRequestedTag = options?.tag;
-  const hasRequestedTags = (requestedTags?.length ?? 0) > 0 || singleRequestedTag !== undefined;
-
-  // Match by name
-  if (slot.name !== undefined) {
-    if (requestedName === undefined) {
-      return false;
-    }
-    if (slot.name !== requestedName) {
-      return false;
-    }
-  } else if (requestedName !== undefined) {
-    // Binding has no name but options requests a specific name — no match
-    return false;
-  }
-
-  // Match by tags — binding's tags must all be present in options
-  if (slot.tags.length > 0) {
-    if (!hasRequestedTags) {
-      return false;
-    }
-    for (const [tagKey, tagValue] of slot.tags) {
-      if (!matchesRequestedTag(tagKey, tagValue, requestedTags, singleRequestedTag)) {
-        return false;
-      }
-    }
-  } else if (hasRequestedTags) {
-    // Requested tags require a tagged slot: an untagged binding never matches (SPEC §6.9).
-    return false;
-  }
-
-  return true;
-}
-
-function matchesRequestedTag(
-  tagKey: string,
-  tagValue: unknown,
-  requestedTags: ReadonlyArray<BindingTag> | undefined,
-  singleRequestedTag: BindingTag | undefined,
-): boolean {
-  if (
-    singleRequestedTag !== undefined &&
-    singleRequestedTag[0] === tagKey &&
-    Object.is(singleRequestedTag[1], tagValue)
-  ) {
-    return true;
-  }
-  if (requestedTags === undefined || requestedTags.length === 0) {
-    return false;
-  }
-  for (let index = 0; index < requestedTags.length; index += 1) {
-    const requestedTag = requestedTags[index]!;
-    if (requestedTag[0] === tagKey && Object.is(requestedTag[1], tagValue)) {
-      return true;
-    }
-  }
-  return false;
-}
-
-function matchesPredicate(binding: Binding, ctx: ConstraintContext): boolean {
-  if (binding.predicate === undefined) {
-    return true;
-  }
-  return binding.predicate(ctx);
-}

package/src/resolution/class-introspector.ts

@@ -1,74 +0,0 @@
-/**
- * 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/constraints.ts

@@ -1,121 +0,0 @@
-import type { Token } from "#/token";
-import { tokenName } from "#/token";
-import type { BindingTag, ConstraintContext, Constructor } from "#/types";
-
-function tokenNameOf(token: Token<unknown> | Constructor): string {
-  return tokenName(token);
-}
-
-/**
- * @since 0.3.16-canary.0
- */
-export function whenParentIs(token: Token<unknown> | Constructor): (constraintContext: ConstraintContext) => boolean {
-  const tokenDisplayName = tokenNameOf(token);
-  return (constraintContext) =>
-    constraintContext.parent !== undefined && constraintContext.parent.tokenName === tokenDisplayName;
-}
-
-/**
- * @since 0.3.16-canary.0
- */
-export function whenNoParentIs(token: Token<unknown> | Constructor): (constraintContext: ConstraintContext) => boolean {
-  const tokenDisplayName = tokenNameOf(token);
-  return (constraintContext) =>
-    constraintContext.parent === undefined || constraintContext.parent.tokenName !== tokenDisplayName;
-}
-
-/**
- * @since 0.3.16-canary.0
- */
-export function whenAnyAncestorIs(
-  token: Token<unknown> | Constructor,
-): (constraintContext: ConstraintContext) => boolean {
-  const tokenDisplayName = tokenNameOf(token);
-  return (constraintContext) =>
-    constraintContext.ancestors.some((ancestorFrame) => ancestorFrame.tokenName === tokenDisplayName);
-}
-
-/**
- * @since 0.3.16-canary.0
- */
-export function whenNoAncestorIs(
-  token: Token<unknown> | Constructor,
-): (constraintContext: ConstraintContext) => boolean {
-  const tokenDisplayName = tokenNameOf(token);
-  return (constraintContext) =>
-    constraintContext.ancestors.every((ancestorFrame) => ancestorFrame.tokenName !== tokenDisplayName);
-}
-
-/**
- * @since 0.3.16-canary.0
- */
-export function whenParentNamed(name: string): (constraintContext: ConstraintContext) => boolean {
-  return (constraintContext) => constraintContext.parent !== undefined && constraintContext.parent.slot.name === name;
-}
-
-/**
- * @since 0.3.16-canary.0
- */
-export function whenAnyAncestorNamed(name: string): (constraintContext: ConstraintContext) => boolean {
-  return (constraintContext) => constraintContext.ancestors.some((ancestorFrame) => ancestorFrame.slot.name === name);
-}
-
-/**
- * @since 0.3.16-canary.0
- */
-export function whenParentTagged(tag: string, value: unknown): (constraintContext: ConstraintContext) => boolean {
-  return (constraintContext) =>
-    constraintContext.parent !== undefined &&
-    constraintContext.parent.slot.tags.some(([tagKey, tagValue]) => tagKey === tag && Object.is(tagValue, value));
-}
-
-/**
- * @since 0.3.16-canary.0
- */
-export function whenAnyAncestorTagged(tag: string, value: unknown): (constraintContext: ConstraintContext) => boolean {
-  return (constraintContext) =>
-    constraintContext.ancestors.some((ancestorFrame) =>
-      ancestorFrame.slot.tags.some(([tagKey, tagValue]) => tagKey === tag && Object.is(tagValue, value)),
-    );
-}
-
-/**
- * Matches when the direct parent slot carries **all** of the given tag pairs.
- * Equivalent to AND-composing multiple `whenParentTagged` calls but evaluates
- * in a single predicate invocation — no intermediate closure allocations.
- *
- * @since 0.3.16-canary.1
- */
-export function whenParentTaggedAll(
-  tags: ReadonlyArray<BindingTag>,
-): (constraintContext: ConstraintContext) => boolean {
-  return (constraintContext) => {
-    const { parent } = constraintContext;
-    if (parent === undefined) {
-      return false;
-    }
-    const { tags: parentTags } = parent.slot;
-    return tags.every(([tagKey, tagValue]) =>
-      parentTags.some(([otherKey, otherValue]) => otherKey === tagKey && Object.is(otherValue, tagValue)),
-    );
-  };
-}
-
-/**
- * Matches when at least one ancestor slot carries **all** of the given tag pairs.
- * Equivalent to AND-composing multiple `whenAnyAncestorTagged` calls but evaluates
- * in a single predicate invocation — no intermediate closure allocations.
- *
- * @since 0.3.16-canary.1
- */
-export function whenAnyAncestorTaggedAll(
-  tags: ReadonlyArray<BindingTag>,
-): (constraintContext: ConstraintContext) => boolean {
-  return (constraintContext) =>
-    constraintContext.ancestors.some((frame) => {
-      const { tags: frameTags } = frame.slot;
-      return tags.every(([tagKey, tagValue]) =>
-        frameTags.some(([otherKey, otherValue]) => otherKey === tagKey && Object.is(otherValue, tagValue)),
-      );
-    });
-}

package/src/resolution/instantiation-plan.ts

@@ -1,292 +0,0 @@
-/**
- * Compiles a transient class or resolved-factory binding into a nested-constructor closure.
- *
- * @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 { 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 { Token } from "#/token";
-import { tokenName } from "#/token";
-import type { Constructor, ResolutionFrame, ResolveOptions } from "#/types";
-
-// 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;
-
-/**
- * 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;
-
-/**
- * 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;
-}
-
-/**
- * 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;
-  /** 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
- */
-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, []);
-  }
-
-  /**
-   * 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
-  // 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,
-    ancestors: ReadonlyArray<Binding>,
-  ): InstantiationPlanCompileResult {
-    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.#compileInjectionThunk(binding.deps[index]!, compileStack, depth, depAncestors);
-        if (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;
-    };
-  }
-
-  /**
-   * 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,
-    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);
-    }
-    if (options !== undefined) {
-      return this.#compileEscapeThunk(token, ancestors, "single", options);
-    }
-    const entry = this.#host.lookupDependencyEntry(token);
-    if (entry === null) {
-      return this.#compileEscapeThunk(token, ancestors);
-    }
-    return this.#compileDepThunk(entry, compileStack, depth, ancestors);
-  }
-
-  #compileClassPlan(
-    binding: Binding & { kind: "class" },
-    compileStack: Set<Binding["id"]>,
-    depth: number,
-    ancestors: ReadonlyArray<Binding>,
-  ): InstantiationPlanCompileResult {
-    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);
-    const depAncestors = [...ancestors, binding];
-    compileStack.add(binding.id);
-    try {
-      for (let index = 0; index < params.length; index += 1) {
-        const thunk = this.#compileInjectionThunk(params[index]!, compileStack, depth, depAncestors);
-        if (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,
-    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 scope = binding.scope;
-    if (scope === "singleton") {
-      // 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 cached = singletonBinding.instance;
-        return cached === NO_INSTANCE ? escape() : cached;
-      };
-    }
-    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;
-      }
-    }
-    // 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);
-  }
-}