@codefast/di 0.8.0 → 0.8.1

package/src/introspection/dependency-graph.ts

@@ -1,296 +0,0 @@
-import type { Binding } from "#/core/binding";
-import { effectiveBindingScope } from "#/core/binding-scope";
-import type { BindingRegistry } from "#/core/registry";
-import { slotName } from "#/core/tag";
-import type { Token } from "#/core/token";
-import { tokenName } from "#/core/token";
-import type { BindingKind, BindingScope, Constructor } from "#/core/types";
-import type { DependencySlot } from "#/injection/resolve-options";
-import { bindingSlotToResolveOptions } from "#/injection/resolve-options";
-import type { MetadataReader } from "#/metadata/metadata-types";
-import { matchesSlot } from "#/resolution/select/binding-select";
-
-// ── Types ────────────────────────────────────────────────────────────────────────────────────────────────────────────
-
-/**
- * @remarks `kind`/`scope` are `"unbound"` for the placeholder node an optional, currently
- * unsatisfied dependency points at.
- *
- * @since 0.3.16-canary.0
- */
-export interface GraphNode {
-  readonly id: string;
-  readonly tokenName: string;
-  /** Identifies the token itself, so bindings that share a display name stay distinguishable. */
-  readonly tokenKey: string;
-  readonly kind: BindingKind | "unbound";
-  readonly scope: BindingScope | "unbound";
-  readonly fromParent: boolean;
-}
-
-/**
- * @remarks `label` is presentation, assembled for the adapters; read `optional` and `slotName`
- * rather than parsing it.
- *
- * @since 0.3.16-canary.0
- */
-export interface GraphEdge {
-  readonly from: string;
-  readonly to: string;
-  readonly label?: string;
-  readonly optional: boolean;
-  /** The named slot this edge resolves to, when the binding declares one. */
-  readonly slotName?: string;
-}
-
-/**
- * A container's dependency graph as plain JSON — nodes, edges, and whether the parent is included.
- *
- * @since 0.3.16-canary.0
- */
-export interface ContainerGraphJson {
-  readonly nodes: ReadonlyArray<GraphNode>;
-  readonly edges: ReadonlyArray<GraphEdge>;
-  readonly includesParent: boolean;
-}
-
-/**
- * Options controlling what a dependency graph includes.
- *
- * @since 0.3.16-canary.0
- */
-export interface GraphOptions {
-  readonly includeParent?: boolean | undefined;
-}
-
-// ── Builder ──────────────────────────────────────────────────────────────────────────────────────────────────────────
-
-// Tokens are compared by object identity, and a name is free to repeat, so the graph mints its
-// own per-process key. Weakly held: a discarded token takes its key with it.
-const tokenKeys = new WeakMap<object, string>();
-let tokenKeySequence = 0;
-
-function tokenKeyOf(dependency: Token<unknown> | Constructor): string {
-  const existing = tokenKeys.get(dependency);
-
-  if (existing !== undefined) {
-    return existing;
-  }
-
-  tokenKeySequence += 1;
-  const key = `${tokenName(dependency)}@${String(tokenKeySequence)}`;
-
-  tokenKeys.set(dependency, key);
-
-  return key;
-}
-
-// Mirrors filterBindings' slot semantics; predicates need a live resolution context, so the graph
-// keeps every predicate-carrying candidate.
-function matchingTargets(candidates: ReadonlyArray<Binding>, ref: DependencySlot): ReadonlyArray<Binding> {
-  const criterion = bindingSlotToResolveOptions(ref);
-
-  if (ref.multi && criterion === undefined) {
-    return candidates;
-  }
-
-  return candidates.filter((candidate) => matchesSlot(candidate.slot, criterion));
-}
-
-/** The name a dependency asks for, whichever spelling carries it. */
-function refSlotName(ref: DependencySlot): string | undefined {
-  if (ref.name !== undefined) {
-    return ref.name;
-  }
-  const reserved = ref.tags?.find((criterion) => criterion.key === slotName);
-  return reserved === undefined ? undefined : String(reserved.value);
-}
-
-function edgeLabel(ref: DependencySlot, index: number): string {
-  const name = refSlotName(ref);
-  const firstPlainTag = ref.tags?.find((criterion) => criterion.key !== slotName);
-  const criterion =
-    name !== undefined
-      ? `name:${name}`
-      : firstPlainTag !== undefined
-        ? `tag:${firstPlainTag.key.name}=${String(firstPlainTag.value)}`
-        : `[${index}]`;
-
-  return ref.optional ? `${criterion} optional` : criterion;
-}
-
-/** The collections a graph walk fills, so each step of the walk can be a function of its own. */
-interface GraphAccumulator {
-  readonly nodes: Array<GraphNode>;
-  readonly edges: Array<GraphEdge>;
-  // One placeholder node per optional-but-unbound token keeps the declared edge visible.
-  readonly unboundNodeIds: Map<string, string>;
-}
-
-/** Own bindings shadow the fallback, mirroring resolution's upward walk. */
-type BindingLookup = (token: Token<unknown> | Constructor) => ReadonlyArray<Binding>;
-
-function bindingLookup(sourceRegistry: BindingRegistry, fallbackRegistry: BindingRegistry | undefined): BindingLookup {
-  return (token) => {
-    const own = sourceRegistry.getAll(token);
-
-    if (own.length > 0 || fallbackRegistry === undefined) {
-      return own;
-    }
-
-    return fallbackRegistry.getAll(token);
-  };
-}
-
-/** The placeholder node an optional-but-unbound dependency points at, minted once per token. */
-function unboundNodeIdFor(accumulator: GraphAccumulator, dependency: Token<unknown> | Constructor): string {
-  const key = tokenKeyOf(dependency);
-  const existing = accumulator.unboundNodeIds.get(key);
-
-  if (existing !== undefined) {
-    return existing;
-  }
-
-  const id = `unbound:${key}`;
-
-  accumulator.unboundNodeIds.set(key, id);
-  accumulator.nodes.push({
-    id,
-    tokenName: tokenName(dependency),
-    tokenKey: key,
-    kind: "unbound",
-    scope: "unbound",
-    fromParent: false,
-  });
-
-  return id;
-}
-
-function addDependencyEdges(
-  accumulator: GraphAccumulator,
-  from: string,
-  ref: DependencySlot,
-  index: number,
-  lookup: BindingLookup,
-): void {
-  const targets = matchingTargets(lookup(ref.token), ref);
-  const label = edgeLabel(ref, index);
-
-  if (targets.length === 0) {
-    // A required-but-unbound dependency is validate()'s story, not the graph's.
-    if (!ref.optional) {
-      return;
-    }
-
-    const unboundSlotName = refSlotName(ref);
-    accumulator.edges.push({
-      from,
-      to: unboundNodeIdFor(accumulator, ref.token),
-      label,
-      optional: true,
-      ...(unboundSlotName !== undefined ? { slotName: unboundSlotName } : {}),
-    });
-
-    return;
-  }
-
-  const requestedName = refSlotName(ref);
-  for (const target of targets) {
-    // A multi dep with no criterion of its own fans out — each edge names the slot it hits.
-    const edgeSlotName = target.slot.name ?? requestedName;
-    const perTargetLabel =
-      ref.multi && requestedName === undefined && edgeSlotName !== undefined
-        ? edgeLabel({ ...ref, name: edgeSlotName }, index)
-        : label;
-
-    accumulator.edges.push({
-      from,
-      to: target.id,
-      label: perTargetLabel,
-      optional: ref.optional,
-      ...(edgeSlotName !== undefined ? { slotName: edgeSlotName } : {}),
-    });
-  }
-}
-
-/** What one binding declares up front — a class's params, a factory's descriptors, an alias's target. */
-function addBindingEdges(
-  accumulator: GraphAccumulator,
-  binding: Binding,
-  metadataReader: MetadataReader,
-  lookup: BindingLookup,
-): void {
-  if (binding.kind === "class") {
-    const meta = metadataReader.getConstructorMetadata(binding.target);
-
-    if (meta !== undefined) {
-      for (const [index, param] of meta.params.entries()) {
-        addDependencyEdges(accumulator, binding.id, param, index, lookup);
-      }
-    }
-
-    return;
-  }
-
-  if (binding.kind === "resolved" || binding.kind === "resolved-async") {
-    for (const [index, dependency] of binding.deps.entries()) {
-      addDependencyEdges(accumulator, binding.id, dependency, index, lookup);
-    }
-
-    return;
-  }
-
-  if (binding.kind === "alias") {
-    const aliasRef: DependencySlot = { token: binding.target, optional: false, multi: false };
-
-    for (const target of matchingTargets(lookup(binding.target), aliasRef)) {
-      accumulator.edges.push({ from: binding.id, to: target.id, label: "alias", optional: false });
-    }
-  }
-}
-
-function addRegistryBindings(
-  accumulator: GraphAccumulator,
-  sourceRegistry: BindingRegistry,
-  metadataReader: MetadataReader,
-  fromParent: boolean,
-  fallbackRegistry?: BindingRegistry,
-): void {
-  const lookup = bindingLookup(sourceRegistry, fallbackRegistry);
-
-  for (const binding of sourceRegistry.allBindings()) {
-    accumulator.nodes.push({
-      id: binding.id,
-      tokenName: tokenName(binding.token),
-      tokenKey: tokenKeyOf(binding.token),
-      kind: binding.kind,
-      scope: effectiveBindingScope(binding),
-      fromParent,
-    });
-
-    addBindingEdges(accumulator, binding, metadataReader, lookup);
-  }
-}
-
-/**
- * Builds the JSON dependency graph of a registry's bindings, optionally including the parent's.
- *
- * @since 0.3.16-canary.0
- */
-export function buildDependencyGraph(
-  registry: BindingRegistry,
-  metadataReader: MetadataReader,
-  options: GraphOptions | undefined,
-  parentRegistry?: BindingRegistry,
-): ContainerGraphJson {
-  const accumulator: GraphAccumulator = { nodes: [], edges: [], unboundNodeIds: new Map() };
-  const includesParent = options?.includeParent === true;
-
-  addRegistryBindings(accumulator, registry, metadataReader, false, includesParent ? parentRegistry : undefined);
-
-  if (includesParent && parentRegistry !== undefined) {
-    addRegistryBindings(accumulator, parentRegistry, metadataReader, true);
-  }
-
-  return { nodes: accumulator.nodes, edges: accumulator.edges, includesParent };
-}

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,
-    };
-  }
-}