@codefast/di 0.7.1 → 0.8.1

package/src/introspection/graph-adapters/cytoscape.ts

@@ -1,78 +0,0 @@
-import type { ContainerGraphJson, GraphNode } from "#/introspection/dependency-graph";
-
-/**
- * A dependency-graph node in Cytoscape's element format.
- *
- * @since 0.3.16-canary.0
- */
-export interface CytoscapeNode {
-  readonly data: {
-    readonly id: string;
-    readonly label: string;
-    readonly tokenKey: string;
-    readonly kind: GraphNode["kind"];
-    readonly scope: GraphNode["scope"];
-    readonly fromParent: boolean;
-  };
-}
-
-/**
- * A dependency-graph edge in Cytoscape's element format.
- *
- * @since 0.3.16-canary.0
- */
-export interface CytoscapeEdge {
-  readonly data: {
-    readonly id: string;
-    readonly source: string;
-    readonly target: string;
-    readonly label?: string;
-    readonly optional: boolean;
-    readonly slotName?: string;
-  };
-}
-
-/**
- * The flat node-and-edge list Cytoscape takes as its `elements` input.
- *
- * @since 0.3.16-canary.0
- */
-export type CytoscapeElements = ReadonlyArray<CytoscapeNode | CytoscapeEdge>;
-
-/**
- * Converts a container's dependency graph into Cytoscape's element list.
- *
- * @since 0.3.16-canary.0
- */
-export function toCytoscapeGraph(graph: ContainerGraphJson): CytoscapeElements {
-  const elements: Array<CytoscapeNode | CytoscapeEdge> = [];
-
-  for (const node of graph.nodes) {
-    elements.push({
-      data: {
-        id: node.id,
-        label: node.tokenName,
-        tokenKey: node.tokenKey,
-        kind: node.kind,
-        scope: node.scope,
-        fromParent: node.fromParent,
-      },
-    });
-  }
-
-  for (let idx = 0; idx < graph.edges.length; idx += 1) {
-    const edge = graph.edges[idx]!;
-    elements.push({
-      data: {
-        id: `edge-${idx}`,
-        source: edge.from,
-        target: edge.to,
-        ...(edge.label !== undefined ? { label: edge.label } : {}),
-        optional: edge.optional,
-        ...(edge.slotName !== undefined ? { slotName: edge.slotName } : {}),
-      },
-    });
-  }
-
-  return elements;
-}

package/src/introspection/graph-adapters/dot.ts

@@ -1,32 +0,0 @@
-import type { ContainerGraphJson } from "#/introspection/dependency-graph";
-
-// Token names are caller-supplied and land inside DOT quoted strings — ids included, since an
-// unbound placeholder id embeds the name it was minted from.
-function escapeDotString(value: string): string {
-  return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
-}
-
-/**
- * Renders a container's dependency graph as Graphviz DOT source.
- *
- * @since 0.3.16-canary.0
- */
-export function toDotGraph(graph: ContainerGraphJson): string {
-  const lines: Array<string> = ["digraph DI {", "  rankdir=TB;"];
-
-  for (const node of graph.nodes) {
-    const label = `${escapeDotString(node.tokenName)}\\n[${node.kind}/${node.scope}]`;
-    // Dashed for anything that is not a live binding of this container: the parent chain
-    // and unbound-optional placeholders.
-    const style = node.fromParent || node.kind === "unbound" ? ' style="dashed"' : "";
-    lines.push(`  "${escapeDotString(node.id)}" [label="${label}"${style}];`);
-  }
-
-  for (const edge of graph.edges) {
-    const label = edge.label === undefined ? "" : ` [label="${escapeDotString(edge.label)}"]`;
-    lines.push(`  "${escapeDotString(edge.from)}" -> "${escapeDotString(edge.to)}"${label};`);
-  }
-
-  lines.push("}");
-  return lines.join("\n");
-}

package/src/introspection/graph-adapters/mermaid.ts

