effect 3.18.5 → 3.19.0

package/dist/cjs/Graph.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.values = exports.updateNode = exports.updateEdge = exports.undirected = exports.topo = exports.toGraphViz = exports.stronglyConnectedComponents = exports.reverse = exports.removeNode = exports.removeEdge = exports.nodes = exports.nodeCount = exports.neighborsDirected = exports.neighbors = exports.mutate = exports.mapNodes = exports.mapEdges = exports.isGraph = exports.isBipartite = exports.isAcyclic = exports.indices = exports.hasNode = exports.hasEdge = exports.getNode = exports.getEdge = exports.floydWarshall = exports.findNodes = exports.findNode = exports.findEdges = exports.findEdge = exports.filterNodes = exports.filterMapNodes = exports.filterMapEdges = exports.filterEdges = exports.externals = exports.entries = exports.endMutation = exports.edges = exports.edgeCount = exports.directed = exports.dijkstra = exports.dfsPostOrder = exports.dfs = exports.connectedComponents = exports.bfs = exports.bellmanFord = exports.beginMutation = exports.astar = exports.addNode = exports.addEdge = exports.Walker = exports.TypeId = exports.Edge = void 0;
+exports.values = exports.updateNode = exports.updateEdge = exports.undirected = exports.topo = exports.toMermaid = exports.toGraphViz = exports.stronglyConnectedComponents = exports.reverse = exports.removeNode = exports.removeEdge = exports.nodes = exports.nodeCount = exports.neighborsDirected = exports.neighbors = exports.mutate = exports.mapNodes = exports.mapEdges = exports.isGraph = exports.isBipartite = exports.isAcyclic = exports.indices = exports.hasNode = exports.hasEdge = exports.getNode = exports.getEdge = exports.floydWarshall = exports.findNodes = exports.findNode = exports.findEdges = exports.findEdge = exports.filterNodes = exports.filterMapNodes = exports.filterMapEdges = exports.filterEdges = exports.externals = exports.entries = exports.endMutation = exports.edges = exports.edgeCount = exports.directed = exports.dijkstra = exports.dfsPostOrder = exports.dfs = exports.connectedComponents = exports.bfs = exports.bellmanFord = exports.beginMutation = exports.astar = exports.addNode = exports.addEdge = exports.Walker = exports.TypeId = exports.GraphError = exports.Edge = void 0;
 var Data = _interopRequireWildcard(require("./Data.js"));
 var Equal = _interopRequireWildcard(require("./Equal.js"));
 var _Function = require("./Function.js");
@@ -17,17 +17,6 @@ function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r
  * @since 3.18.0
  */
 
-/**
- * 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.
  *
@@ -113,6 +102,21 @@ const ProtoGraph = {
   }
 };
 // =============================================================================
+// Errors
+// =============================================================================
+/**
+ * Error thrown when a graph operation fails.
+ *
+ * @since 3.18.0
+ * @category errors
+ */
+class GraphError extends /*#__PURE__*/Data.TaggedError("GraphError") {}
+/** @internal */
+exports.GraphError = GraphError;
+const missingNode = node => new GraphError({
+  message: `Node ${node} does not exist`
+});
+// =============================================================================
 // Constructors
 // =============================================================================
 /** @internal */
@@ -344,7 +348,7 @@ const addNode = (mutable, data) => {
  * @category getters
  */
 exports.addNode = addNode;
-const getNode = (graph, nodeIndex) => getMapSafe(graph.nodes, nodeIndex);
+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.
  *
@@ -923,10 +927,10 @@ const invalidateCycleFlagOnAddition = mutable => {
 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
@@ -937,23 +941,23 @@ 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
@@ -992,16 +996,16 @@ 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);
     }
   }
@@ -1050,43 +1054,43 @@ const removeEdge = (mutable, edgeIndex) => {
 exports.removeEdge = removeEdge;
 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);
       }
     }
   }
@@ -1123,7 +1127,7 @@ const removeEdgeInternal = (mutable, edgeIndex) => {
  * @since 3.18.0
  * @category getters
  */
-const getEdge = (graph, edgeIndex) => getMapSafe(graph.edges, edgeIndex);
+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.
  *
@@ -1154,14 +1158,14 @@ const getEdge = (graph, edgeIndex) => getMapSafe(graph.edges, edgeIndex);
  */
 exports.getEdge = getEdge;
 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;
     }
   }
