@codefast/di 0.7.1 → 0.8.1

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

@@ -1,209 +0,0 @@
-/**
- * Options-less token → terminal binding, memoized per container chain.
- *
- * @remarks Each cache links to its parent's, so a child answers from its own chain without walking
- * 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";
-import type { Constructor } from "#/core/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
- */
-const newNameToEntryMap = <Owner>(): Map<string, DefaultLookupEntry<Owner> | null> => new Map();
-
-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> {
-  readonly #byToken = new Map<Token<unknown> | Constructor, DefaultLookupEntry<Owner> | null>();
-  #version = -1;
-  // One entry in front of the map: the two shapes that reach here — an alias, and a token owned by
-  // a parent — are both resolved in a loop over the same token. `null` is a real answer, so absence
-  // is tracked by the token slot rather than by the entry.
-  #lastToken: Token<unknown> | Constructor | undefined;
-  #lastEntry: DefaultLookupEntry<Owner> | null = null;
-  readonly #byTokenAndName = new Map<Token<unknown> | Constructor, Map<string, DefaultLookupEntry<Owner> | null>>();
-  #namedVersion = -1;
-  readonly #byTokenAndTag = new Map<Token<unknown> | Constructor, Map<BindingTag, DefaultLookupEntry<Owner> | null>>();
-  #taggedVersion = -1;
-  // One entry in front of the tag map, and the map is not written until a second distinct request
-  // shape appears: a per-request child usually asks one (token, tag) once, and the inner-map
-  // allocation was that shape's whole regression when this memo landed.
-  #lastTagToken: Token<unknown> | Constructor | undefined;
-  #lastTag: BindingTag | undefined;
-  #lastTaggedEntry: DefaultLookupEntry<Owner> | null = null;
-
-  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;
-      this.#lastToken = undefined;
-    } else if (token === this.#lastToken) {
-      return this.#lastEntry;
-    }
-    let entry = this.#byToken.get(token);
-    if (entry === undefined) {
-      entry = this.#foldAliases(token);
-      this.#byToken.set(token, entry);
-    }
-    this.#lastToken = token;
-    this.#lastEntry = 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;
-    }
-    // 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);
-      byName.set(name, entry);
-    }
-    return entry;
-  }
-
-  /** `null` when the tag's shape needs the full selection path. */
-  taggedEntry(token: Token<unknown> | Constructor, tag: BindingTag): DefaultLookupEntry<Owner> | null {
-    const version = this.chainVersion();
-    if (version !== this.#taggedVersion) {
-      this.#byTokenAndTag.clear();
-      this.#taggedVersion = version;
-      this.#lastTagToken = undefined;
-      this.#lastTag = undefined;
-    } else if (token === this.#lastTagToken && tag === this.#lastTag) {
-      return this.#lastTaggedEntry;
-    }
-    let entry: DefaultLookupEntry<Owner> | null | undefined;
-    if (this.#lastTagToken === undefined) {
-      // First shape this cache generation sees: answer from the walk and defer the map entirely.
-      entry = this.#findTaggedInChain(token, tag);
-    } 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 = getOrInsertComputed(this.#byTokenAndTag, token, newTagToEntryMap);
-      entry = byTag.get(tag);
-      if (entry === undefined) {
-        entry = this.#findTaggedInChain(token, tag);
-        byTag.set(tag, entry);
-      }
-    }
-    this.#lastTagToken = token;
-    this.#lastTag = tag;
-    this.#lastTaggedEntry = 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);
-  }
-
-  #findTaggedInChain(token: Token<unknown> | Constructor, tag: BindingTag): DefaultLookupEntry<Owner> | null {
-    const tagged = this.#registry.getSimpleTagged(token, tag);
-    if (tagged !== undefined) {
-      // Predicates need a live context; aliases carry options through the full path.
-      if (tagged.predicate !== undefined || tagged.kind === "alias") {
-        return null;
-      }
-      return { binding: tagged, owner: this.#owner };
-    }
-    if (this.#registry.has(token)) {
-      return null;
-    }
-    return this.#parent === undefined ? null : this.#parent.#findTaggedInChain(token, tag);
-  }
-}

