effect 3.21.5 → 3.22.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.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;
+exports.values = exports.updateNode = exports.updateEdge = exports.undirected = exports.topo = exports.toMermaid = exports.toGraphViz = exports.successors = exports.stronglyConnectedComponents = exports.reverse = exports.removeNode = exports.removeEdge = exports.predecessors = 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");
@@ -658,6 +658,24 @@ const mapEdges = (mutable, f) => {
     });
   }
 };
+/** @internal */
+exports.mapEdges = mapEdges;
+const rebuildAdjacency = mutable => {
+  mutable.adjacency.clear();
+  mutable.reverseAdjacency.clear();
+  for (const nodeIndex of mutable.nodes.keys()) {
+    mutable.adjacency.set(nodeIndex, []);
+    mutable.reverseAdjacency.set(nodeIndex, []);
+  }
+  for (const [edgeIndex, edgeData] of mutable.edges) {
+    mutable.adjacency.get(edgeData.source).push(edgeIndex);
+    mutable.reverseAdjacency.get(edgeData.target).push(edgeIndex);
+    if (mutable.type === "undirected") {
+      mutable.adjacency.get(edgeData.target).push(edgeIndex);
+      mutable.reverseAdjacency.get(edgeData.source).push(edgeIndex);
+    }
+  }
+};
 /**
  * Reverses all edge directions in a mutable graph by swapping source and target nodes.
  *
@@ -681,8 +699,10 @@ const mapEdges = (mutable, f) => {
  * @since 3.18.0
  * @category transformations
  */