@@ -1,61 +0,0 @@
-import type { ContainerGraphJson } from "#/introspection/dependency-graph";
-
-// Token names are caller-supplied and Mermaid labels are HTML-bearing quoted strings, so quotes
-// and markup are neutralized with Mermaid's decimal entity codes before they reach a renderer.
-function escapeMermaidLabel(value: string): string {
-  return value.replaceAll("&", "#38;").replaceAll('"', "#34;").replaceAll("<", "#60;").replaceAll(">", "#62;");
-}
-
-/**
- * Mermaid `flowchart TD` source for a container graph — renders anywhere Mermaid does
- * (GitHub markdown, docs tooling, mermaid.live) with no extra library.
- *
- * @since 0.6.0
- */
-export function toMermaidGraph(graph: ContainerGraphJson): string {
-  // Mermaid identifiers must stay word-safe; labels carry the real token names.
-  const idByNode = new Map<string, string>();
-  const lines: Array<string> = ["flowchart TD"];
-  const parentIds: Array<string> = [];
-  const unboundIds: Array<string> = [];
-
-  graph.nodes.forEach((node, index) => {
-    const id = `n${String(index)}`;
-
-    idByNode.set(node.id, id);
-    lines.push(`  ${id}["${escapeMermaidLabel(node.tokenName)}<br/>${node.kind} · ${node.scope}"]`);
-
-    if (node.fromParent) {
-      parentIds.push(id);
-    }
-
-    if (node.kind === "unbound") {
-      unboundIds.push(id);
-    }
-  });
-
-  for (const edge of graph.edges) {
-    const from = idByNode.get(edge.from);
-    const to = idByNode.get(edge.to);
-
-    if (from === undefined || to === undefined) {
-      continue;
-    }
-
-    lines.push(
-      edge.label === undefined ? `  ${from} --> ${to}` : `  ${from} -->|"${escapeMermaidLabel(edge.label)}"| ${to}`,
-    );
-  }
-
-  if (parentIds.length > 0) {
-    lines.push("  classDef fromParent stroke-dasharray: 4 4;");
-    lines.push(`  class ${parentIds.join(",")} fromParent;`);
-  }
-
-  if (unboundIds.length > 0) {
-    lines.push("  classDef unbound stroke-dasharray: 4 4,opacity:0.6;");
-    lines.push(`  class ${unboundIds.join(",")} unbound;`);
-  }
-
-  return lines.join("\n");
-}

package/src/introspection/graph-adapters/reactflow.ts

@@ -1,84 +0,0 @@
-import type { ContainerGraphJson, GraphNode } from "#/introspection/dependency-graph";
-
-/**
- * A dependency-graph node in React Flow's node format.
- *
- * @since 0.3.16-canary.0
- */
-export interface ReactFlowNode {
-  readonly id: string;
-  readonly data: {
-    readonly label: string;
-    readonly tokenKey: string;
-    readonly kind: GraphNode["kind"];
-    readonly scope: GraphNode["scope"];
-    readonly fromParent: boolean;
-  };
-  readonly position: { readonly x: number; readonly y: number };
-}
-
-/**
- * A dependency-graph edge in React Flow's edge format.
- *
- * @since 0.3.16-canary.0
- */
-export interface ReactFlowEdge {
-  readonly id: string;
-  readonly source: string;
-  readonly target: string;
-  readonly label?: string;
-  readonly optional: boolean;
-  readonly slotName?: string;
-}
-
-/**
- * The nodes-and-edges pair a React Flow viewer renders.
- *
- * @since 0.3.16-canary.0
- */
-export interface ReactFlowGraph {
-  readonly nodes: ReadonlyArray<ReactFlowNode>;
-  readonly edges: ReadonlyArray<ReactFlowEdge>;
-}
-
-/**
- * Initial grid layout: React Flow expects concrete positions; viewers re-layout anyway.
- *
- * @since 0.3.16-canary.0
- */
-const GRID_COLUMN_COUNT = 5;
-const GRID_CELL_WIDTH_PX = 200;
-const GRID_CELL_HEIGHT_PX = 100;
-
-/**
- * Converts a container's dependency graph into React Flow nodes and edges on an initial grid.
- *
- * @since 0.5.0-canary.7
- */
-export function toReactFlowGraph(graph: ContainerGraphJson): ReactFlowGraph {
-  const nodes: Array<ReactFlowNode> = graph.nodes.map((node, idx) => ({
-    id: node.id,
-    data: {
-      label: node.tokenName,
-      tokenKey: node.tokenKey,
-      kind: node.kind,
-      scope: node.scope,
-      fromParent: node.fromParent,
-    },
-    position: {
-      x: (idx % GRID_COLUMN_COUNT) * GRID_CELL_WIDTH_PX,
-      y: Math.floor(idx / GRID_COLUMN_COUNT) * GRID_CELL_HEIGHT_PX,
-    },
-  }));
-
-  const edges: Array<ReactFlowEdge> = graph.edges.map((edge, idx) => ({
-    id: `edge-${idx}`,
-    source: edge.from,
-    target: edge.to,
-    ...(edge.label !== undefined ? { label: edge.label } : {}),
-    optional: edge.optional,
-    ...(edge.slotName !== undefined ? { slotName: edge.slotName } : {}),
-  }));
-
-  return { nodes, edges };
-}