package/src/resolution/cache/class-introspector.ts

@@ -1,256 +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 { runWithAmbientResolution } from "#/ambient/active-container";
-import type { AmbientResolution } from "#/ambient/active-container";
-import type { Container } from "#/container/container";
-import type { ConstructorInvocation } from "#/core/constructor-type";
-import type { Constructor } from "#/core/types";
-import { InvalidMetadataError } from "#/errors/errors";
-import type { InjectionDescriptor } from "#/injection/descriptor";
-import type { ConstructorMetadata, LifecycleMetadata, MetadataReader } from "#/metadata/metadata-types";
-
-// Verified pairs, not verified classes: two readers may disagree about the same class, and a reader
-// that goes out of scope takes its record with it.
-const verifiedTargets = new WeakMap<MetadataReader, WeakSet<Constructor>>();
-const verifiedLifecycleTargets = new WeakMap<MetadataReader, WeakSet<Constructor>>();
-const verifiedAccessorTargets = new WeakMap<MetadataReader, WeakSet<Constructor>>();
-
-function isVerified(
-  cache: WeakMap<MetadataReader, WeakSet<Constructor>>,
-  reader: MetadataReader,
-  target: Constructor,
-): boolean {
-  return cache.get(reader)?.has(target) ?? false;
-}
-
-function markVerified(
-  cache: WeakMap<MetadataReader, WeakSet<Constructor>>,
-  reader: MetadataReader,
-  target: Constructor,
-): void {
-  let verified = cache.get(reader);
-  if (verified === undefined) {
-    verified = new WeakSet();
-    cache.set(reader, verified);
-  }
-  verified.add(target);
-}
-
-/**
- * A reader's constructor metadata for a class, verified the first time this process asks.
- *
- * @remarks Metadata cannot change once a class is defined, so re-checking per container would charge
- * every fresh container for a fact already established — a per-request child or a cold boot pays
- * that repeatedly.
- *
- * @since 0.6.0
- */
-export function verifyConstructorMetadata(
-  reader: MetadataReader,
-  target: Constructor,
-): ConstructorMetadata | undefined {
-  const metadata = reader.getConstructorMetadata(target);
-  if (metadata === undefined) {
-    return undefined;
-  }
-  if (isVerified(verifiedTargets, reader, target)) {
-    return metadata;
-  }
-  assertConstructorMetadata(metadata, target);
-  markVerified(verifiedTargets, reader, target);
-
-  return metadata;
-}
-
-/**
- * Verifies what a reader claims about a class, since a `MetadataReader` is a public seam.
- *
- * @remarks Every path that reads constructor metadata comes through here, so a reader that answers
- * wrongly is a named error at the class it described rather than a `TypeError` raised later inside a
- * resolve. Only what a consumer dereferences is checked: `params` and each entry's `token`.
- * `optional`/`multi` degrade to falsy without crashing, and `index` is decorative — dependencies are
- * consumed positionally.
- *
- * @since 0.6.0
- */
-export function assertConstructorMetadata(metadata: unknown, target: Constructor): ConstructorMetadata | undefined {
-  if (metadata === undefined) {
-    return undefined;
-  }
-  if (typeof metadata !== "object" || metadata === null) {
-    throw new InvalidMetadataError(
-      target.name,
-      `constructor metadata: expected an object, received ${typeof metadata}`,
-    );
-  }
-  const params: unknown = Reflect.get(metadata, "params");
-  if (!Array.isArray(params)) {
-    throw new InvalidMetadataError(target.name, "constructor metadata: params is not an array");
-  }
-  for (const [position, param] of params.entries()) {
-    if (typeof param !== "object" || param === null) {
-      throw new InvalidMetadataError(target.name, `constructor metadata: params[${String(position)}] is not an object`);
-    }
-    const dependency: unknown = Reflect.get(param, "token");
-    if (typeof dependency !== "object" && typeof dependency !== "function") {
-      throw new InvalidMetadataError(
-        target.name,
-        `constructor metadata: params[${String(position)}].token is not a token or a class`,
-      );
-    }
-  }
-
-  return metadata as ConstructorMetadata;
-}
-
-/**
- * A reader's lifecycle metadata for a class, verified the first time this process asks.
- *
- * @since 0.6.0
- */
-export function verifyLifecycleMetadata(reader: MetadataReader, target: Constructor): LifecycleMetadata | undefined {
-  const metadata = reader.getLifecycleMetadata(target);
-  if (metadata === undefined || isVerified(verifiedLifecycleTargets, reader, target)) {
-    return metadata;
-  }
-  if (typeof metadata !== "object" || metadata === null) {
-    throw new InvalidMetadataError(target.name, `lifecycle metadata: expected an object, received ${typeof metadata}`);
-  }
-  for (const phase of ["postConstruct", "preDestroy"] as const) {
-    const methods: unknown = Reflect.get(metadata, phase);
-    if (methods === undefined) {
-      continue;
-    }
-    if (!Array.isArray(methods)) {
-      throw new InvalidMetadataError(target.name, `lifecycle metadata: ${phase} is not an array`);
-    }
-    for (const [position, name] of methods.entries()) {
-      if (typeof name !== "string") {
-        throw new InvalidMetadataError(
-          target.name,
-          `lifecycle metadata: ${phase}[${String(position)}] is not a string`,
-        );
-      }
-    }
-  }
-  markVerified(verifiedLifecycleTargets, reader, target);
-  return metadata;
-}
-
-/**
- * A reader's accessor metadata for a class, verified the first time this process asks.
- *
- * @since 0.6.0
- */
-export function verifyAccessorMetadata(
-  reader: MetadataReader,
-  target: Constructor,
-): ReadonlyArray<{ readonly key: string | symbol; readonly descriptor: InjectionDescriptor }> | undefined {
-  const metadata = reader.getAccessorMetadata?.(target);
-  if (metadata === undefined || isVerified(verifiedAccessorTargets, reader, target)) {
-    return metadata;
-  }
-  if (!Array.isArray(metadata)) {
-    throw new InvalidMetadataError(target.name, "accessor metadata: expected an array");
-  }
-  for (const [position, entry] of metadata.entries()) {
-    if (typeof entry !== "object" || entry === null) {
-      throw new InvalidMetadataError(target.name, `accessor metadata: [${String(position)}] is not an object`);
-    }
-    const key: unknown = Reflect.get(entry, "key");
-    if (typeof key !== "string" && typeof key !== "symbol") {
-      throw new InvalidMetadataError(
-        target.name,
-        `accessor metadata: [${String(position)}].key is not a string or symbol`,
-      );
-    }
-    const descriptor: unknown = Reflect.get(entry, "descriptor");
-    if (typeof descriptor !== "object" || descriptor === null) {
-      throw new InvalidMetadataError(
-        target.name,
-        `accessor metadata: [${String(position)}].descriptor is not an object`,
-      );
-    }
-    const dependency: unknown = Reflect.get(descriptor, "token");
-    if (typeof dependency !== "object" && typeof dependency !== "function") {
-      throw new InvalidMetadataError(
-        target.name,
-        `accessor metadata: [${String(position)}].descriptor.token is not a token or a class`,
-      );
-    }
-  }
-  markVerified(verifiedAccessorTargets, reader, target);
-  return metadata;
-}
-
-/**
- * A per-class cache of constructor metadata and the activation facts derived from it.
- *
- * @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<Constructor, ConstructorMetadata | null>()).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<Constructor, boolean>()).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<Constructor, boolean>()).set(target, needsActiveContainer);
-    }
-    return needsActiveContainer;
-  }
-
-  instantiate(target: Constructor, deps: Array<unknown>, resolution?: AmbientResolution): unknown {
-    const invokable = target as ConstructorInvocation;
-    if (!this.needsActiveContainer(target)) {
-      return new invokable(...deps);
-    }
-    return runWithAmbientResolution(this.#container, resolution, () => new invokable(...deps));
-  }
-}