-exports.mapEdges = mapEdges;
 const reverse = mutable => {
+  if (mutable.type === "undirected") {
+    return;
+  }
   // Reverse all edges by swapping source and target
   for (const [index, edgeData] of mutable.edges) {
     mutable.edges.set(index, {
@@ -691,20 +711,7 @@ const reverse = mutable => {
       data: edgeData.data
     });
   }
-  // Clear and rebuild adjacency lists with reversed directions
-  mutable.adjacency.clear();
-  mutable.reverseAdjacency.clear();
-  // Rebuild adjacency lists with reversed directions
-  for (const [edgeIndex, edgeData] of mutable.edges) {
-    // Add to forward adjacency (source -> target)
-    const sourceEdges = mutable.adjacency.get(edgeData.source) || [];
-    sourceEdges.push(edgeIndex);
-    mutable.adjacency.set(edgeData.source, sourceEdges);
-    // Add to reverse adjacency (target <- source)
-    const targetEdges = mutable.reverseAdjacency.get(edgeData.target) || [];
-    targetEdges.push(edgeIndex);
-    mutable.reverseAdjacency.set(edgeData.target, targetEdges);
-  }
+  rebuildAdjacency(mutable);
   // Invalidate cycle flag since edge directions changed
   mutable.isAcyclic = Option.none();
 };
@@ -1165,8 +1172,11 @@ const hasEdge = (graph, source, target) => {
   // Check if any edge in the adjacency list connects to the target
   for (const edgeIndex of adjacencyList) {
     const edge = graph.edges.get(edgeIndex);
-    if (edge !== undefined && edge.target === target) {
-      return true;
+    if (edge !== undefined) {
+      const neighbor = graph.type === "undirected" && edge.target === source ? edge.source : edge.target;
+      if (neighbor === target) {
+        return true;
+      }
     }
   }
   return false;
@@ -1198,6 +1208,22 @@ const hasEdge = (graph, source, target) => {
  */
 exports.hasEdge = hasEdge;
 const edgeCount = graph => graph.edges.size;
+exports.edgeCount = edgeCount;
+const getDirectedNeighbors = (graph, nodeIndex, direction) => {
+  const adjacencyMap = direction === "incoming" ? graph.reverseAdjacency : graph.adjacency;
+  const adjacencyList = adjacencyMap.get(nodeIndex);
+  if (adjacencyList === undefined) {
+    return [];
+  }
+  const result = [];
+  for (const edgeIndex of adjacencyList) {
+    const edge = graph.edges.get(edgeIndex);
+    if (edge !== undefined) {
+      result.push(direction === "incoming" ? edge.source : edge.target);
+    }
+  }
+  return result;
+};
 /**
  * Returns the neighboring nodes (targets of outgoing edges) for a given node.
  *
@@ -1227,27 +1253,49 @@ const edgeCount = graph => graph.edges.size;
  * @since 3.18.0
  * @category getters
  */
-exports.edgeCount = edgeCount;
 const neighbors = (graph, nodeIndex) => {
   // 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 [];
+  return getDirectedNeighbors(graph, nodeIndex, "outgoing");
+};
+/**
+ * Returns the outgoing neighbor node indices for a node in a directed graph.
+ *
+ * Throws a `GraphError` when used with an undirected graph.
+ *
+ * @since 3.22.0
+ * @category queries
+ */
+exports.neighbors = neighbors;
+const successors = (graph, nodeIndex) => {
+  if (graph.type === "undirected") {
+    throw new GraphError({
+      message: "Cannot get successors of undirected graph"
+    });
   }
-  const result = [];
-  for (const edgeIndex of adjacencyList) {
-    const edge = graph.edges.get(edgeIndex);
-    if (edge !== undefined) {
-      result.push(edge.target);
-    }
+  return getDirectedNeighbors(graph, nodeIndex, "outgoing");
+};
+/**
+ * Returns the incoming neighbor node indices for a node in a directed graph.
+ *
+ * Throws a `GraphError` when used with an undirected graph.
+ *
+ * @since 3.22.0
+ * @category queries
+ */
+exports.successors = successors;
+const predecessors = (graph, nodeIndex) => {
+  if (graph.type === "undirected") {
+    throw new GraphError({
+      message: "Cannot get predecessors of undirected graph"
+    });
   }
-  return result;
+  return getDirectedNeighbors(graph, nodeIndex, "incoming");
 };
 /**
- * Get neighbors of a node in a specific direction for bidirectional traversal.
+ * Get directed neighbors of a node in a specific direction.
  *
  * @example
  * ```ts
@@ -1269,26 +1317,18 @@ const neighbors = (graph, nodeIndex) => {
  * const incoming = Graph.neighborsDirected(graph, nodeB, "incoming")
  * ```
  *
+ * @deprecated Use {@link successors} for outgoing neighbors or {@link predecessors} for incoming neighbors.
  * @since 3.18.0
  * @category queries
  */
-exports.neighbors = neighbors;
+exports.predecessors = predecessors;
 const neighborsDirected = (graph, nodeIndex, direction) => {
-  const adjacencyMap = direction === "incoming" ? graph.reverseAdjacency : graph.adjacency;
-  const adjacencyList = adjacencyMap.get(nodeIndex);
-  if (adjacencyList === undefined) {
-    return [];
-  }
-  const result = [];
-  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.source : edge.target;
-      result.push(neighborNode);
-    }
+  if (graph.type === "undirected") {
+    throw new GraphError({
+      message: "Cannot get directed neighbors of undirected graph"
+    });
   }
-  return result;
+  return getDirectedNeighbors(graph, nodeIndex, direction);
 };
 /**
  * Exports a graph to GraphViz DOT format for visualization.
@@ -1542,7 +1582,7 @@ const isAcyclic = graph => {
         visited.add(node);
         recursionStack.add(node);
         // Get neighbors for this node
-        const nodeNeighbors = Array.from(neighborsDirected(graph, node, "outgoing"));
+        const nodeNeighbors = getDirectedNeighbors(graph, node, "outgoing");
         stack[stack.length - 1] = [node, nodeNeighbors, 0, false];
         continue;
       }
@@ -1669,7 +1709,7 @@ const getUndirectedNeighbors = (graph, nodeIndex) => {
   }
   return Array.from(neighbors);
 };
-const getTraversalNeighbors = (graph, nodeIndex, direction) => graph.type === "undirected" ? getUndirectedNeighbors(graph, nodeIndex) : neighborsDirected(graph, nodeIndex, direction);
+const getTraversalNeighbors = (graph, nodeIndex, direction) => graph.type === "undirected" ? getUndirectedNeighbors(graph, nodeIndex) : getDirectedNeighbors(graph, nodeIndex, direction);
 const getTraversableNeighbor = (graph, current, edge) => graph.type === "undirected" && edge.target === current ? edge.source : edge.target;
 /**
  * Find connected components in an undirected graph.
@@ -1748,6 +1788,11 @@ const connectedComponents = graph => {
  */
 exports.connectedComponents = connectedComponents;
 const stronglyConnectedComponents = graph => {
+  if (graph.type === "undirected") {
+    throw new GraphError({
+      message: "Cannot find strongly connected components of undirected graph"
+    });
+  }
   const visited = new Set();
   const finishOrder = [];
   for (const startNode of graph.nodes.keys()) {
@@ -1763,7 +1808,7 @@ const stronglyConnectedComponents = graph => {
           continue;
         }
         visited.add(node);
-        const nodeNeighborsList = neighbors(graph, node);
+        const nodeNeighborsList = getDirectedNeighbors(graph, node, "outgoing");
         stack[stack.length - 1] = [node, nodeNeighborsList, 0, false];
         continue;
       }
@@ -1816,6 +1861,20 @@ const stronglyConnectedComponents = graph => {
   }
   return sccs;
 };
+exports.stronglyConnectedComponents = stronglyConnectedComponents;
+const validateNonNegativeEdgeWeights = (graph, cost, algorithm) => {
+  const edgeWeights = new Map();
+  for (const [edgeIndex, edgeData] of graph.edges) {
+    const weight = cost(edgeData.data);
+    if (weight < 0 || Number.isNaN(weight)) {
+      throw new GraphError({
+        message: `${algorithm} requires non-negative edge weights`
+      });
+    }
+    edgeWeights.set(edgeIndex, weight);
+  }
+  return edgeWeights;
+};
 /**
  * Find the shortest path between two nodes using Dijkstra's algorithm.
  *
@@ -1845,7 +1904,6 @@ const stronglyConnectedComponents = graph => {
  * @since 3.18.0
  * @category algorithms
  */
-exports.stronglyConnectedComponents = stronglyConnectedComponents;
 const dijkstra = (graph, config) => {
   const {
     cost,
@@ -1859,6 +1917,7 @@ const dijkstra = (graph, config) => {
   if (!graph.nodes.has(target)) {
     throw missingNode(target);
   }
+  const edgeWeights = validateNonNegativeEdgeWeights(graph, cost, "Dijkstra's algorithm");
   // Early return if source equals target
   if (source === target) {
     return Option.some({
@@ -1910,11 +1969,7 @@ const dijkstra = (graph, config) => {
         const edge = graph.edges.get(edgeIndex);
         if (edge !== undefined) {
           const neighbor = getTraversableNeighbor(graph, currentNode, edge);
-          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}`);
-          }
+          const weight = edgeWeights.get(edgeIndex);
           const newDistance = currentDistance + weight;
           const neighborDistance = distances.get(neighbor);
           // Relaxation step
@@ -2136,6 +2191,7 @@ const astar = (graph, config) => {
   if (!graph.nodes.has(target)) {
     throw missingNode(target);
   }
+  const edgeWeights = validateNonNegativeEdgeWeights(graph, cost, "A* algorithm");
   // Early return if source equals target
   if (source === target) {
     return Option.some({
@@ -2200,11 +2256,7 @@ const astar = (graph, config) => {
         const edge = graph.edges.get(edgeIndex);
         if (edge !== undefined) {
           const neighbor = getTraversableNeighbor(graph, currentNode, edge);
-          const weight = cost(edge.data);
-          // Validate non-negative weights
-          if (weight < 0) {
-            throw new Error(`A* algorithm requires non-negative edge weights, found ${weight}`);
-          }
+          const weight = edgeWeights.get(edgeIndex);
           const tentativeGScore = currentGScore + weight;
           const neighborGScore = gScore.get(neighbor);
           // If this path to neighbor is better than any previous one
@@ -2810,6 +2862,7 @@ const topo = (graph, config = {}) => {
     [Symbol.iterator]: () => {
       const inDegree = new Map();
       const remaining = new Set();
+      const initialSet = new Set(initials);
       const queue = [...initials];
       // Initialize in-degree counts
       for (const [nodeIndex] of graph.nodes) {
@@ -2821,12 +2874,16 @@ const topo = (graph, config = {}) => {
         const currentInDegree = inDegree.get(edgeData.target) || 0;
         inDegree.set(edgeData.target, currentInDegree + 1);
       }
-      // Add nodes with zero in-degree to queue if no initials provided
-      if (initials.length === 0) {
-        for (const [nodeIndex, degree] of inDegree) {
-          if (degree === 0) {
-            queue.push(nodeIndex);
-          }
+      for (const nodeIndex of initials) {
+        if (inDegree.get(nodeIndex) !== 0) {
+          throw new GraphError({
+            message: `Initial node ${nodeIndex} has incoming edges`
+          });
+        }
+      }
+      for (const [nodeIndex, degree] of inDegree) {
+        if (degree === 0 && !initialSet.has(nodeIndex)) {
+          queue.push(nodeIndex);
         }
       }
       const nextMapped = () => {
@@ -2835,7 +2892,7 @@ const topo = (graph, config = {}) => {
           if (remaining.has(current)) {
             remaining.delete(current);
             // Process outgoing edges, reducing in-degree of targets
-            const neighbors = neighborsDirected(graph, current, "outgoing");
+            const neighbors = getDirectedNeighbors(graph, current, "outgoing");
             for (const neighbor of neighbors) {
               if (remaining.has(neighbor)) {
                 const currentInDegree = inDegree.get(neighbor) || 0;