@codefast/di 0.7.1 → 0.8.1

package/src/lifecycle/scope-manager.ts

@@ -1,158 +0,0 @@
-import type { Binding } from "#/core/binding";
-import { NO_INSTANCE } from "#/core/binding";
-import { tokenName } from "#/core/token";
-import type { BindingIdentifier } from "#/core/types";
-import { MissingScopeContextError } from "#/errors/errors";
-
-/**
- * One container's instance caches — singletons, in-flight async creations, and the scoped cache.
- *
- * @since 0.3.16-canary.0
- */
-export class ScopeManager {
-  // Instances live on their binding; this list only lets disposal and `inspect()` enumerate them.
-  #singletonBindings: Array<Binding<unknown>> | undefined;
-  // In-flight promises for async singleton creation — only an async resolve ever needs it.
-  #inflight: Map<BindingIdentifier, Promise<unknown>> | undefined;
-  // Scoped cache — only a child container resolving a `scoped` binding ever needs it.
-  #scoped: Map<BindingIdentifier, unknown> | undefined;
-  // Set once by the owning container's dispose — refuses new materializations into torn-down state.
-  #closed = false;
-
-  readonly isChild: boolean;
-
-  constructor(isChild = false) {
-    this.isChild = isChild;
-  }
-
-  get isClosed(): boolean {
-    return this.#closed;
-  }
-
-  markClosed(): void {
-    this.#closed = true;
-  }
-
-  /** Awaits every in-flight async materialization, so teardown deactivates what they produce. */
-  async settleInflight(): Promise<void> {
-    let previousSize = -1;
-    while (this.#inflight !== undefined && this.#inflight.size > 0 && this.#inflight.size !== previousSize) {
-      previousSize = this.#inflight.size;
-      await Promise.allSettled(this.#inflight.values());
-    }
-  }
-
-  setSingleton<Value>(binding: Binding<Value>, instance: unknown): void {
-    if (binding.instance === NO_INSTANCE) {
-      (this.#singletonBindings ??= []).push(binding as Binding<unknown>);
-    }
-    binding.instance = instance;
-  }
-
-  /** Every binding in this container holding a cached singleton. */
-  cachedSingletons(): ReadonlyArray<Binding<unknown>> {
-    return this.#singletonBindings ?? EMPTY_BINDINGS;
-  }
-
-  deleteSingleton<Value>(binding: Binding<Value>): boolean {
-    if (binding.instance === NO_INSTANCE) {
-      return false;
-    }
-    binding.instance = NO_INSTANCE;
-    const tracked = this.#singletonBindings;
-    if (tracked !== undefined) {
-      const index = tracked.indexOf(binding as Binding<unknown>);
-      if (index !== -1) {
-        tracked.splice(index, 1);
-      }
-    }
-    return true;
-  }
-
-  /** Swaps a re-slotted binding's tracked entry, so teardown pairs the instance with the live object. */
-  replaceSingleton(previous: Binding, next: Binding): void {
-    const tracked = this.#singletonBindings;
-    if (tracked === undefined) {
-      return;
-    }
-    const index = tracked.indexOf(previous as Binding<unknown>);
-    if (index !== -1) {
-      tracked[index] = next as Binding<unknown>;
-    }
-  }
-
-  getInflight(id: BindingIdentifier): Promise<unknown> | undefined {
-    return this.#inflight?.get(id);
-  }
-
-  setInflight(id: BindingIdentifier, promise: Promise<unknown>): void {
-    (this.#inflight ??= new Map<BindingIdentifier, Promise<unknown>>()).set(id, promise);
-  }
-
-  clearInflight(id: BindingIdentifier): void {
-    this.#inflight?.delete(id);
-  }
-
-  /**
-   * The cached scoped instance, or {@link SCOPED_MISS}.
-   *
-   * @remarks One map read answers both existence and value; a cached `undefined` is the only
-   * shape that pays for a second, and it is the rare one.
-   */
-  readScoped(id: BindingIdentifier): unknown {
-    const scoped = this.#scoped;
-    if (scoped === undefined) {
-      return SCOPED_MISS;
-    }
-    const cached = scoped.get(id);
-    if (cached !== undefined) {
-      return cached;
-    }
-    return scoped.has(id) ? undefined : SCOPED_MISS;
-  }
-
-  /** Takes the binding rather than its id, so a failure here can name the token — as `setSingleton` does. */
-  setScoped(binding: Binding, instance: unknown): void {
-    if (!this.isChild) {
-      throw new MissingScopeContextError(tokenName(binding.token));
-    }
-    (this.#scoped ??= new Map<BindingIdentifier, unknown>()).set(binding.id, instance);
-  }
-
-  /** Releases a removed binding's scoped instance. A scoped instance has no deactivation. */
-  deleteScoped(id: BindingIdentifier): void {
-    this.#scoped?.delete(id);
-  }
-
-  /** Scoped instances currently cached — a structural count for diagnostics. */
-  get scopedCount(): number {
-    return this.#scoped?.size ?? 0;
-  }
-
-  clearAll(): void {
-    const tracked = this.#singletonBindings;
-    if (tracked !== undefined) {
-      for (const binding of tracked) {
-        binding.instance = NO_INSTANCE;
-      }
-      tracked.length = 0;
-    }
-    this.#inflight?.clear();
-    this.#scoped?.clear();
-  }
-  /** Whether the deferred scoped-instance cache has had to be built. */
-  get isScopedCacheBuilt(): boolean {
-    return this.#scoped !== undefined;
-  }
-}
-
-const EMPTY_BINDINGS: ReadonlyArray<Binding<unknown>> = [];
-
-/**
- * Absent scoped entry — distinguishes it from a cached `undefined`.
- *
- * @remarks A `unique symbol`, so no value a caller could cache can ever equal it.
- *
- * @since 0.6.0
- */
-export const SCOPED_MISS: unique symbol = Symbol("di:scoped-miss");

package/src/metadata/metadata-keys.ts

@@ -1,28 +0,0 @@
-/**
- * The metadata key `@injectable` writes a class's constructor dependencies under.
- *
- * @since 0.3.16-canary.0
- */
-export const INJECTABLE_KEY: unique symbol = Symbol("di:injectable");
-/**
- * The metadata key `@postConstruct` and `@preDestroy` record method names under.
- *
- * @since 0.3.16-canary.0
- */
-export const LIFECYCLE_KEY: unique symbol = Symbol("di:lifecycle");
-/**
- * The metadata key `@inject` accessors record their injection descriptors under.
- *
- * @since 0.3.16-canary.0
- */
-export const INJECT_ACCESSOR_KEY: unique symbol = Symbol("di:inject-accessor");
-
-/**
- * The symbol TC39 Stage 3 decorator transforms store class metadata under.
- *
- * @remarks Falls back to the global-registry symbol, which is what Babel and esbuild emit until
- * a runtime ships `Symbol.metadata` natively.
- *
- * @since 0.3.16-canary.0
- */
-export const METADATA_SYMBOL: symbol = Symbol.metadata ?? Symbol.for("Symbol.metadata");

package/src/metadata/metadata-reader-token.ts

@@ -1,10 +0,0 @@
-import { token } from "#/core/token";
-import type { Token } from "#/core/token";
-import type { MetadataReader } from "#/metadata/metadata-types";
-
-/**
- * The token a custom `MetadataReader` is bound to for a container to pick up.
- *
- * @since 0.3.16-canary.0
- */
-export const MetadataReaderToken: Token<MetadataReader> = token<MetadataReader>("MetadataReader");

package/src/metadata/metadata-types.ts

@@ -1,57 +0,0 @@
-import type { Constructor } from "#/core/types";
-import type { InjectionDescriptor } from "#/injection/descriptor";
-import type { DependencySlot } from "#/injection/resolve-options";
-
-/**
- * One constructor parameter's declaration.
- *
- * @remarks Extends {@link DependencySlot} so the two dependency sources stay literally one shape
- * rather than two that happen to match; `index` is the only thing a parameter adds.
- *
- * @since 0.3.16-canary.0
- */
-export interface ParamMetadata extends DependencySlot {
-  readonly index: number;
-}
-
-/**
- * A class's declared constructor dependencies, as a `MetadataReader` reports them.
- *
- * @since 0.3.16-canary.0
- */
-export interface ConstructorMetadata {
-  readonly params: ReadonlyArray<ParamMetadata>;
-}
-
-/**
- * The `postConstruct` and `preDestroy` method names a class declares.
- *
- * @since 0.3.16-canary.0
- */
-export interface LifecycleMetadata {
-  readonly postConstruct: ReadonlyArray<string>;
-  readonly preDestroy: ReadonlyArray<string>;
-}
-
-/**
- * Mutable buckets used while aggregating decorator metadata (same keys as {@link LifecycleMetadata}).
- *
- * @since 0.3.16-canary.0
- */
-export interface MutableLifecycleMetadata {
-  postConstruct: Array<string>;
-  preDestroy: Array<string>;
-}
-
-/**
- * The port a container reads class metadata through — constructor deps, lifecycle, and accessors.
- *
- * @since 0.3.16-canary.0
- */
-export interface MetadataReader {
-  getConstructorMetadata(target: Constructor): ConstructorMetadata | undefined;
-  getLifecycleMetadata(target: Constructor): LifecycleMetadata | undefined;
-  getAccessorMetadata?(
-    target: Constructor,
-  ): ReadonlyArray<{ readonly key: string | symbol; readonly descriptor: InjectionDescriptor }> | undefined;
-}

package/src/metadata/symbol-metadata-reader.ts

@@ -1,126 +0,0 @@
-import type { Constructor } from "#/core/types";
-import type { InjectionDescriptor } from "#/injection/descriptor";
-import { INJECT_ACCESSOR_KEY, INJECTABLE_KEY, LIFECYCLE_KEY, METADATA_SYMBOL } from "#/metadata/metadata-keys";
-import type { ConstructorMetadata, LifecycleMetadata, MetadataReader } from "#/metadata/metadata-types";
-
-type AccessorEntry = { readonly key: string | symbol; readonly descriptor: InjectionDescriptor };
-
-/**
- * The default `MetadataReader`, reading decorator metadata stored under `Symbol.metadata`.
- *
- * @since 0.3.16-canary.0
- */
-export class SymbolMetadataReader implements MetadataReader {
-  // Merged chain answers, cached per class: decorator metadata cannot change once a class is defined.
-  #lifecycleByClass: WeakMap<Constructor, LifecycleMetadata | null> | undefined;
-  #accessorsByClass: WeakMap<Constructor, ReadonlyArray<AccessorEntry> | null> | undefined;
-
-  /**
-   * Whatever a decorator stored under `key` on this exact class, narrowed as far as the platform allows.
-   *
-   * @remarks Own-property only: an inherited `Symbol.metadata` belongs to the base class. Constructor
-   * metadata must not be borrowed (each class opts into its deps); the lifecycle and accessor readers
-   * walk the base chain themselves, because the platform runs inherited members regardless.
-   */
-  #read(target: object, key: string | symbol): unknown {
-    const descriptor = Object.getOwnPropertyDescriptor(target, METADATA_SYMBOL);
-    if (descriptor === undefined) {
-      return undefined;
-    }
-    const record: unknown = descriptor.value;
-    if (typeof record !== "object" || record === null || !Object.hasOwn(record, key)) {
-      return undefined;
-    }
-    return Reflect.get(record, key);
-  }
-
-  /** Each class level's own bucket under `key`, base first — the order construction runs them. */
-  #ownBucketsBaseFirst(target: Constructor, key: string | symbol): Array<unknown> {
-    const buckets: Array<unknown> = [];
-    let current: unknown = target;
-    while (typeof current === "function" && current !== Function.prototype) {
-      const bucket = this.#read(current, key);
-      if (bucket !== undefined) {
-        buckets.unshift(bucket);
-      }
-      current = Object.getPrototypeOf(current);
-    }
-    return buckets;
-  }
-
-  getConstructorMetadata(target: Constructor): ConstructorMetadata | undefined {
-    return this.#read(target, INJECTABLE_KEY) as ConstructorMetadata | undefined;
-  }
-
-  /**
-   * Lifecycle hooks aggregated over the base chain — an inherited hook method exists on the instance.
-   *
-   * @remarks `postConstruct` runs base first (a derived hook may rely on base state); `preDestroy`
-   * runs derived first, mirroring teardown. A method name repeated across levels runs once.
-   */
-  getLifecycleMetadata(target: Constructor): LifecycleMetadata | undefined {
-    const cached = this.#lifecycleByClass?.get(target);
-    if (cached !== undefined) {
-      return cached ?? undefined;
-    }
-    const buckets = this.#ownBucketsBaseFirst(target, LIFECYCLE_KEY) as Array<LifecycleMetadata>;
-    let merged: LifecycleMetadata | null;
-    if (buckets.length === 0) {
-      merged = null;
-    } else if (buckets.length === 1) {
-      merged = buckets[0]!;
-    } else {
-      merged = {
-        postConstruct: mergeUniqueNames(buckets.map((bucket) => bucket.postConstruct)),
-        preDestroy: mergeUniqueNames(buckets.map((bucket) => bucket.preDestroy).reverse()),
-      };
-    }
-    (this.#lifecycleByClass ??= new WeakMap<Constructor, LifecycleMetadata | null>()).set(target, merged);
-    return merged ?? undefined;
-  }
-
-  /**
-   * Accessor injections aggregated over the base chain, base first — the order initializers run.
-   *
-   * @remarks Not deduplicated: a derived accessor shadowing a base one still runs both initializers.
-   */
-  getAccessorMetadata(target: Constructor): ReadonlyArray<AccessorEntry> | undefined {
-    const cached = this.#accessorsByClass?.get(target);
-    if (cached !== undefined) {
-      return cached ?? undefined;
-    }
-    const buckets = this.#ownBucketsBaseFirst(target, INJECT_ACCESSOR_KEY) as Array<ReadonlyArray<AccessorEntry>>;
-    let merged: ReadonlyArray<AccessorEntry> | null;
-    if (buckets.length === 0) {
-      merged = null;
-    } else if (buckets.length === 1) {
-      merged = buckets[0]!;
-    } else {
-      merged = buckets.flat();
-    }
-    (this.#accessorsByClass ??= new WeakMap<Constructor, ReadonlyArray<AccessorEntry> | null>()).set(target, merged);
-    return merged ?? undefined;
-  }
-}
-
-/** Concatenates hook-name lists in the given order, keeping each name's first occurrence. */
-function mergeUniqueNames(lists: Array<ReadonlyArray<string>>): Array<string> {
-  const seen = new Set<string>();
-  const merged: Array<string> = [];
-  for (const list of lists) {
-    for (const name of list) {
-      if (!seen.has(name)) {
-        seen.add(name);
-        merged.push(name);
-      }
-    }
-  }
-  return merged;
-}
-
-/**
- * The shared reader a container falls back to when given no custom `MetadataReader`.
- *
- * @since 0.3.16-canary.0
- */
-export const defaultMetadataReader: SymbolMetadataReader = new SymbolMetadataReader();

package/src/metadata/verifying-metadata-reader.ts

@@ -1,41 +0,0 @@
-/**
- * Wraps a foreign {@link MetadataReader} so its answers are verified before anything dereferences
- * them.
- */
-
-import type { MetadataReader } from "#/metadata/metadata-types";
-import { defaultMetadataReader } from "#/metadata/symbol-metadata-reader";
-import {
-  verifyAccessorMetadata,
-  verifyConstructorMetadata,
-  verifyLifecycleMetadata,
-} from "#/resolution/cache/class-introspector";
-
-// Wrapping a wrapper would stack a layer per child container, so each one is remembered.
-const verifyingReaders = new WeakSet<MetadataReader>();
-
-/**
- * The reader a container should hand its resolver: verified when it came from outside.
- *
- * @remarks The decorator reader writes the metadata it later reads, so there is nothing to check and
- * nothing to pay — a container that supplies no reader of its own is left on the same code path it
- * has always taken. A supplied reader is a claim, and only its callers can be charged for checking.
- *
- * @since 0.6.0
- */
-export function verifyingMetadataReader(reader: MetadataReader): MetadataReader {
-  if (reader === defaultMetadataReader || verifyingReaders.has(reader)) {
-    return reader;
-  }
-  const verifying: MetadataReader = {
-    getConstructorMetadata: (target) => verifyConstructorMetadata(reader, target),
-    getLifecycleMetadata: (target) => verifyLifecycleMetadata(reader, target),
-    ...(reader.getAccessorMetadata === undefined
-      ? {}
-      : { getAccessorMetadata: (target) => verifyAccessorMetadata(reader, target) }),
-  };
-
-  verifyingReaders.add(verifying);
-
-  return verifying;
-}

package/src/resolution/cache/activation-need.ts

@@ -1,87 +0,0 @@
-/**
- * Per binding: does resolving it have to go through the activation pipeline?
- *
- * @remarks Versioned on the lifecycle manager plus the own registry, since `onActivation` can be
- * registered at any time and a rebind mints binding ids the memo must not keep forever.
- */
-import type { Binding } from "#/core/binding";
-import type { BindingRegistry } from "#/core/registry";
-import type { BindingIdentifier } from "#/core/types";
-import type { LifecycleManager } from "#/lifecycle/lifecycle-manager";
-import type { ClassIntrospector } from "#/resolution/cache/class-introspector";
-
-/**
- * A per-binding cache of whether activation work — hooks or `@postConstruct` — is needed on resolve.
- *
- * @since 0.5.0-canary.8
- */
-export class ActivationNeedCache {
-  readonly #needByBindingId = new Map<BindingIdentifier, boolean>();
-  #version = -1;
-  readonly #lifecycle: LifecycleManager;
-  readonly #classes: ClassIntrospector;
-  readonly #registry: BindingRegistry;
-
-  constructor(lifecycle: LifecycleManager, classes: ClassIntrospector, registry: BindingRegistry) {
-    this.#lifecycle = lifecycle;
-    this.#classes = classes;
-    this.#registry = registry;
-  }
-
-  needsActivation<Value>(binding: Binding<Value>): boolean {
-    // The chain writes a binding's own hook in place with no version anything here can see, so it
-    // is read fresh on every call; the memo covers only container hooks and lifecycle metadata.
-    if (binding.kind !== "alias" && binding.onActivation !== undefined) {
-      return true;
-    }
-    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") {
-      return false;
-    }
-    // The registry version evicts entries for binding ids a rebind has retired.
-    const version = lifecycleVersion + this.#registry.version;
-    if (this.#version !== version) {
-      this.#needByBindingId.clear();
-      this.#version = version;
-    }
-    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);
-  }
-
-  // Own hooks are answered before the memo, so both computations cover the memoizable rest only.
-  #classNeedsActivation<Value>(binding: Binding<Value> & { kind: "class" }): boolean {
-    if (this.#lifecycle.hasActivationHandlers(binding.token)) {
-      return true;
-    }
-    // Unknown lifecycle metadata: activate once so the first instantiation can settle it.
-    return this.#classes.knownPostConstruct(binding.target) !== false;
-  }
-
-  #nonClassNeedsActivation<Value>(binding: Binding<Value>): boolean {
-    return this.#lifecycle.hasActivationHandlers(binding.token);
-  }
-}