@codefast/di 0.3.16-canary.2 → 0.3.16-canary.3

package/src/index.ts

@@ -0,0 +1,101 @@
+// Foundation types
+export type {
+  ActivationHandler,
+  BindingIdentifier,
+  BindingKind,
+  BindingScope,
+  BindingTag,
+  ConstraintContext,
+  Constructor,
+  DependencyKey,
+  DeactivationHandler,
+  ResolutionFrame,
+  ResolveOptions,
+  ResolutionContext,
+  TokenValue,
+} from "#/types";
+
+// Token
+export { token, tokenName, isToken } from "#/token";
+export type { Token } from "#/token";
+
+// Binding builders — types only
+export type {
+  AliasBindingBuilder,
+  BindToBuilder,
+  BindingBuilder,
+  ConstantBindingBuilder,
+  ScopedBindingBuilder,
+  SingletonBindingBuilder,
+  SingletonLifecycleBuilder,
+  SlotConstrainedBuilder,
+  TransientBindingBuilder,
+} from "#/binding";
+
+// Container
+export { Container } from "#/container";
+export type { Container as ContainerInterface, ContainerStatic } from "#/container";
+
+export { effectiveBindingScope } from "#/binding-scope";
+export { injectionSlotToResolveOptions, bindingSlotToResolveOptions } from "#/resolve-options";
+
+// Introspection types
+export type { BindingSnapshot, ContainerSnapshot } from "#/inspector";
+
+// Graph types
+export type { ContainerGraphJson, GraphEdge, GraphNode, GraphOptions } from "#/dependency-graph";
+
+// Module
+export { AsyncModule, isSyncModule, Module, SyncModule } from "#/module";
+export type { AsyncModuleBuilder, ModuleBuilder } from "#/module";
+
+// Decorators
+export { inject, injectAll, isInjectionDescriptor, optional } from "#/decorators/inject";
+export type { InjectionDescriptor, InjectOptions } from "#/decorators/inject";
+export { injectable } from "#/decorators/injectable";
+export type { InjectableDependency, InjectableOptions } from "#/decorators/injectable";
+export { postConstruct, preDestroy } from "#/decorators/lifecycle-decorators";
+
+// Auto-register
+export { createAutoRegisterRegistry } from "#/decorators/injectable";
+export type { AutoRegisterRegistry } from "#/decorators/injectable";
+
+// MetadataReader
+export { MetadataReaderToken } from "#/metadata/metadata-reader-token";
+export type { MetadataReader, MutableLifecycleMetadata } from "#/metadata/metadata-types";
+
+// Constraints — contextual injection predicates for .when()
+export {
+  whenAnyAncestorIs,
+  whenAnyAncestorNamed,
+  whenAnyAncestorTagged,
+  whenAnyAncestorTaggedAll,
+  whenNoAncestorIs,
+  whenNoParentIs,
+  whenParentIs,
+  whenParentNamed,
+  whenParentTagged,
+  whenParentTaggedAll,
+} from "#/constraints";
+
+// Errors
+export {
+  AmbiguousBindingError,
+  AsyncActivationError,
+  AsyncDeactivationError,
+  AsyncModuleLoadError,
+  AsyncResolutionError,
+  CircularDependencyError,
+  DiError,
+  DisposedContainerError,
+  InternalError,
+  MissingContainerContextError,
+  MissingMetadataError,
+  MissingScopeContextError,
+  NoMatchingBindingError,
+  RebindUnboundTokenError,
+  ScopeViolationError,
+  SyncDisposalNotSupportedError,
+  TokenNotBoundError,
+} from "#/errors";
+export type { ScopeViolationDetails } from "#/errors";

package/src/inspector.ts

