@codefast/di 0.5.0 → 0.6.1

package/src/introspection/dependency-graph.ts

@@ -1,29 +1,45 @@
+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 { 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 type { BindingRegistry } from "#/registry";
-import { effectiveBindingScope } from "#/resolution/binding-scope";
-import { tokenName } from "#/token";
-import type { BindingScope, Constructor } from "#/types";
+import { matchesSlot } from "#/resolution/select/binding-select";
 
-// ── Types ─────────────────────────────────────────────────────────────────────
+// ── 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;
-  readonly kind: string;
-  readonly scope: BindingScope;
+  /** 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;
 }
 
 /**
@@ -39,10 +55,204 @@ export interface ContainerGraphJson {
  * @since 0.3.16-canary.0
  */
 export interface GraphOptions {
-  readonly includeParent?: boolean;
+  readonly includeParent?: boolean | undefined;
 }
 
-// ── Builder ───────────────────────────────────────────────────────────────────
+// ── 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));
+}
+
+function edgeLabel(ref: DependencySlot, index: number): string {
+  const criterion =
+    ref.name !== undefined
+      ? `name:${ref.name}`
+      : ref.tags !== undefined && ref.tags.length > 0
+        ? `tag:${ref.tags[0]?.key.name}=${String(ref.tags[0]?.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;
+    }
+
+    accumulator.edges.push({
+      from,
+      to: unboundNodeIdFor(accumulator, ref.token),
+      label,
+      optional: true,
+      ...(ref.name !== undefined ? { slotName: ref.name } : {}),
+    });
+
+    return;
+  }
+
+  for (const target of targets) {
+    // A multi dep with no criterion of its own fans out — each edge names the slot it hits.
+    const slotName = target.slot.name ?? ref.name;
+    const perTargetLabel =
+      ref.multi && ref.name === undefined && slotName !== undefined
+        ? edgeLabel({ ...ref, name: slotName }, index)
+        : label;
+
+    accumulator.edges.push({
+      from,
+      to: target.id,
+      label: perTargetLabel,
+      optional: ref.optional,
+      ...(slotName !== undefined ? { slotName } : {}),
+    });
+  }
+}
+
+/** 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);
+  }
+}
 
 /**
  * @since 0.3.16-canary.0
@@ -53,64 +263,14 @@ export function buildDependencyGraph(
   options: GraphOptions | undefined,
   parentRegistry?: BindingRegistry,
 ): ContainerGraphJson {
-  const nodes: Array<GraphNode> = [];
-  const edges: Array<GraphEdge> = [];
+  const accumulator: GraphAccumulator = { nodes: [], edges: [], unboundNodeIds: new Map() };
   const includesParent = options?.includeParent === true;
 
-  const addBindings = (sourceRegistry: BindingRegistry, fromParent: boolean): void => {
-    for (const binding of sourceRegistry.allBindings()) {
-      const scope = effectiveBindingScope(binding);
-      nodes.push({
-        id: binding.id,
-        tokenName: tokenName(binding.token),
-        kind: binding.kind,
-        scope,
-        fromParent,
-      });
-
-      // Build edges
-      if (binding.kind === "class") {
-        const meta = metadataReader.getConstructorMetadata(binding.target as Constructor);
-        if (meta !== undefined) {
-          for (let index = 0; index < meta.params.length; index += 1) {
-            const param = meta.params[index]!;
-            const dependencyBinding = sourceRegistry.getAll(param.token as Constructor)[0];
-            if (dependencyBinding !== undefined) {
-              edges.push({
-                from: binding.id,
-                to: dependencyBinding.id,
-                label: `[${index}]`,
-              });
-            }
-          }
-        }
-      } else if (binding.kind === "resolved" || binding.kind === "resolved-async") {
-        for (let index = 0; index < binding.deps.length; index += 1) {
-          const dependency = binding.deps[index]!;
-          const dependencyBindings = sourceRegistry.getAll(dependency.token as Constructor);
-          if (dependencyBindings.length > 0 && dependencyBindings[0] !== undefined) {
-            const label =
-              dependency.name !== undefined
-                ? `name:${dependency.name}`
-                : dependency.tags !== undefined && dependency.tags.length > 0
-                  ? `tag:${dependency.tags[0]?.[0]}=${String(dependency.tags[0]?.[1])}`
-                  : `[${index}]`;
-            edges.push({ from: binding.id, to: dependencyBindings[0].id, label });
-          }
-        }
-      } else if (binding.kind === "alias") {
-        const targetBindings = sourceRegistry.getAll(binding.target as Constructor);
-        if (targetBindings.length > 0 && targetBindings[0] !== undefined) {
-          edges.push({ from: binding.id, to: targetBindings[0].id, label: "alias" });
-        }
-      }
-    }
-  };
+  addRegistryBindings(accumulator, registry, metadataReader, false, includesParent ? parentRegistry : undefined);
 
-  addBindings(registry, false);
   if (includesParent && parentRegistry !== undefined) {
-    addBindings(parentRegistry, true);
+    addRegistryBindings(accumulator, parentRegistry, metadataReader, true);
   }
 
-  return { nodes, edges, includesParent };
+  return { nodes: accumulator.nodes, edges: accumulator.edges, includesParent };
 }

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

@@ -1,4 +1,4 @@
-import type { ContainerGraphJson } from "#/introspection/dependency-graph";
+import type { ContainerGraphJson, GraphNode } from "#/introspection/dependency-graph";
 
 /**
  * @since 0.3.16-canary.0
@@ -7,8 +7,9 @@ export interface CytoscapeNode {
   readonly data: {
     readonly id: string;
     readonly label: string;
-    readonly kind: string;
-    readonly scope: string;
+    readonly tokenKey: string;
+    readonly kind: GraphNode["kind"];
+    readonly scope: GraphNode["scope"];
     readonly fromParent: boolean;
   };
 }
@@ -22,6 +23,8 @@ export interface CytoscapeEdge {
     readonly source: string;
     readonly target: string;
     readonly label?: string;
+    readonly optional: boolean;
+    readonly slotName?: string;
   };
 }
 
@@ -41,6 +44,7 @@ export function toCytoscapeGraph(graph: ContainerGraphJson): CytoscapeElements {
       data: {
         id: node.id,
         label: node.tokenName,
+        tokenKey: node.tokenKey,
         kind: node.kind,
         scope: node.scope,
         fromParent: node.fromParent,
@@ -56,6 +60,8 @@ export function toCytoscapeGraph(graph: ContainerGraphJson): CytoscapeElements {
         source: edge.from,
         target: edge.to,
         ...(edge.label !== undefined ? { label: edge.label } : {}),
+        optional: edge.optional,
+        ...(edge.slotName !== undefined ? { slotName: edge.slotName } : {}),
       },
     });
   }

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

@@ -1,5 +1,11 @@
 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('"', '\\"');
+}
+
 /**
  * @since 0.3.16-canary.0
  */
@@ -7,14 +13,16 @@ export function toDotGraph(graph: ContainerGraphJson): string {
   const lines: Array<string> = ["digraph DI {", "  rankdir=TB;"];
 
   for (const node of graph.nodes) {
-    const label = `${node.tokenName}\\n[${node.kind}/${node.scope}]`;
-    const style = node.fromParent ? ' style="dashed"' : "";
-    lines.push(`  "${node.id}" [label="${label}"${style}];`);
+    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="${edge.label}"]` : "";
-    lines.push(`  "${edge.from}" -> "${edge.to}"${label};`);
+    const label = edge.label === undefined ? "" : ` [label="${escapeDotString(edge.label)}"]`;
+    lines.push(`  "${escapeDotString(edge.from)}" -> "${escapeDotString(edge.to)}"${label};`);
   }
 
   lines.push("}");

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