package/src/introspection/inspector.ts

@@ -1,134 +0,0 @@
-import type { Binding } from "#/core/binding";
-import { effectiveBindingScope } from "#/core/binding-scope";
-import type { BindingRegistry } from "#/core/registry";
-import type { Token } from "#/core/token";
-import { tokenName } from "#/core/token";
-import type {
-  BindingIdentifier,
-  BindingKind,
-  BindingScope,
-  BindingTag,
-  ConstraintContext,
-  Constructor,
-  ResolveOptions,
-} from "#/core/types";
-import type { ScopeManager } from "#/lifecycle/scope-manager";
-import { selectAllBindings } from "#/resolution/select/binding-select";
-
-// ── Public types ─────────────────────────────────────────────────────────────────────────────────────────────────────
-
-/**
- * A read-only view of one binding: token, kind, scope, slot, and id.
- *
- * @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;
-}
-
-/**
- * A read-only view of one container's own bindings and state.
- *
- * @since 0.3.16-canary.0
- */
-export interface ContainerSnapshot {
-  readonly ownBindings: ReadonlyArray<BindingSnapshot>;
-  readonly cachedSingletonCount: number;
-  readonly hasParent: boolean;
-  readonly isDisposed: boolean;
-}
-
-// ── Inspector ────────────────────────────────────────────────────────────────────────────────────────────────────────
-
-/**
- * The read-only introspection surface behind a container's `inspect()`.
- *
- * @since 0.3.16-canary.0
- */
-export class Inspector {
-  readonly #registry: BindingRegistry;
-  readonly #scope: ScopeManager;
-  readonly #hasParent: boolean;
-  readonly #isDisposed: () => boolean;
-
-  constructor(registry: BindingRegistry, scope: ScopeManager, hasParent: boolean, isDisposed: () => boolean) {
-    this.#registry = registry;
-    this.#scope = scope;
-    this.#hasParent = hasParent;
-    this.#isDisposed = isDisposed;
-  }
-
-  inspect(): ContainerSnapshot {
-    return {
-      ownBindings: this.#registry.allBindings().map((binding) => this.#toSnapshot(binding)),
-      cachedSingletonCount: this.#scope.cachedSingletons().length,
-      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, options?: ResolveOptions, parentHas?: () => boolean): boolean {
-    const bindings = this.#registry.getAll(token);
-    if (bindings.length > 0) {
-      // An existence probe answers ambiguity with `true` — several matches still exist; only
-      // resolution has to pick one.
-      if (options !== undefined) {
-        if (selectAllBindings(bindings, options, this.#makeConstraintContext(options)).length > 0) {
-          return true;
-        }
-      } else {
-        return true;
-      }
-    }
-    return parentHas?.() ?? false;
-  }
-
-  hasOwn(token: Token<unknown> | Constructor, options?: ResolveOptions): boolean {
-    const bindings = this.#registry.getAll(token);
-    if (bindings.length === 0) {
-      return false;
-    }
-    if (options !== undefined) {
-      return selectAllBindings(bindings, options, this.#makeConstraintContext(options)).length > 0;
-    }
-    return true;
-  }
-
-  #makeConstraintContext(options: ResolveOptions): ConstraintContext {
-    return {
-      resolutionPath: [],
-      resolutionStack: [],
-      parent: undefined,
-      ancestors: [],
-      currentResolveOptions: options,
-    };
-  }
-
-  #toSnapshot(binding: Binding): BindingSnapshot {
-    // Aliased, not copied: slot tags are frozen where they are built, so a caller's write throws
-    // instead of corrupting the registry — and the snapshot skips an allocation per 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: effectiveBindingScope(binding),
-      slot,
-      id: binding.id,
-    };
-  }
-}