@@ -0,0 +1,133 @@
+import type { Binding } from "#/binding";
+import type {
+  BindingIdentifier,
+  BindingKind,
+  BindingScope,
+  BindingTag,
+  ConstraintContext,
+  Constructor,
+  ResolveOptions,
+} from "#/types";
+import type { Token } from "#/token";
+import type { BindingRegistry } from "#/registry";
+import type { ScopeManager } from "#/scope";
+import { tokenName } from "#/token";
+import { selectBinding } from "#/binding-select";
+import { effectiveBindingScope } from "#/binding-scope";
+
+// ── Public types ──────────────────────────────────────────────────────────────
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface BindingSnapshot {
+  readonly tokenName: string;
+  readonly kind: BindingKind;
+  readonly scope: BindingScope;
+  readonly slot: {
+    readonly name?: string;
+    readonly tags: ReadonlyArray<BindingTag>;
+  };
+  readonly id: BindingIdentifier;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ContainerSnapshot {
+  readonly ownBindings: ReadonlyArray<BindingSnapshot>;
+  readonly cachedSingletonCount: number;
+  readonly hasParent: boolean;
+  readonly isDisposed: boolean;
+}
+
+// ── Inspector ─────────────────────────────────────────────────────────────────
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export class Inspector {
+  constructor(
+    private readonly _registry: BindingRegistry,
+    private readonly _scope: ScopeManager,
+    private readonly _hasParent: boolean,
+    private readonly _isDisposed: () => boolean,
+  ) {}
+
+  inspect(): ContainerSnapshot {
+    const snapshots = this.allBindingSnapshots();
+    return {
+      ownBindings: snapshots,
+      cachedSingletonCount: this._scope.getAllSingletons().size,
+      hasParent: this._hasParent,
+      isDisposed: this._isDisposed(),
+    };
+  }
+
+  lookupBindings<Value>(token: Token<Value> | Constructor<Value>): ReadonlyArray<BindingSnapshot> {
+    const bindings = this._registry.getAll(token);
+    return bindings.map((binding) => this._toSnapshot(binding));
+  }
+
+  has(
+    token: Token<unknown> | Constructor,
+    hint?: ResolveOptions,
+    parentHas?: () => boolean,
+  ): boolean {
+    const bindings = this._registry.getAll(token);
+    if (bindings.length > 0) {
+      if (hint !== undefined) {
+        if (
+          selectBinding(bindings, hint, this._makeHintContext(hint), tokenName(token)) !== undefined
+        ) {
+          return true;
+        }
+      } else {
+        return true;
+      }
+    }
+    return parentHas?.() ?? false;
+  }
+
+  hasOwn(token: Token<unknown> | Constructor, hint?: ResolveOptions): boolean {
+    const bindings = this._registry.getAll(token);
+    if (bindings.length === 0) {
+      return false;
+    }
+    if (hint !== undefined) {
+      return (
+        selectBinding(bindings, hint, this._makeHintContext(hint), tokenName(token)) !== undefined
+      );
+    }
+    return true;
+  }
+
+  private _makeHintContext(hint: ResolveOptions): ConstraintContext {
+    return {
+      resolutionPath: [],
+      resolutionStack: [],
+      parent: undefined,
+      ancestors: [],
+      currentResolveHint: hint,
+    };
+  }
+
+  private allBindingSnapshots(): ReadonlyArray<BindingSnapshot> {
+    return this._registry.allBindings().map((binding) => this._toSnapshot(binding));
+  }
+
+  private _toSnapshot(binding: Binding): BindingSnapshot {
+    const scope = effectiveBindingScope(binding);
+    const slot: BindingSnapshot["slot"] =
+      binding.slot.name !== undefined
+        ? { name: binding.slot.name, tags: binding.slot.tags }
+        : { tags: binding.slot.tags };
+    return {
+      tokenName: tokenName(binding.token),
+      kind: binding.kind,
+      scope,
+      slot,
+      id: binding.id,
+    };
+  }
+}

package/src/lifecycle.ts

@@ -0,0 +1,238 @@
+import type {
+  ActivationHandler,
+  Constructor,
+  DeactivationHandler,
+  ResolutionContext,
+} from "#/types";
+import type { Token } from "#/token";
+import type { Binding } from "#/binding";
+import type { MetadataReader } from "#/metadata/metadata-types";
+import { AsyncActivationError, AsyncDeactivationError } from "#/errors";
+import { tokenName } from "#/token";
+
+/**
+ * @since 0.3.16-canary.0
+ */
+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;
+
+  registerActivation<const Value>(
+    token: Token<Value> | Constructor<Value>,
+    handler: ActivationHandler<Value>,
+  ): void {
+    this._activationVersion += 1;
+    // ✓ TS6.0: Map.getOrInsert (ES2025)
+    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) {
+      return false;
+    }
+    const list = this._activationHooks.get(token as Token<unknown> | Constructor);
+    return list !== undefined && list.length > 0;
+  }
+
+  get activationVersion(): number {
+    return this._activationVersion;
+  }
+
+  registerDeactivation<const Value>(
+    token: Token<Value> | Constructor<Value>,
+    handler: DeactivationHandler<Value>,
+  ): void {
+    const list = this._deactivationHooks.getOrInsert(token as Token<unknown> | Constructor, []);
+    list.push(handler as DeactivationHandler<unknown>);
+  }
+
+  async runActivation<const Value>(
+    resolutionContext: ResolutionContext,
+    binding: Binding<Value>,
+    instance: Value,
+    metadataReader: MetadataReader,
+  ): Promise<Value> {
+    let activatedInstance: Value = instance;
+
+    // 1. @postConstruct() — after TC39 construction (constructor + accessor addInitializer callbacks)
+    if (binding.kind === "class") {
+      const lifecycle = metadataReader.getLifecycleMetadata(binding.target);
+      if (lifecycle?.postConstruct && lifecycle.postConstruct.length > 0) {
+        for (const methodName of lifecycle.postConstruct) {
+          const method = (activatedInstance as Record<string, unknown>)[methodName];
+          if (typeof method === "function") {
+            const hookResult = (method as () => unknown).call(activatedInstance);
+            if (hookResult instanceof Promise) {
+              await hookResult;
+            }
+          }
+        }
+      }
+    }
+
+    // 2. per-binding onActivation
+    if (binding.kind !== "alias" && binding.onActivation !== undefined) {
+      const activationResult = binding.onActivation(resolutionContext, activatedInstance);
+      activatedInstance =
+        activationResult instanceof Promise ? await activationResult : activationResult;
+    }
+
+    // 3. container-level onActivation
+    const containerHooks = this._activationHooks.get(binding.token as Token<unknown> | Constructor);
+    if (containerHooks !== undefined) {
+      for (const hook of containerHooks) {
+        const activationResult = hook(resolutionContext, activatedInstance);
+        activatedInstance = (
+          activationResult instanceof Promise ? await activationResult : activationResult
+        ) as Value;
+      }
+    }
+
+    return activatedInstance;
+  }
+
+  runActivationSync<const Value>(
+    resolutionContext: ResolutionContext,
+    binding: Binding<Value>,
+    instance: Value,
+    metadataReader: MetadataReader,
+  ): Value {
+    let activatedInstance: Value = instance;
+
+    // 1. @postConstruct() — must be sync (instance fully constructed per TC39 order)
+    if (binding.kind === "class") {
+      const lifecycle = metadataReader.getLifecycleMetadata(binding.target);
+      if (lifecycle?.postConstruct && lifecycle.postConstruct.length > 0) {
+        for (const methodName of lifecycle.postConstruct) {
+          const method = (activatedInstance as Record<string, unknown>)[methodName];
+          if (typeof method === "function") {
+            const hookResult = (method as () => unknown).call(activatedInstance);
+            if (hookResult instanceof Promise) {
+              throw new AsyncActivationError(tokenName(binding.token), "postConstruct", methodName);
+            }
+          }
+        }
+      }
+    }
+
+    // 2. per-binding onActivation (must be sync)
+    if (binding.kind !== "alias" && binding.onActivation !== undefined) {
+      const activationResult = binding.onActivation(resolutionContext, activatedInstance);
+      if (activationResult instanceof Promise) {
+        throw new AsyncActivationError(tokenName(binding.token), "onActivation");
+      }
+      activatedInstance = activationResult;
+    }
+
+    // 3. container-level onActivation (must be sync)
+    const tokenDisplayName = tokenName(binding.token);
+    const containerHooks = this._activationHooks.get(binding.token as Token<unknown> | Constructor);
+    if (containerHooks !== undefined) {
+      for (const hook of containerHooks) {
+        const activationResult = hook(resolutionContext, activatedInstance);
+        if (activationResult instanceof Promise) {
+          throw new AsyncActivationError(tokenDisplayName, "onActivation");
+        }
+        activatedInstance = activationResult as Value;
+      }
+    }
+
+    return activatedInstance;
+  }
+
+  async runDeactivation<const Value>(
+    binding: Binding<Value>,
+    instance: Value,
+    metadataReader: MetadataReader,
+  ): Promise<void> {
+    const tokenKey = binding.token as Token<unknown> | Constructor;
+
+    // 1. container-level onDeactivation
+    const containerHooks = this._deactivationHooks.get(tokenKey);
+    if (containerHooks !== undefined) {
+      for (const hook of containerHooks) {
+        const hookResult = hook(instance);
+        if (hookResult instanceof Promise) {
+          await hookResult;
+        }
+      }
+    }
+
+    // 2. per-binding onDeactivation
+    if (binding.kind !== "alias" && binding.onDeactivation !== undefined) {
+      const hookResult = binding.onDeactivation(instance);
+      if (hookResult instanceof Promise) {
+        await hookResult;
+      }
+    }
+
+    // 3. @preDestroy() — all methods in declaration order
+    if (binding.kind === "class") {
+      const lifecycle = metadataReader.getLifecycleMetadata(binding.target);
+      if (lifecycle?.preDestroy && lifecycle.preDestroy.length > 0) {
+        for (const methodName of lifecycle.preDestroy) {
+          const method = (instance as Record<string, unknown>)[methodName];
+          if (typeof method === "function") {
+            const hookResult = (method as () => unknown).call(instance);
+            if (hookResult instanceof Promise) {
+              await hookResult;
+            }
+          }
+        }
+      }
+    }
+  }
+
+  runDeactivationSync<const Value>(
+    binding: Binding<Value>,
+    instance: Value,
+    metadataReader: MetadataReader,
+  ): void {
+    const tokenDisplayName = tokenName(binding.token);
+    const tokenKey = binding.token as Token<unknown> | Constructor;
+
+    // 1. container-level onDeactivation
+    const containerHooks = this._deactivationHooks.get(tokenKey);
+    if (containerHooks !== undefined) {
+      for (const hook of containerHooks) {
+        const hookResult = hook(instance);
+        if (hookResult instanceof Promise) {
+          throw new AsyncDeactivationError(tokenDisplayName);
+        }
+      }
+    }
+
+    // 2. per-binding onDeactivation
+    if (binding.kind !== "alias" && binding.onDeactivation !== undefined) {
+      const hookResult = binding.onDeactivation(instance);
+      if (hookResult instanceof Promise) {
+        throw new AsyncDeactivationError(tokenDisplayName);
+      }
+    }
+
+    // 3. @preDestroy()
+    if (binding.kind === "class") {
+      const lifecycle = metadataReader.getLifecycleMetadata(binding.target);
+      if (lifecycle?.preDestroy && lifecycle.preDestroy.length > 0) {
+        for (const methodName of lifecycle.preDestroy) {
+          const method = (instance as Record<string, unknown>)[methodName];
+          if (typeof method === "function") {
+            const hookResult = (method as () => unknown).call(instance);
+            if (hookResult instanceof Promise) {
+              throw new AsyncDeactivationError(tokenDisplayName);
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/metadata/metadata-keys.ts

@@ -0,0 +1,25 @@
+/**
+ * @since 0.3.16-canary.0
+ */
+export const INJECTABLE_KEY: unique symbol = Symbol("di:injectable");
+/**
+ * @since 0.3.16-canary.0
+ */
+export const LIFECYCLE_KEY: unique symbol = Symbol("di:lifecycle");
+/**
+ * @since 0.3.16-canary.0
+ */
+export const INJECT_ACCESSOR_KEY: unique symbol = Symbol("di:inject-accessor");
+
+/**
+ * The well-known symbol used by TC39 Stage 3 decorator transforms to store class metadata.
+ *
+ * `Symbol.metadata` is defined natively once the runtime ships the full TC39 decorator
+ * proposal.  Until then (current Node.js / browsers), Babel and esbuild both fall back to
+ * `Symbol.for("Symbol.metadata")` — a global-registry symbol with the same string key.
+ * Resolving it here once keeps the reader and the decorator transforms in sync regardless
+ * of which path is taken.
+ *
+ * @since 0.3.16-canary.0
+ */
+export const METADATA_SYMBOL: symbol = Symbol.metadata ?? Symbol.for("Symbol.metadata");

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

@@ -0,0 +1,8 @@
+import { token } from "#/token";
+import type { MetadataReader } from "#/metadata/metadata-types";
+import type { Token } from "#/token";
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export const MetadataReaderToken: Token<MetadataReader> = token<MetadataReader>("MetadataReader");

package/src/metadata/metadata-types.ts

@@ -0,0 +1,53 @@
+import type { Constructor } from "#/types";
+import type { Token } from "#/token";
+import type { InjectionDescriptor } from "#/decorators/inject";
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ParamMetadata {
+  readonly index: number;
+  readonly token: Token<unknown> | Constructor;
+  readonly optional: boolean;
+  readonly multi: boolean;
+  readonly name?: string;
+  readonly tags?: ReadonlyArray<readonly [string, unknown]>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ConstructorMetadata {
+  readonly params: ReadonlyArray<ParamMetadata>;
+}
+
+/**
+ * @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>;
+}
+
+/**
+ * @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

@@ -0,0 +1,57 @@
+import type { Constructor } from "#/types";
+import type {
+  ConstructorMetadata,
+  LifecycleMetadata,
+  MetadataReader,
+} from "#/metadata/metadata-types";
+import type { InjectionDescriptor } from "#/decorators/inject";
+import {
+  INJECT_ACCESSOR_KEY,
+  INJECTABLE_KEY,
+  LIFECYCLE_KEY,
+  METADATA_SYMBOL,
+} from "#/metadata/metadata-keys";
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export class SymbolMetadataReader implements MetadataReader {
+  private _getMetadataRecord(
+    target: Constructor,
+    key: string | symbol,
+  ): Record<string | symbol, unknown> | undefined {
+    const descriptor = Object.getOwnPropertyDescriptor(target, METADATA_SYMBOL);
+    if (descriptor === undefined) {
+      return undefined;
+    }
+    const record = descriptor.value as Record<string | symbol, unknown> | null | undefined;
+    if (!record || typeof record !== "object" || !Object.hasOwn(record, key)) {
+      return undefined;
+    }
+    return record;
+  }
+
+  getConstructorMetadata(target: Constructor): ConstructorMetadata | undefined {
+    const record = this._getMetadataRecord(target, INJECTABLE_KEY);
+    return record?.[INJECTABLE_KEY] as ConstructorMetadata | undefined;
+  }
+
+  getLifecycleMetadata(target: Constructor): LifecycleMetadata | undefined {
+    const record = this._getMetadataRecord(target, LIFECYCLE_KEY);
+    return record?.[LIFECYCLE_KEY] as LifecycleMetadata | undefined;
+  }
+
+  getAccessorMetadata(
+    target: Constructor,
+  ): Array<{ key: string | symbol; descriptor: InjectionDescriptor }> | undefined {
+    const record = this._getMetadataRecord(target, INJECT_ACCESSOR_KEY);
+    return record?.[INJECT_ACCESSOR_KEY] as
+      | Array<{ key: string | symbol; descriptor: InjectionDescriptor }>
+      | undefined;
+  }
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export const defaultMetadataReader = new SymbolMetadataReader();