@@ -0,0 +1,61 @@
+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,4 +1,4 @@
-import type { ContainerGraphJson } from "#/introspection/dependency-graph";
+import type { ContainerGraphJson, GraphNode } from "#/introspection/dependency-graph";
 
 /**
  * @since 0.3.16-canary.0
@@ -7,8 +7,9 @@ export interface ReactFlowNode {
   readonly id: string;
   readonly data: {
     readonly label: string;
-    readonly kind: string;
-    readonly scope: string;
+    readonly tokenKey: string;
+    readonly kind: GraphNode["kind"];
+    readonly scope: GraphNode["scope"];
     readonly fromParent: boolean;
   };
   readonly position: { readonly x: number; readonly y: number };
@@ -22,6 +23,8 @@ export interface ReactFlowEdge {
   readonly source: string;
   readonly target: string;
   readonly label?: string;
+  readonly optional: boolean;
+  readonly slotName?: string;
 }
 
 /**
@@ -33,9 +36,10 @@ export interface ReactFlowGraph {
 }
 
 /**
+ * Initial grid layout: React Flow expects concrete positions; viewers re-layout anyway.
+ *
  * @since 0.3.16-canary.0
  */
-// Initial grid layout: React Flow expects concrete positions; viewers re-layout anyway.
 const GRID_COLUMN_COUNT = 5;
 const GRID_CELL_WIDTH_PX = 200;
 const GRID_CELL_HEIGHT_PX = 100;
@@ -48,6 +52,7 @@ export function toReactFlowGraph(graph: ContainerGraphJson): ReactFlowGraph {
     id: node.id,
     data: {
       label: node.tokenName,
+      tokenKey: node.tokenKey,
       kind: node.kind,
       scope: node.scope,
       fromParent: node.fromParent,
@@ -63,6 +68,8 @@ export function toReactFlowGraph(graph: ContainerGraphJson): ReactFlowGraph {
     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,10 +1,8 @@
-import type { Binding } from "#/binding";
-import type { BindingRegistry } from "#/registry";
-import { effectiveBindingScope } from "#/resolution/binding-scope";
-import { selectBinding } from "#/resolution/binding-select";
-import type { ScopeManager } from "#/resolution/scope";
-import type { Token } from "#/token";
-import { tokenName } from "#/token";
+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,
@@ -13,9 +11,11 @@ import type {
   ConstraintContext,
   Constructor,
   ResolveOptions,
-} from "#/types";
+} from "#/core/types";
+import type { ScopeManager } from "#/lifecycle/scope-manager";
+import { selectAllBindings } from "#/resolution/select/binding-select";
 
-// ── Public types ──────────────────────────────────────────────────────────────
+// ── Public types ─────────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
  * @since 0.3.16-canary.0
@@ -41,7 +41,7 @@ export interface ContainerSnapshot {
   readonly isDisposed: boolean;
 }
 
-// ── Inspector ─────────────────────────────────────────────────────────────────
+// ── Inspector ────────────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
  * @since 0.3.16-canary.0
@@ -76,8 +76,10 @@ export class Inspector {
   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 (selectBinding(bindings, options, this.#makeConstraintContext(options), tokenName(token)) !== undefined) {
+        if (selectAllBindings(bindings, options, this.#makeConstraintContext(options)).length > 0) {
           return true;
         }
       } else {
@@ -93,7 +95,7 @@ export class Inspector {
       return false;
     }
     if (options !== undefined) {
-      return selectBinding(bindings, options, this.#makeConstraintContext(options), tokenName(token)) !== undefined;
+      return selectAllBindings(bindings, options, this.#makeConstraintContext(options)).length > 0;
     }
     return true;
   }
@@ -109,6 +111,8 @@ export class Inspector {
   }
 
   #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 }