effect 3.18.4 → 3.19.0

package/dist/esm/Graph.js

@@ -9,17 +9,6 @@ import * as Hash from "./Hash.js";
 import { format, NodeInspectSymbol } from "./Inspectable.js";
 import * as Option from "./Option.js";
 import { pipeArguments } from "./Pipeable.js";
-/**
- * Safely get a value from a Map, returning an Option.
- * Uses explicit key presence check with map.has() for better safety.
- * @internal
- */
-const getMapSafe = (map, key) => {
-  if (map.has(key)) {
-    return Option.some(map.get(key));
-  }
-  return Option.none();
-};
 /**
  * Unique identifier for Graph instances.
  *
@@ -104,6 +93,20 @@ const ProtoGraph = {
   }
 };
 // =============================================================================
+// Errors
+// =============================================================================
+/**
+ * Error thrown when a graph operation fails.
+ *
+ * @since 3.18.0
+ * @category errors
+ */
+export class GraphError extends /*#__PURE__*/Data.TaggedError("GraphError") {}
+/** @internal */
+const missingNode = node => new GraphError({
+  message: `Node ${node} does not exist`
+});
+// =============================================================================
 // Constructors
 // =============================================================================
 /** @internal */
@@ -329,7 +332,7 @@ export const addNode = (mutable, data) => {
  * @since 3.18.0
  * @category getters
  */
-export const getNode = (graph, nodeIndex) => getMapSafe(graph.nodes, nodeIndex);
+export const getNode = (graph, nodeIndex) => graph.nodes.has(nodeIndex) ? Option.some(graph.nodes.get(nodeIndex)) : Option.none();
 /**
  * Checks if a node with the given index exists in the graph.
  *
@@ -892,10 +895,10 @@ const invalidateCycleFlagOnAddition = mutable => {
 export const addEdge = (mutable, source, target, data) => {
   // Validate that both nodes exist
   if (!mutable.nodes.has(source)) {
-    throw new Error(`Source node ${source} does not exist`);
+    throw missingNode(source);
   }
   if (!mutable.nodes.has(target)) {
-    throw new Error(`Target node ${target} does not exist`);
+    throw missingNode(target);
   }
   const edgeIndex = mutable.nextEdgeIndex;
   // Create edge data
@@ -906,23 +909,23 @@ export const addEdge = (mutable, source, target, data) => {
   });
   mutable.edges.set(edgeIndex, edgeData);
   // Update adjacency lists
-  const sourceAdjacency = getMapSafe(mutable.adjacency, source);
-  if (Option.isSome(sourceAdjacency)) {
-    sourceAdjacency.value.push(edgeIndex);
+  const sourceAdjacency = mutable.adjacency.get(source);
+  if (sourceAdjacency !== undefined) {
+    sourceAdjacency.push(edgeIndex);
   }
-  const targetReverseAdjacency = getMapSafe(mutable.reverseAdjacency, target);
-  if (Option.isSome(targetReverseAdjacency)) {
-    targetReverseAdjacency.value.push(edgeIndex);
+  const targetReverseAdjacency = mutable.reverseAdjacency.get(target);
+  if (targetReverseAdjacency !== undefined) {
+    targetReverseAdjacency.push(edgeIndex);
   }
   // For undirected graphs, add reverse connections
   if (mutable.type === "undirected") {
-    const targetAdjacency = getMapSafe(mutable.adjacency, target);
-    if (Option.isSome(targetAdjacency)) {
-      targetAdjacency.value.push(edgeIndex);
+    const targetAdjacency = mutable.adjacency.get(target);
+    if (targetAdjacency !== undefined) {
+      targetAdjacency.push(edgeIndex);
     }
-    const sourceReverseAdjacency = getMapSafe(mutable.reverseAdjacency, source);
-    if (Option.isSome(sourceReverseAdjacency)) {
-      sourceReverseAdjacency.value.push(edgeIndex);
+    const sourceReverseAdjacency = mutable.reverseAdjacency.get(source);
+    if (sourceReverseAdjacency !== undefined) {
+      sourceReverseAdjacency.push(edgeIndex);
     }
   }
   // Update allocators
@@ -960,16 +963,16 @@ export const removeNode = (mutable, nodeIndex) => {
   // Collect all incident edges for removal
   const edgesToRemove = [];
   // Get outgoing edges
-  const outgoingEdges = getMapSafe(mutable.adjacency, nodeIndex);
-  if (Option.isSome(outgoingEdges)) {
-    for (const edge of outgoingEdges.value) {
+  const outgoingEdges = mutable.adjacency.get(nodeIndex);
+  if (outgoingEdges !== undefined) {
+    for (const edge of outgoingEdges) {
       edgesToRemove.push(edge);
     }
   }
   // Get incoming edges
-  const incomingEdges = getMapSafe(mutable.reverseAdjacency, nodeIndex);
-  if (Option.isSome(incomingEdges)) {
-    for (const edge of incomingEdges.value) {
+  const incomingEdges = mutable.reverseAdjacency.get(nodeIndex);
+  if (incomingEdges !== undefined) {
+    for (const edge of incomingEdges) {
       edgesToRemove.push(edge);
     }
   }
@@ -1016,43 +1019,43 @@ export const removeEdge = (mutable, edgeIndex) => {
 /** @internal */
 const removeEdgeInternal = (mutable, edgeIndex) => {
   // Get edge data
-  const edge = getMapSafe(mutable.edges, edgeIndex);
-  if (Option.isNone(edge)) {
+  const edge = mutable.edges.get(edgeIndex);
+  if (edge === undefined) {
     return false; // Edge doesn't exist, no mutation occurred
   }
   const {
     source,
     target
-  } = edge.value;
+  } = edge;
   // Remove from adjacency lists
-  const sourceAdjacency = getMapSafe(mutable.adjacency, source);
-  if (Option.isSome(sourceAdjacency)) {
-    const index = sourceAdjacency.value.indexOf(edgeIndex);
+  const sourceAdjacency = mutable.adjacency.get(source);
+  if (sourceAdjacency !== undefined) {
+    const index = sourceAdjacency.indexOf(edgeIndex);
     if (index !== -1) {
-      sourceAdjacency.value.splice(index, 1);
+      sourceAdjacency.splice(index, 1);
     }
   }
-  const targetReverseAdjacency = getMapSafe(mutable.reverseAdjacency, target);
-  if (Option.isSome(targetReverseAdjacency)) {
-    const index = targetReverseAdjacency.value.indexOf(edgeIndex);
+  const targetReverseAdjacency = mutable.reverseAdjacency.get(target);
+  if (targetReverseAdjacency !== undefined) {
+    const index = targetReverseAdjacency.indexOf(edgeIndex);
     if (index !== -1) {
-      targetReverseAdjacency.value.splice(index, 1);
+      targetReverseAdjacency.splice(index, 1);
     }
   }
   // For undirected graphs, remove reverse connections
   if (mutable.type === "undirected") {
-    const targetAdjacency = getMapSafe(mutable.adjacency, target);
-    if (Option.isSome(targetAdjacency)) {
-      const index = targetAdjacency.value.indexOf(edgeIndex);
+    const targetAdjacency = mutable.adjacency.get(target);
+    if (targetAdjacency !== undefined) {
+      const index = targetAdjacency.indexOf(edgeIndex);
       if (index !== -1) {
-        targetAdjacency.value.splice(index, 1);
+        targetAdjacency.splice(index, 1);
       }
     }
-    const sourceReverseAdjacency = getMapSafe(mutable.reverseAdjacency, source);
-    if (Option.isSome(sourceReverseAdjacency)) {
-      const index = sourceReverseAdjacency.value.indexOf(edgeIndex);
+    const sourceReverseAdjacency = mutable.reverseAdjacency.get(source);
+    if (sourceReverseAdjacency !== undefined) {
+      const index = sourceReverseAdjacency.indexOf(edgeIndex);
       if (index !== -1) {
-        sourceReverseAdjacency.value.splice(index, 1);
+        sourceReverseAdjacency.splice(index, 1);
       }
     }
   }
@@ -1089,7 +1092,7 @@ const removeEdgeInternal = (mutable, edgeIndex) => {
  * @since 3.18.0
  * @category getters
  */
-export const getEdge = (graph, edgeIndex) => getMapSafe(graph.edges, edgeIndex);
+export const getEdge = (graph, edgeIndex) => graph.edges.has(edgeIndex) ? Option.some(graph.edges.get(edgeIndex)) : Option.none();
 /**
  * Checks if an edge exists between two nodes in the graph.
  *
@@ -1119,14 +1122,14 @@ export const getEdge = (graph, edgeIndex) => getMapSafe(graph.edges, edgeIndex);
  * @category getters
  */
 export const hasEdge = (graph, source, target) => {
-  const adjacencyList = getMapSafe(graph.adjacency, source);
-  if (Option.isNone(adjacencyList)) {
+  const adjacencyList = graph.adjacency.get(source);
+  if (adjacencyList === undefined) {
     return false;
   }
   // Check if any edge in the adjacency list connects to the target
-  for (const edgeIndex of adjacencyList.value) {
-    const edge = getMapSafe(graph.edges, edgeIndex);
-    if (Option.isSome(edge) && edge.value.target === target) {
+  for (const edgeIndex of adjacencyList) {
+    const edge = graph.edges.get(edgeIndex);
+    if (edge !== undefined && edge.target === target) {
       return true;
     }
   }
@@ -1188,15 +1191,19 @@ export const edgeCount = graph => graph.edges.size;
  * @category getters
  */
 export const neighbors = (graph, nodeIndex) => {
-  const adjacencyList = getMapSafe(graph.adjacency, nodeIndex);
-  if (Option.isNone(adjacencyList)) {
+  // For undirected graphs, use the specialized helper that returns the other endpoint
+  if (graph.type === "undirected") {
+    return getUndirectedNeighbors(graph, nodeIndex);
+  }
+  const adjacencyList = graph.adjacency.get(nodeIndex);
+  if (adjacencyList === undefined) {
     return [];
   }
   const result = [];
-  for (const edgeIndex of adjacencyList.value) {
-    const edge = getMapSafe(graph.edges, edgeIndex);
-    if (Option.isSome(edge)) {
-      result.push(edge.value.target);
+  for (const edgeIndex of adjacencyList) {
+    const edge = graph.edges.get(edgeIndex);
+    if (edge !== undefined) {
+      result.push(edge.target);
     }
   }
   return result;
@@ -1229,24 +1236,21 @@ export const neighbors = (graph, nodeIndex) => {
  */
 export const neighborsDirected = (graph, nodeIndex, direction) => {
   const adjacencyMap = direction === "incoming" ? graph.reverseAdjacency : graph.adjacency;
-  const adjacencyList = getMapSafe(adjacencyMap, nodeIndex);
-  if (Option.isNone(adjacencyList)) {
+  const adjacencyList = adjacencyMap.get(nodeIndex);
+  if (adjacencyList === undefined) {
     return [];
   }
   const result = [];
-  for (const edgeIndex of adjacencyList.value) {
-    const edge = getMapSafe(graph.edges, edgeIndex);
-    if (Option.isSome(edge)) {
+  for (const edgeIndex of adjacencyList) {
+    const edge = graph.edges.get(edgeIndex);
+    if (edge !== undefined) {
       // For incoming direction, we want the source node instead of target
-      const neighborNode = direction === "incoming" ? edge.value.source : edge.value.target;
+      const neighborNode = direction === "incoming" ? edge.source : edge.target;
       result.push(neighborNode);
     }
   }
   return result;
 };
-// =============================================================================
-// GraphViz Export
-// =============================================================================
 /**
  * Exports a graph to GraphViz DOT format for visualization.
  *
@@ -1302,6 +1306,97 @@ export const toGraphViz = (graph, options) => {
   lines.push("}");
   return lines.join("\n");
 };
+/** @internal */
+const escapeMermaidLabel = label => {
+  // Escape special characters for Mermaid using HTML entity codes
+  // According to: https://mermaid.js.org/syntax/flowchart.html#special-characters-that-break-syntax
+  return label.replace(/#/g, "#35;").replace(/"/g, "#quot;").replace(/</g, "#lt;").replace(/>/g, "#gt;").replace(/&/g, "#amp;").replace(/\[/g, "#91;").replace(/\]/g, "#93;").replace(/\{/g, "#123;").replace(/\}/g, "#125;").replace(/\(/g, "#40;").replace(/\)/g, "#41;").replace(/\|/g, "#124;").replace(/\\/g, "#92;").replace(/\n/g, "<br/>");
+};
+/** @internal */
+const formatMermaidNode = (nodeId, label, shape) => {
+  switch (shape) {
+    case "rectangle":
+      return `${nodeId}["${label}"]`;
+    case "rounded":
+      return `${nodeId}("${label}")`;
+    case "circle":
+      return `${nodeId}(("${label}"))`;
+    case "diamond":
+      return `${nodeId}{"${label}"}`;
+    case "hexagon":
+      return `${nodeId}{{"${label}"}}`;
+    case "stadium":
+      return `${nodeId}(["${label}"])`;
+    case "subroutine":
+      return `${nodeId}[["${label}"]]`;
+    case "cylindrical":
+      return `${nodeId}[("${label}")]`;
+  }
+};
+/**
+ * Exports a graph to Mermaid diagram format for visualization.
+ *
+ * @example
+ * ```ts
+ * import { Graph } from "effect"
+ *
+ * const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
+ *   const app = Graph.addNode(mutable, "App")
+ *   const db = Graph.addNode(mutable, "Database")
+ *   const cache = Graph.addNode(mutable, "Cache")
+ *   Graph.addEdge(mutable, app, db, 1)
+ *   Graph.addEdge(mutable, app, cache, 2)
+ * })
+ *
+ * const mermaid = Graph.toMermaid(graph)
+ * console.log(mermaid)
+ * // flowchart TD
+ * //   0["App"]
+ * //   1["Database"]
+ * //   2["Cache"]
+ * //   0 -->|"1"| 1
+ * //   0 -->|"2"| 2
+ * ```
+ *
+ * @since 3.18.0
+ * @category utils
+ */
+export const toMermaid = (graph, options) => {
+  // Extract and validate options with defaults
+  const {
+    diagramType,
+    direction = "TD",
+    edgeLabel = data => String(data),
+    nodeLabel = data => String(data),
+    nodeShape = () => "rectangle"
+  } = options ?? {};
+  // Auto-detect diagram type if not specified
+  const finalDiagramType = diagramType ?? (graph.type === "directed" ? "flowchart" : "graph");
+  // Generate diagram header
+  const lines = [];
+  lines.push(`${finalDiagramType} ${direction}`);
+  // Add nodes
+  for (const [nodeIndex, nodeData] of graph.nodes) {
+    const nodeId = String(nodeIndex);
+    const label = escapeMermaidLabel(nodeLabel(nodeData));
+    const shape = nodeShape(nodeData);
+    const formattedNode = formatMermaidNode(nodeId, label, shape);
+    lines.push(`  ${formattedNode}`);
+  }
+  // Add edges
+  const edgeOperator = finalDiagramType === "flowchart" ? "-->" : "---";
+  for (const [, edgeData] of graph.edges) {
+    const sourceId = String(edgeData.source);
+    const targetId = String(edgeData.target);
+    const label = escapeMermaidLabel(edgeLabel(edgeData.data));
+    if (label) {
+      lines.push(`  ${sourceId} ${edgeOperator}|"${label}"| ${targetId}`);
+    } else {
+      lines.push(`  ${sourceId} ${edgeOperator} ${targetId}`);
+    }
+  }
+  return lines.join("\n");
+};
 // =============================================================================
 // =============================================================================
 // Graph Structure Analysis Algorithms (Phase 5A)
@@ -1483,13 +1578,13 @@ export const isBipartite = graph => {
 const getUndirectedNeighbors = (graph, nodeIndex) => {
   const neighbors = new Set();
   // Check edges where this node is the source
-  const adjacencyList = getMapSafe(graph.adjacency, nodeIndex);
-  if (Option.isSome(adjacencyList)) {
-    for (const edgeIndex of adjacencyList.value) {
-      const edge = getMapSafe(graph.edges, edgeIndex);
-      if (Option.isSome(edge)) {
+  const adjacencyList = graph.adjacency.get(nodeIndex);
+  if (adjacencyList !== undefined) {
+    for (const edgeIndex of adjacencyList) {
+      const edge = graph.edges.get(edgeIndex);
+      if (edge !== undefined) {
         // For undirected graphs, the neighbor is the other endpoint
-        const otherNode = edge.value.source === nodeIndex ? edge.value.target : edge.value.source;
+        const otherNode = edge.source === nodeIndex ? edge.target : edge.source;
         neighbors.add(otherNode);
       }
     }
@@ -1623,12 +1718,12 @@ export const stronglyConnectedComponents = graph => {
       visited.add(node);
       scc.push(node);
       // Use reverse adjacency (transpose graph)
-      const reverseAdjacency = getMapSafe(graph.reverseAdjacency, node);
-      if (Option.isSome(reverseAdjacency)) {
-        for (const edgeIndex of reverseAdjacency.value) {
-          const edge = getMapSafe(graph.edges, edgeIndex);
-          if (Option.isSome(edge)) {
-            const predecessor = edge.value.source;
+      const reverseAdjacency = graph.reverseAdjacency.get(node);
+      if (reverseAdjacency !== undefined) {
+        for (const edgeIndex of reverseAdjacency) {
+          const edge = graph.edges.get(edgeIndex);
+          if (edge !== undefined) {
+            const predecessor = edge.source;
             if (!visited.has(predecessor)) {
               stack.push(predecessor);
             }
@@ -1659,7 +1754,7 @@ export const stronglyConnectedComponents = graph => {
  *   Graph.addEdge(mutable, b, c, 2)
  * })
  *
- * const result = Graph.dijkstra(graph, 0, 2, (edgeData) => edgeData)
+ * const result = Graph.dijkstra(graph, { source: 0, target: 2, cost: (edgeData) => edgeData })
  * if (Option.isSome(result)) {
  *   console.log(result.value.path) // [0, 1, 2] - shortest path A->B->C
  *   console.log(result.value.distance) // 7 - total distance
@@ -1669,20 +1764,25 @@ export const stronglyConnectedComponents = graph => {
  * @since 3.18.0
  * @category algorithms
  */
-export const dijkstra = (graph, source, target, edgeWeight) => {
+export const dijkstra = (graph, config) => {
+  const {
+    cost,
+    source,
+    target
+  } = config;
   // Validate that source and target nodes exist
   if (!graph.nodes.has(source)) {
-    throw new Error(`Source node ${source} does not exist`);
+    throw missingNode(source);
   }
   if (!graph.nodes.has(target)) {
-    throw new Error(`Target node ${target} does not exist`);
+    throw missingNode(target);
   }
   // Early return if source equals target
   if (source === target) {
     return Option.some({
       path: [source],
       distance: 0,
-      edgeWeights: []
+      costs: []
     });
   }
   // Distance tracking and priority queue simulation
@@ -1722,13 +1822,13 @@ export const dijkstra = (graph, source, target, edgeWeight) => {
     // Get current distance
     const currentDistance = distances.get(currentNode);
     // Examine all outgoing edges
-    const adjacencyList = getMapSafe(graph.adjacency, currentNode);
-    if (Option.isSome(adjacencyList)) {
-      for (const edgeIndex of adjacencyList.value) {
-        const edge = getMapSafe(graph.edges, edgeIndex);
-        if (Option.isSome(edge)) {
-          const neighbor = edge.value.target;
-          const weight = edgeWeight(edge.value.data);
+    const adjacencyList = graph.adjacency.get(currentNode);
+    if (adjacencyList !== undefined) {
+      for (const edgeIndex of adjacencyList) {
+        const edge = graph.edges.get(edgeIndex);
+        if (edge !== undefined) {
+          const neighbor = edge.target;
+          const weight = cost(edge.data);
           // Validate non-negative weights
           if (weight < 0) {
             throw new Error(`Dijkstra's algorithm requires non-negative edge weights, found ${weight}`);
@@ -1740,7 +1840,7 @@ export const dijkstra = (graph, source, target, edgeWeight) => {
             distances.set(neighbor, newDistance);
             previous.set(neighbor, {
               node: currentNode,
-              edgeData: edge.value.data
+              edgeData: edge.data
             });
             // Add to priority queue if not visited
             if (!visited.has(neighbor)) {
@@ -1761,13 +1861,13 @@ export const dijkstra = (graph, source, target, edgeWeight) => {
   }
   // Reconstruct path
   const path = [];
-  const edgeWeights = [];
+  const costs = [];
   let currentNode = target;
   while (currentNode !== null) {
     path.unshift(currentNode);
     const prev = previous.get(currentNode);
     if (prev !== null) {
-      edgeWeights.unshift(prev.edgeData);
+      costs.unshift(prev.edgeData);
       currentNode = prev.node;
     } else {
       currentNode = null;
@@ -1776,7 +1876,7 @@ export const dijkstra = (graph, source, target, edgeWeight) => {
   return Option.some({
     path,
     distance: targetDistance,
-    edgeWeights
+    costs
   });
 };
 /**
@@ -1806,7 +1906,7 @@ export const dijkstra = (graph, source, target, edgeWeight) => {
  * @since 3.18.0
  * @category algorithms
  */
-export const floydWarshall = (graph, edgeWeight) => {
+export const floydWarshall = (graph, cost) => {
   // Get all nodes for Floyd-Warshall algorithm (needs array for nested iteration)
   const allNodes = Array.from(graph.nodes.keys());
   // Initialize distance matrix
@@ -1826,7 +1926,7 @@ export const floydWarshall = (graph, edgeWeight) => {
   }
   // Set edge weights
   for (const [, edgeData] of graph.edges) {
-    const weight = edgeWeight(edgeData.data);
+    const weight = cost(edgeData.data);
     const i = edgeData.source;
     const j = edgeData.target;
     // Use minimum weight if multiple edges exist
@@ -1859,17 +1959,17 @@ export const floydWarshall = (graph, edgeWeight) => {
   }
   // Build result paths and edge weights
   const paths = new Map();
-  const resultEdgeWeights = new Map();
+  const resultCosts = new Map();
   for (const i of allNodes) {
     paths.set(i, new Map());
-    resultEdgeWeights.set(i, new Map());
+    resultCosts.set(i, new Map());
     for (const j of allNodes) {
       if (i === j) {
         paths.get(i).set(j, [i]);
-        resultEdgeWeights.get(i).set(j, []);
+        resultCosts.get(i).set(j, []);
       } else if (dist.get(i).get(j) === Infinity) {
         paths.get(i).set(j, null);
-        resultEdgeWeights.get(i).set(j, []);
+        resultCosts.get(i).set(j, []);
       } else {
         // Reconstruct path iteratively
         const path = [];
@@ -1887,14 +1987,14 @@ export const floydWarshall = (graph, edgeWeight) => {
           path.push(current);
         }
         paths.get(i).set(j, path);
-        resultEdgeWeights.get(i).set(j, weights);
+        resultCosts.get(i).set(j, weights);
       }
     }
   }
   return {
     distances: dist,
     paths,
-    edgeWeights: resultEdgeWeights
+    costs: resultCosts
   };
 };
 /**
@@ -1920,7 +2020,7 @@ export const floydWarshall = (graph, edgeWeight) => {
  * const heuristic = (nodeData: {x: number, y: number}, targetData: {x: number, y: number}) =>
  *   Math.abs(nodeData.x - targetData.x) + Math.abs(nodeData.y - targetData.y)
  *
- * const result = Graph.astar(graph, 0, 2, (edgeData) => edgeData, heuristic)
+ * const result = Graph.astar(graph, { source: 0, target: 2, cost: (edgeData) => edgeData, heuristic })
  * if (Option.isSome(result)) {
  *   console.log(result.value.path) // [0, 1, 2] - shortest path
  *   console.log(result.value.distance) // 2 - total distance
@@ -1930,25 +2030,31 @@ export const floydWarshall = (graph, edgeWeight) => {
  * @since 3.18.0
  * @category algorithms
  */
-export const astar = (graph, source, target, edgeWeight, heuristic) => {
+export const astar = (graph, config) => {
+  const {
+    cost,
+    heuristic,
+    source,
+    target
+  } = config;
   // Validate that source and target nodes exist
   if (!graph.nodes.has(source)) {
-    throw new Error(`Source node ${source} does not exist`);
+    throw missingNode(source);
   }
   if (!graph.nodes.has(target)) {
-    throw new Error(`Target node ${target} does not exist`);
+    throw missingNode(target);
   }
   // Early return if source equals target
   if (source === target) {
     return Option.some({
       path: [source],
       distance: 0,
-      edgeWeights: []
+      costs: []
     });
   }
   // Get target node data for heuristic calculations
-  const targetNodeData = getMapSafe(graph.nodes, target);
-  if (Option.isNone(targetNodeData)) {
+  const targetNodeData = graph.nodes.get(target);
+  if (targetNodeData === undefined) {
     throw new Error(`Target node ${target} data not found`);
   }
   // Distance tracking (g-score) and f-score (g + h)
@@ -1964,9 +2070,9 @@ export const astar = (graph, source, target, edgeWeight, heuristic) => {
     previous.set(node, null);
   }
   // Calculate initial f-score for source
-  const sourceNodeData = getMapSafe(graph.nodes, source);
-  if (Option.isSome(sourceNodeData)) {
-    const h = heuristic(sourceNodeData.value, targetNodeData.value);
+  const sourceNodeData = graph.nodes.get(source);
+  if (sourceNodeData !== undefined) {
+    const h = heuristic(sourceNodeData, targetNodeData);
     fScore.set(source, h);
   }
   // Priority queue using f-score (total estimated cost)
@@ -1996,13 +2102,13 @@ export const astar = (graph, source, target, edgeWeight, heuristic) => {
     // Get current g-score
     const currentGScore = gScore.get(currentNode);
     // Examine all outgoing edges
-    const adjacencyList = getMapSafe(graph.adjacency, currentNode);
-    if (Option.isSome(adjacencyList)) {
-      for (const edgeIndex of adjacencyList.value) {
-        const edge = getMapSafe(graph.edges, edgeIndex);
-        if (Option.isSome(edge)) {
-          const neighbor = edge.value.target;
-          const weight = edgeWeight(edge.value.data);
+    const adjacencyList = graph.adjacency.get(currentNode);
+    if (adjacencyList !== undefined) {
+      for (const edgeIndex of adjacencyList) {
+        const edge = graph.edges.get(edgeIndex);
+        if (edge !== undefined) {
+          const neighbor = edge.target;
+          const weight = cost(edge.data);
           // Validate non-negative weights
           if (weight < 0) {
             throw new Error(`A* algorithm requires non-negative edge weights, found ${weight}`);
@@ -2015,12 +2121,12 @@ export const astar = (graph, source, target, edgeWeight, heuristic) => {
             gScore.set(neighbor, tentativeGScore);
             previous.set(neighbor, {
               node: currentNode,
-              edgeData: edge.value.data
+              edgeData: edge.data
             });
             // Calculate f-score using heuristic
-            const neighborNodeData = getMapSafe(graph.nodes, neighbor);
-            if (Option.isSome(neighborNodeData)) {
-              const h = heuristic(neighborNodeData.value, targetNodeData.value);
+            const neighborNodeData = graph.nodes.get(neighbor);
+            if (neighborNodeData !== undefined) {
+              const h = heuristic(neighborNodeData, targetNodeData);
               const f = tentativeGScore + h;
               fScore.set(neighbor, f);
               // Add to open set if not visited
@@ -2043,13 +2149,13 @@ export const astar = (graph, source, target, edgeWeight, heuristic) => {
   }
   // Reconstruct path
   const path = [];
-  const edgeWeights = [];
+  const costs = [];
   let currentNode = target;
   while (currentNode !== null) {
     path.unshift(currentNode);
     const prev = previous.get(currentNode);
     if (prev !== null) {
-      edgeWeights.unshift(prev.edgeData);
+      costs.unshift(prev.edgeData);
       currentNode = prev.node;
     } else {
       currentNode = null;
@@ -2058,7 +2164,7 @@ export const astar = (graph, source, target, edgeWeight, heuristic) => {
   return Option.some({
     path,
     distance: targetGScore,
-    edgeWeights
+    costs
   });
 };
 /**
@@ -2081,7 +2187,7 @@ export const astar = (graph, source, target, edgeWeight, heuristic) => {
  *   Graph.addEdge(mutable, a, c, 5)
  * })
  *
- * const result = Graph.bellmanFord(graph, 0, 2, (edgeData) => edgeData)
+ * const result = Graph.bellmanFord(graph, { source: 0, target: 2, cost: (edgeData) => edgeData })
  * if (Option.isSome(result)) {
  *   console.log(result.value.path) // [0, 1, 2] - shortest path A->B->C
  *   console.log(result.value.distance) // 2 - total distance
@@ -2091,20 +2197,25 @@ export const astar = (graph, source, target, edgeWeight, heuristic) => {
  * @since 3.18.0
  * @category algorithms
  */
-export const bellmanFord = (graph, source, target, edgeWeight) => {
+export const bellmanFord = (graph, config) => {
+  const {
+    cost,
+    source,
+    target
+  } = config;
   // Validate that source and target nodes exist
   if (!graph.nodes.has(source)) {
-    throw new Error(`Source node ${source} does not exist`);
+    throw missingNode(source);
   }
   if (!graph.nodes.has(target)) {
-    throw new Error(`Target node ${target} does not exist`);
+    throw missingNode(target);
   }
   // Early return if source equals target
   if (source === target) {
     return Option.some({
       path: [source],
       distance: 0,
-      edgeWeights: []
+      costs: []
     });
   }
   // Initialize distances and predecessors
@@ -2118,7 +2229,7 @@ export const bellmanFord = (graph, source, target, edgeWeight) => {
   // Collect all edges for relaxation
   const edges = [];
   for (const [, edgeData] of graph.edges) {
-    const weight = edgeWeight(edgeData.data);
+    const weight = cost(edgeData.data);
     edges.push({
       source: edgeData.source,
       target: edgeData.target,
@@ -2161,12 +2272,12 @@ export const bellmanFord = (graph, source, target, edgeWeight) => {
         if (affectedNodes.has(node)) continue;
         affectedNodes.add(node);
         // Add all nodes reachable from this node
-        const adjacencyList = getMapSafe(graph.adjacency, node);
-        if (Option.isSome(adjacencyList)) {
-          for (const edgeIndex of adjacencyList.value) {
-            const edge = getMapSafe(graph.edges, edgeIndex);
-            if (Option.isSome(edge)) {
-              queue.push(edge.value.target);
+        const adjacencyList = graph.adjacency.get(node);
+        if (adjacencyList !== undefined) {
+          for (const edgeIndex of adjacencyList) {
+            const edge = graph.edges.get(edgeIndex);
+            if (edge !== undefined) {
+              queue.push(edge.target);
             }
           }
         }
@@ -2184,13 +2295,13 @@ export const bellmanFord = (graph, source, target, edgeWeight) => {
   }
   // Reconstruct path
   const path = [];
-  const edgeWeights = [];
+  const costs = [];
   let currentNode = target;
   while (currentNode !== null) {
     path.unshift(currentNode);
     const prev = previous.get(currentNode);
     if (prev !== null) {
-      edgeWeights.unshift(prev.edgeData);
+      costs.unshift(prev.edgeData);
       currentNode = prev.node;
     } else {
       currentNode = null;
@@ -2199,7 +2310,7 @@ export const bellmanFord = (graph, source, target, edgeWeight) => {
   return Option.some({
     path,
     distance: targetDistance,
-    edgeWeights
+    costs
   });
 };
 /**
@@ -2220,7 +2331,7 @@ export const bellmanFord = (graph, source, target, edgeWeight) => {
  * })
  *
  * // Both traversal and element iterators return NodeWalker
- * const dfsNodes: Graph.NodeWalker<string> = Graph.dfs(graph, { startNodes: [0] })
+ * const dfsNodes: Graph.NodeWalker<string> = Graph.dfs(graph, { start: [0] })
  * const allNodes: Graph.NodeWalker<string> = Graph.nodes(graph)
  *
  * // Common interface for working with node iterables
@@ -2256,7 +2367,7 @@ export class Walker {
    *   Graph.addEdge(mutable, a, b, 1)
    * })
    *
-   * const dfs = Graph.dfs(graph, { startNodes: [0] })
+   * const dfs = Graph.dfs(graph, { start: [0] })
    *
    * // Map to just the node data
    * const values = Array.from(dfs.visit((index, data) => data))
@@ -2289,7 +2400,7 @@ export class Walker {
    *   Graph.addEdge(mutable, a, b, 1)
    * })
    *
-   * const dfs = Graph.dfs(graph, { startNodes: [0] })
+   * const dfs = Graph.dfs(graph, { start: [0] })
    *
    * // Map to just the node data
    * const values = Array.from(dfs.visit((index, data) => data))
@@ -2321,7 +2432,7 @@ export class Walker {
  *   Graph.addEdge(mutable, a, b, 1)
  * })
  *
- * const dfs = Graph.dfs(graph, { startNodes: [0] })
+ * const dfs = Graph.dfs(graph, { start: [0] })
  * const indices = Array.from(Graph.indices(dfs))
  * console.log(indices) // [0, 1]
  * ```
@@ -2343,7 +2454,7 @@ export const indices = walker => walker.visit((index, _) => index);
  *   Graph.addEdge(mutable, a, b, 1)
  * })
  *
- * const dfs = Graph.dfs(graph, { startNodes: [0] })
+ * const dfs = Graph.dfs(graph, { start: [0] })
  * const values = Array.from(Graph.values(dfs))
  * console.log(values) // ["A", "B"]
  * ```
@@ -2365,7 +2476,7 @@ export const values = walker => walker.visit((_, data) => data);
  *   Graph.addEdge(mutable, a, b, 1)
  * })
  *
- * const dfs = Graph.dfs(graph, { startNodes: [0] })
+ * const dfs = Graph.dfs(graph, { start: [0] })
  * const entries = Array.from(Graph.entries(dfs))
  * console.log(entries) // [[0, "A"], [1, "B"]]
  * ```
@@ -2393,7 +2504,7 @@ export const entries = walker => walker.visit((index, data) => [index, data]);
  * })
  *
  * // Start from a specific node
- * const dfs1 = Graph.dfs(graph, { startNodes: [0] })
+ * const dfs1 = Graph.dfs(graph, { start: [0] })
  * for (const nodeIndex of Graph.indices(dfs1)) {
  *   console.log(nodeIndex) // Traverses in DFS order: 0, 1, 2
  * }
@@ -2407,17 +2518,17 @@ export const entries = walker => walker.visit((index, data) => [index, data]);
  * @category iterators
  */
 export const dfs = (graph, config = {}) => {
-  const startNodes = config.startNodes ?? [];
+  const start = config.start ?? [];
   const direction = config.direction ?? "outgoing";
   // Validate that all start nodes exist
-  for (const nodeIndex of startNodes) {
+  for (const nodeIndex of start) {
     if (!hasNode(graph, nodeIndex)) {
-      throw new Error(`Start node ${nodeIndex} does not exist`);
+      throw missingNode(nodeIndex);
     }
   }
   return new Walker(f => ({
     [Symbol.iterator]: () => {
-      const stack = [...startNodes];
+      const stack = [...start];
       const discovered = new Set();
       const nextMapped = () => {
         while (stack.length > 0) {
@@ -2426,8 +2537,8 @@ export const dfs = (graph, config = {}) => {
             continue;
           }
           discovered.add(current);
-          const nodeDataOption = getMapSafe(graph.nodes, current);
-          if (Option.isNone(nodeDataOption)) {
+          const nodeDataOption = graph.nodes.get(current);
+          if (nodeDataOption === undefined) {
             continue;
           }
           const neighbors = neighborsDirected(graph, current, direction);
@@ -2439,7 +2550,7 @@ export const dfs = (graph, config = {}) => {
           }
           return {
             done: false,
-            value: f(current, nodeDataOption.value)
+            value: f(current, nodeDataOption)
           };
         }
         return {
@@ -2472,7 +2583,7 @@ export const dfs = (graph, config = {}) => {
  * })
  *
  * // Start from a specific node
- * const bfs1 = Graph.bfs(graph, { startNodes: [0] })
+ * const bfs1 = Graph.bfs(graph, { start: [0] })
  * for (const nodeIndex of Graph.indices(bfs1)) {
  *   console.log(nodeIndex) // Traverses in BFS order: 0, 1, 2
  * }
@@ -2486,17 +2597,17 @@ export const dfs = (graph, config = {}) => {
  * @category iterators
  */
 export const bfs = (graph, config = {}) => {
-  const startNodes = config.startNodes ?? [];
+  const start = config.start ?? [];
   const direction = config.direction ?? "outgoing";
   // Validate that all start nodes exist
-  for (const nodeIndex of startNodes) {
+  for (const nodeIndex of start) {
     if (!hasNode(graph, nodeIndex)) {
-      throw new Error(`Start node ${nodeIndex} does not exist`);
+      throw missingNode(nodeIndex);
     }
   }
   return new Walker(f => ({
     [Symbol.iterator]: () => {
-      const queue = [...startNodes];
+      const queue = [...start];
       const discovered = new Set();
       const nextMapped = () => {
         while (queue.length > 0) {
@@ -2584,7 +2695,7 @@ export const topo = (graph, config = {}) => {
   // Validate that all initial nodes exist
   for (const nodeIndex of initials) {
     if (!hasNode(graph, nodeIndex)) {
-      throw new Error(`Initial node ${nodeIndex} does not exist`);
+      throw missingNode(nodeIndex);
     }
   }
   return new Walker(f => ({
@@ -2669,7 +2780,7 @@ export const topo = (graph, config = {}) => {
  * })
  *
  * // Postorder: children before parents
- * const postOrder = Graph.dfsPostOrder(graph, { startNodes: [0] })
+ * const postOrder = Graph.dfsPostOrder(graph, { start: [0] })
  * for (const node of postOrder) {
  *   console.log(node) // 1, 2, 0
  * }
@@ -2679,12 +2790,12 @@ export const topo = (graph, config = {}) => {
  * @category iterators
  */
 export const dfsPostOrder = (graph, config = {}) => {
-  const startNodes = config.startNodes ?? [];
+  const start = config.start ?? [];
   const direction = config.direction ?? "outgoing";
   // Validate that all start nodes exist
-  for (const nodeIndex of startNodes) {
+  for (const nodeIndex of start) {
     if (!hasNode(graph, nodeIndex)) {
-      throw new Error(`Start node ${nodeIndex} does not exist`);
+      throw missingNode(nodeIndex);
     }
   }
   return new Walker(f => ({
@@ -2693,9 +2804,9 @@ export const dfsPostOrder = (graph, config = {}) => {
       const discovered = new Set();
       const finished = new Set();
       // Initialize stack with start nodes
-      for (let i = startNodes.length - 1; i >= 0; i--) {
+      for (let i = start.length - 1; i >= 0; i--) {
         stack.push({
-          node: startNodes[i],
+          node: start[i],
           visitedChildren: false
         });
       }
@@ -2881,9 +2992,9 @@ export const externals = (graph, config = {}) => {
         let current = nodeIterator.next();
         while (!current.done) {
           const [nodeIndex, nodeData] = current.value;
-          const adjacencyList = getMapSafe(adjacencyMap, nodeIndex);
+          const adjacencyList = adjacencyMap.get(nodeIndex);
           // Node is external if it has no edges in the specified direction
-          if (Option.isNone(adjacencyList) || adjacencyList.value.length === 0) {
+          if (adjacencyList === undefined || adjacencyList.length === 0) {
             return {
               done: false,
               value: f(nodeIndex, nodeData)