package/src/lifecycle/lifecycle-manager.ts

@@ -1,272 +0,0 @@
-import type { Binding } from "#/core/binding";
-import { getOrInsert } from "#/core/map-upsert";
-import type { Token } from "#/core/token";
-import { tokenName } from "#/core/token";
-import type {
-  ActivationHandler,
-  Constructor,
-  DeactivationHandler,
-  DependencyKey,
-  ResolutionContext,
-} from "#/core/types";
-import { AsyncActivationError, AsyncDeactivationError, InvalidMetadataError } from "#/errors/errors";
-import type { MetadataReader } from "#/metadata/metadata-types";
-
-/**
- * One container's registry of container-level activation and deactivation hooks, keyed by token.
- *
- * @since 0.3.16-canary.0
- */
-export class LifecycleManager {
-  // Container-level activation/deactivation hooks per token — most containers register none, so
-  // both tables stay unallocated until the first hook arrives.
-  #activationHooks: Map<DependencyKey, Array<ActivationHandler<unknown>>> | undefined;
-  #deactivationHooks: Map<DependencyKey, Array<DeactivationHandler<unknown>>> | undefined;
-  #activationVersion = 0;
-
-  // One-entry cache in front of the map: a resolve loop asks about the same token over and over,
-  // and registration is the only thing that can change the answer.
-  #cachedToken: Token<unknown> | Constructor | undefined;
-  #cachedHooks: Array<ActivationHandler<unknown>> | undefined;
-
-  registerActivation<Value>(token: Token<Value> | Constructor<Value>, handler: ActivationHandler<Value>): void {
-    this.#activationVersion += 1;
-    this.#cachedToken = undefined;
-    this.#cachedHooks = undefined;
-    this.#activationHooks ??= new Map();
-    const list = getOrInsert(this.#activationHooks, token, []);
-    list.push(handler as ActivationHandler<unknown>);
-  }
-
-  hasActivationHandlers<Value>(token: Token<Value> | Constructor<Value>): boolean {
-    const list = this.activationHandlersFor(token);
-    return list !== undefined && list.length > 0;
-  }
-
-  get activationVersion(): number {
-    return this.#activationVersion;
-  }
-
-  /** Container-level activation handlers for a token — hot-path accessor, no copies. */
-  activationHandlersFor<Value>(
-    token: Token<Value> | Constructor<Value>,
-  ): ReadonlyArray<ActivationHandler<unknown>> | undefined {
-    const hooks = this.#activationHooks;
-    if (hooks === undefined) {
-      return undefined;
-    }
-    const key: DependencyKey = token;
-    if (key === this.#cachedToken) {
-      return this.#cachedHooks;
-    }
-    const list = hooks.get(key);
-    this.#cachedToken = key;
-    this.#cachedHooks = list;
-    return list;
-  }
-
-  registerDeactivation<Value>(token: Token<Value> | Constructor<Value>, handler: DeactivationHandler<Value>): void {
-    this.#deactivationHooks ??= new Map();
-    const list = getOrInsert(this.#deactivationHooks, token, []);
-    list.push(handler as DeactivationHandler<unknown>);
-  }
-
-  /** Asked only while tearing down, so it reads the map directly rather than caching like activation. */
-  hasDeactivationHandlers<Value>(token: Token<Value> | Constructor<Value>): boolean {
-    const list = this.#deactivationHooks?.get(token);
-    return list !== undefined && list.length > 0;
-  }
-
-  /** Every token carrying a container-level hook, paired with the phase that registered it. */
-  hookedTokens(): Array<[DependencyKey, "onActivation" | "onDeactivation"]> {
-    const hooked: Array<[DependencyKey, "onActivation" | "onDeactivation"]> = [];
-    for (const key of this.#activationHooks?.keys() ?? []) {
-      hooked.push([key, "onActivation"]);
-    }
-    for (const key of this.#deactivationHooks?.keys() ?? []) {
-      hooked.push([key, "onDeactivation"]);
-    }
-    return hooked;
-  }
-
-  async runActivation<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)
-    for (const methodName of lifecycleMethods(binding, metadataReader, "postConstruct")) {
-      const hookResult = callHook(activatedInstance, methodName);
-      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);
-    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<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)
-    for (const methodName of lifecycleMethods(binding, metadataReader, "postConstruct")) {
-      if (callHook(activatedInstance, methodName) 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);
-    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<Value>(
-    binding: Binding<Value>,
-    instance: Value,
-    metadataReader: MetadataReader,
-  ): Promise<void> {
-    const tokenKey: DependencyKey = binding.token;
-
-    // 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
-    for (const methodName of lifecycleMethods(binding, metadataReader, "preDestroy")) {
-      const hookResult = callHook(instance, methodName);
-      if (hookResult instanceof Promise) {
-        await hookResult;
-      }
-    }
-  }
-
-  runDeactivationSync<Value>(binding: Binding<Value>, instance: Value, metadataReader: MetadataReader): void {
-    const tokenDisplayName = tokenName(binding.token);
-    const tokenKey: DependencyKey = binding.token;
-
-    // 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()
-    for (const methodName of lifecycleMethods(binding, metadataReader, "preDestroy")) {
-      if (callHook(instance, methodName) instanceof Promise) {
-        throw new AsyncDeactivationError(tokenDisplayName);
-      }
-    }
-  }
-
-  /** Whether the deferred activation-hook table has had to be built. */
-  get isActivationTableBuilt(): boolean {
-    return this.#activationHooks !== undefined;
-  }
-}
-
-const NO_METHODS: ReadonlyArray<string> = [];
-
-/** The `@postConstruct` / `@preDestroy` methods a binding declares — only a class can declare any. */
-function lifecycleMethods<Value>(
-  binding: Binding<Value>,
-  metadataReader: MetadataReader,
-  phase: "postConstruct" | "preDestroy",
-): ReadonlyArray<string> {
-  if (binding.kind !== "class") {
-    return NO_METHODS;
-  }
-  return metadataReader.getLifecycleMetadata(binding.target)?.[phase] ?? NO_METHODS;
-}
-
-/**
- * Invokes a lifecycle hook by name.
- *
- * @remarks A name that is not a method can only come from a {@link MetadataReader} that answered
- * wrongly, so it is reported rather than skipped — a hook that never runs is the failure a caller
- * cannot see. A non-object instance has no hooks to run and is not an error.
- */
-function callHook(instance: unknown, methodName: string): unknown {
-  if (typeof instance !== "object" || instance === null) {
-    return undefined;
-  }
-  const method: unknown = Reflect.get(instance, methodName);
-  if (typeof method !== "function") {
-    // The class is derived here rather than passed in, so the happy path carries no extra argument.
-    const constructor: unknown = Reflect.get(instance, "constructor");
-    const className = typeof constructor === "function" && constructor.name !== "" ? constructor.name : "(anonymous)";
-    throw new InvalidMetadataError(className, `lifecycle method '${methodName}' is not a method on the instance`);
-  }
-
-  return method.call(instance);
-}