@@ -1229,15 +1233,15 @@ const neighbors = (graph, nodeIndex) => {
   if (graph.type === "undirected") {
     return getUndirectedNeighbors(graph, nodeIndex);
   }
-  const adjacencyList = getMapSafe(graph.adjacency, nodeIndex);
-  if (Option.isNone(adjacencyList)) {
+  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;
@@ -1271,24 +1275,21 @@ const neighbors = (graph, nodeIndex) => {
 exports.neighbors = neighbors;
 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.
  *
@@ -1345,6 +1346,98 @@ const toGraphViz = (graph, options) => {
   lines.push("}");
   return lines.join("\n");
 };
+/** @internal */
+exports.toGraphViz = toGraphViz;
+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
+ */
+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)
@@ -1383,7 +1476,7 @@ const toGraphViz = (graph, options) => {
  * @since 3.18.0
  * @category algorithms
  */
-exports.toGraphViz = toGraphViz;
+exports.toMermaid = toMermaid;
 const isAcyclic = graph => {
   // Use existing cycle flag if available
   if (Option.isSome(graph.isAcyclic)) {
@@ -1529,13 +1622,13 @@ exports.isBipartite = isBipartite;
 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);
       }
     }
@@ -1670,12 +1763,12 @@ 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);
             }
@@ -1706,7 +1799,7 @@ 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
@@ -1717,20 +1810,25 @@ const stronglyConnectedComponents = graph => {
  * @category algorithms
  */
 exports.stronglyConnectedComponents = stronglyConnectedComponents;
-const dijkstra = (graph, source, target, edgeWeight) => {
+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
@@ -1770,13 +1868,13 @@ 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}`);
@@ -1788,7 +1886,7 @@ 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)) {
@@ -1809,13 +1907,13 @@ 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;
@@ -1824,7 +1922,7 @@ const dijkstra = (graph, source, target, edgeWeight) => {
   return Option.some({
     path,
     distance: targetDistance,
-    edgeWeights
+    costs
   });
 };
 /**
@@ -1855,7 +1953,7 @@ const dijkstra = (graph, source, target, edgeWeight) => {
  * @category algorithms
  */
 exports.dijkstra = dijkstra;
-const floydWarshall = (graph, edgeWeight) => {
+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
@@ -1875,7 +1973,7 @@ 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
@@ -1908,17 +2006,17 @@ 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 = [];
@@ -1936,14 +2034,14 @@ 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
   };
 };
 /**
@@ -1969,7 +2067,7 @@ 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
@@ -1980,25 +2078,31 @@ const floydWarshall = (graph, edgeWeight) => {
  * @category algorithms
  */
 exports.floydWarshall = floydWarshall;
-const astar = (graph, source, target, edgeWeight, heuristic) => {
+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)
@@ -2014,9 +2118,9 @@ 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)
@@ -2046,13 +2150,13 @@ 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}`);
@@ -2065,12 +2169,12 @@ 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
@@ -2093,13 +2197,13 @@ 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;
@@ -2108,7 +2212,7 @@ const astar = (graph, source, target, edgeWeight, heuristic) => {
   return Option.some({
     path,
     distance: targetGScore,
-    edgeWeights
+    costs
   });
 };
 /**
@@ -2131,7 +2235,7 @@ 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
@@ -2142,20 +2246,25 @@ const astar = (graph, source, target, edgeWeight, heuristic) => {
  * @category algorithms
  */
 exports.astar = astar;
-const bellmanFord = (graph, source, target, edgeWeight) => {
+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
@@ -2169,7 +2278,7 @@ 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,
@@ -2212,12 +2321,12 @@ 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);
             }
           }
         }
@@ -2235,13 +2344,13 @@ 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;
@@ -2250,7 +2359,7 @@ const bellmanFord = (graph, source, target, edgeWeight) => {
   return Option.some({
     path,
     distance: targetDistance,
-    edgeWeights
+    costs
   });
 };
 /**
@@ -2271,7 +2380,7 @@ 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
@@ -2308,7 +2417,7 @@ 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))
@@ -2341,7 +2450,7 @@ 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))
@@ -2373,7 +2482,7 @@ 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]
  * ```
@@ -2396,7 +2505,7 @@ 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"]
  * ```
@@ -2419,7 +2528,7 @@ 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"]]
  * ```
@@ -2448,7 +2557,7 @@ 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
  * }
@@ -2463,17 +2572,17 @@ const entries = walker => walker.visit((index, data) => [index, data]);
  */
 exports.entries = entries;
 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) {
@@ -2482,8 +2591,8 @@ 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);
@@ -2495,7 +2604,7 @@ const dfs = (graph, config = {}) => {
           }
           return {
             done: false,
-            value: f(current, nodeDataOption.value)
+            value: f(current, nodeDataOption)
           };
         }
         return {
@@ -2528,7 +2637,7 @@ 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
  * }
@@ -2543,17 +2652,17 @@ const dfs = (graph, config = {}) => {
  */
 exports.dfs = dfs;
 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) {
@@ -2642,7 +2751,7 @@ 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 => ({
@@ -2727,7 +2836,7 @@ 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
  * }
@@ -2738,12 +2847,12 @@ const topo = (graph, config = {}) => {
  */
 exports.topo = topo;
 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 => ({
@@ -2752,9 +2861,9 @@ 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
         });
       }
@@ -2943,9 +3052,9 @@ 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)