@graphty/algorithms 1.3.1 → 1.5.0

package/src/flow/ford-fulkerson.ts

@@ -1,6 +1,6 @@
-import {bfsAugmentingPath} from "../algorithms/traversal/bfs-variants.js";
-import type {Graph} from "../core/graph.js";
-import {graphToMap} from "../utils/graph-converters.js";
+import { bfsAugmentingPath } from "../algorithms/traversal/bfs-variants.js";
+import type { Graph } from "../core/graph.js";
+import { graphToMap } from "../utils/graph-converters.js";
 
 /**
  * Ford-Fulkerson Algorithm for Maximum Flow
@@ -24,15 +24,15 @@ export interface FlowNetwork {
 export interface MaxFlowResult {
     maxFlow: number;
     flowGraph: Map<string, Map<string, number>>;
-    minCut?: {source: Set<string>, sink: Set<string>, edges: [string, string][]};
+    minCut?: { source: Set<string>; sink: Set<string>; edges: [string, string][] };
 }
 
 /**
  * Create residual graph from original graph
+ * @param graph - The original graph with capacity values
+ * @returns A residual graph initialized with the original capacities
  */
-function createResidualGraph(
-    graph: Map<string, Map<string, number>>,
-): Map<string, Map<string, number>> {
+function createResidualGraph(graph: Map<string, Map<string, number>>): Map<string, Map<string, number>> {
     const residual = new Map<string, Map<string, number>>();
 
     for (const [u, neighbors] of graph) {
@@ -50,6 +50,10 @@ function createResidualGraph(
 
 /**
  * Find augmenting path using DFS
+ * @param residualGraph - The residual graph with remaining capacities
+ * @param source - The source node
+ * @param sink - The sink node
+ * @returns An array of nodes forming the path, or null if no path exists
  */
 function findAugmentingPathDFS(
     residualGraph: Map<string, Map<string, number>>,
@@ -92,6 +96,11 @@ function findAugmentingPathDFS(
 
 /**
  * Update flow along an augmenting path
+ * @param residualGraph - The residual graph to update
+ * @param flowGraph - The flow graph to update with new flow values
+ * @param originalGraph - The original graph for edge direction reference
+ * @param path - The augmenting path to update flow along
+ * @param pathFlow - The amount of flow to push through the path
  */
 function updateFlow(
     residualGraph: Map<string, Map<string, number>>,
@@ -146,11 +155,14 @@ function updateFlow(
 
 /**
  * Find minimum cut from source side
+ * @param residualGraph - The residual graph after max flow computation
+ * @param source - The source node
+ * @returns The minimum cut partition with source and sink sets and cut edges
  */
 function findMinCut(
     residualGraph: Map<string, Map<string, number>>,
     source: string,
-): {source: Set<string>, sink: Set<string>, edges: [string, string][]} {
+): { source: Set<string>; sink: Set<string>; edges: [string, string][] } {
     // Find all reachable nodes from source in residual graph
     const sourceSet = new Set<string>();
     const queue = [source];
@@ -195,20 +207,29 @@ function findMinCut(
         }
     }
 
-    return {source: sourceSet, sink: sinkSet, edges: cutEdges};
+    return { source: sourceSet, sink: sinkSet, edges: cutEdges };
 }
 
 /**
  * Core max flow algorithm implementation
+ * @param graph - The graph with capacity values
+ * @param source - The source node
+ * @param sink - The sink node
+ * @param findPath - Function to find an augmenting path in the residual graph
+ * @returns The maximum flow result including flow value, flow graph, and minimum cut
  */
 function maxFlowCore(
     graph: Map<string, Map<string, number>>,
     source: string,
     sink: string,
-    findPath: (residual: Map<string, Map<string, number>>, src: string, snk: string) => {path: string[], pathCapacity: number} | null,
+    findPath: (
+        residual: Map<string, Map<string, number>>,
+        src: string,
+        snk: string,
+    ) => { path: string[]; pathCapacity: number } | null,
 ): MaxFlowResult {
     if (!graph.has(source) || !graph.has(sink)) {
-        return {maxFlow: 0, flowGraph: new Map()};
+        return { maxFlow: 0, flowGraph: new Map() };
     }
 
     // Create residual graph
@@ -230,7 +251,7 @@ function maxFlowCore(
     let pathResult = findPath(residualGraph, source, sink);
 
     while (pathResult !== null) {
-        const {path, pathCapacity} = pathResult;
+        const { path, pathCapacity } = pathResult;
 
         // Update flow
         updateFlow(residualGraph, flowGraph, graph, path, pathCapacity);
@@ -243,19 +264,23 @@ function maxFlowCore(
     // Find minimum cut
     const minCut = findMinCut(residualGraph, source);
 
-    return {maxFlow, flowGraph, minCut};
+    return { maxFlow, flowGraph, minCut };
 }
 
 /**
  * Internal implementation of Ford-Fulkerson algorithm using DFS
+ * @param graph - The graph with capacity values
+ * @param source - The source node
+ * @param sink - The sink node
+ * @returns The maximum flow result
  */
-function fordFulkersonImpl(
-    graph: Map<string, Map<string, number>>,
-    source: string,
-    sink: string,
-): MaxFlowResult {
+function fordFulkersonImpl(graph: Map<string, Map<string, number>>, source: string, sink: string): MaxFlowResult {
     // Adapter function for DFS path finding
-    const findPathDFS = (residual: Map<string, Map<string, number>>, src: string, snk: string): {path: string[], pathCapacity: number} | null => {
+    const findPathDFS = (
+        residual: Map<string, Map<string, number>>,
+        src: string,
+        snk: string,
+    ): { path: string[]; pathCapacity: number } | null => {
         const path = findAugmentingPathDFS(residual, src, snk);
         if (!path) {
             return null;
@@ -274,7 +299,7 @@ function fordFulkersonImpl(
             }
         }
 
-        return {path, pathCapacity};
+        return { path, pathCapacity };
     };
 
     return maxFlowCore(graph, source, sink, findPathDFS);
@@ -282,14 +307,18 @@ function fordFulkersonImpl(
 
 /**
  * Internal implementation of Edmonds-Karp algorithm
+ * @param graph - The graph with capacity values
+ * @param source - The source node
+ * @param sink - The sink node
+ * @returns The maximum flow result
  */
-function edmondsKarpImpl(
-    graph: Map<string, Map<string, number>>,
-    source: string,
-    sink: string,
-): MaxFlowResult {
+function edmondsKarpImpl(graph: Map<string, Map<string, number>>, source: string, sink: string): MaxFlowResult {
     // Use BFS variant for path finding
-    const findPathBFS = (residual: Map<string, Map<string, number>>, src: string, snk: string): {path: string[], pathCapacity: number} | null => {
+    const findPathBFS = (
+        residual: Map<string, Map<string, number>>,
+        src: string,
+        snk: string,
+    ): { path: string[]; pathCapacity: number } | null => {
         return bfsAugmentingPath(residual, src, snk);
     };
 
@@ -298,12 +327,16 @@ function edmondsKarpImpl(
 
 /**
  * Utility function to create a flow network for bipartite matching
+ * @param leftNodes - Array of left partition node identifiers
+ * @param rightNodes - Array of right partition node identifiers
+ * @param edges - Array of edges connecting left nodes to right nodes
+ * @returns The flow network graph with source and sink nodes
  */
 export function createBipartiteFlowNetwork(
     leftNodes: string[],
     rightNodes: string[],
     edges: [string, string][],
-): {graph: Map<string, Map<string, number>>, source: string, sink: string} {
+): { graph: Map<string, Map<string, number>>; source: string; sink: string } {
     const graph = new Map<string, Map<string, number>>();
     const source = "__source__";
     const sink = "__sink__";
@@ -345,12 +378,11 @@ export function createBipartiteFlowNetwork(
 
     graph.set(sink, new Map());
 
-    return {graph, source, sink};
+    return { graph, source, sink };
 }
 
 /**
  * Ford-Fulkerson algorithm using DFS for finding augmenting paths
- *
  * @param graph - Adjacency list representation with capacities - accepts Graph class or Map
  * @param source - Source node
  * @param sink - Sink node
@@ -359,11 +391,7 @@ export function createBipartiteFlowNetwork(
  * Time Complexity: O(E * f) where f is the maximum flow
  * Space Complexity: O(V + E)
  */
-export function fordFulkerson(
-    graph: Graph,
-    source: string,
-    sink: string,
-): MaxFlowResult {
+export function fordFulkerson(graph: Graph, source: string, sink: string): MaxFlowResult {
     // Convert Graph to Map representation
     const graphMap = graphToMap(graph);
     return fordFulkersonImpl(graphMap, source, sink);
@@ -372,7 +400,6 @@ export function fordFulkerson(
 /**
  * Edmonds-Karp algorithm (Ford-Fulkerson with BFS)
  * More efficient implementation with better time complexity
- *
  * @param graph - Adjacency list representation with capacities - accepts Graph class or Map
  * @param source - Source node
  * @param sink - Sink node

package/src/flow/min-cut.ts

@@ -4,21 +4,20 @@
  * Various algorithms for finding minimum cuts in graphs
  */
 
-import type {Graph} from "../core/graph.js";
-import {graphToMap} from "../utils/graph-converters.js";
-import {fordFulkerson} from "./ford-fulkerson.js";
+import type { Graph } from "../core/graph.js";
+import { graphToMap } from "../utils/graph-converters.js";
+import { fordFulkerson } from "./ford-fulkerson.js";
 
 export interface MinCutResult {
     cutValue: number;
     partition1: Set<string>;
     partition2: Set<string>;
-    cutEdges: {from: string, to: string, weight: number}[];
+    cutEdges: { from: string; to: string; weight: number }[];
 }
 
 /**
  * Find minimum s-t cut using max flow
  * The minimum cut value equals the maximum flow value (max-flow min-cut theorem)
- *
  * @param graph - Weighted graph
  * @param source - Source node
  * @param sink - Sink node
@@ -26,11 +25,7 @@ export interface MinCutResult {
  *
  * Time Complexity: Same as max flow algorithm used
  */
-export function minSTCut(
-    graph: Graph,
-    source: string,
-    sink: string,
-): MinCutResult {
+export function minSTCut(graph: Graph, source: string, sink: string): MinCutResult {
     const flowResult = fordFulkerson(graph, source, sink);
 
     if (!flowResult.minCut) {
@@ -42,14 +37,14 @@ export function minSTCut(
         };
     }
 
-    const cutEdges: {from: string, to: string, weight: number}[] = [];
+    const cutEdges: { from: string; to: string; weight: number }[] = [];
 
     // Find actual cut edges and their weights
     for (const [u, v] of flowResult.minCut.edges) {
         const edge = graph.getEdge(u, v);
         const weight = edge?.weight ?? 0;
         if (weight > 0) {
-            cutEdges.push({from: u, to: v, weight});
+            cutEdges.push({ from: u, to: v, weight });
         }
     }
 
@@ -64,15 +59,12 @@ export function minSTCut(
 /**
  * Stoer-Wagner algorithm for finding global minimum cut
  * Finds the minimum cut that separates the graph into two parts
- *
  * @param graph - Undirected weighted graph - accepts Graph class or Map representation
  * @returns Global minimum cut
  *
  * Time Complexity: O(V³) or O(VE + V² log V) with heap
  */
-export function stoerWagner(
-    graph: Graph | Map<string, Map<string, number>>,
-): MinCutResult {
+export function stoerWagner(graph: Graph | Map<string, Map<string, number>>): MinCutResult {
     // Convert Graph to Map representation if needed
     const graphMap = graph instanceof Map ? graph : graphToMap(graph);
     // Convert to undirected if necessary
@@ -140,13 +132,13 @@ export function stoerWagner(
     }
 
     // Find cut edges
-    const cutEdges: {from: string, to: string, weight: number}[] = [];
+    const cutEdges: { from: string; to: string; weight: number }[] = [];
     for (const u of partition1) {
         const neighbors = originalGraph.get(u);
         if (neighbors) {
             for (const [v, weight] of neighbors) {
                 if (partition2.has(v)) {
-                    cutEdges.push({from: u, to: v, weight});
+                    cutEdges.push({ from: u, to: v, weight });
                 }
             }
         }
@@ -162,11 +154,14 @@ export function stoerWagner(
 
 /**
  * Minimum cut phase of Stoer-Wagner algorithm
+ * @param graph - The undirected weighted graph
+ * @param nodes - Array of remaining nodes in the graph
+ * @returns The cut result with last two nodes, cut value, and partition
  */
 function minimumCutPhase(
     graph: Map<string, Map<string, number>>,
     nodes: string[],
-): {s: string, t: string, value: number, partition: string[]} {
+): { s: string; t: string; value: number; partition: string[] } {
     const n = nodes.length;
     const weight = new Map<string, number>();
     const added = new Set<string>();
@@ -180,7 +175,7 @@ function minimumCutPhase(
     // Start with arbitrary node
     let lastAdded = nodes[0];
     if (!lastAdded) {
-        return {s: "", t: "", value: 0, partition: []};
+        return { s: "", t: "", value: 0, partition: [] };
     }
 
     added.add(lastAdded);
@@ -188,7 +183,7 @@ function minimumCutPhase(
 
     // Add remaining nodes
     for (let i = 1; i < n; i++) {
-    // Update weights
+        // Update weights
         if (!lastAdded) {
             continue;
         }
@@ -225,7 +220,7 @@ function minimumCutPhase(
     const s = order[order.length - 2];
     const t = order[order.length - 1];
     if (!s || !t) {
-        return {s: "", t: "", value: 0, partition: []};
+        return { s: "", t: "", value: 0, partition: [] };
     }
 
     const cutValue = weight.get(t) ?? 0;
@@ -233,18 +228,17 @@ function minimumCutPhase(
     // Partition is all nodes except t
     const partition = order.slice(0, -1);
 
-    return {s, t, value: cutValue, partition};
+    return { s, t, value: cutValue, partition };
 }
 
 /**
  * Contract two nodes in the graph
+ * @param graph - The graph to modify by contracting nodes
+ * @param nodes - Array of nodes to update after contraction
+ * @param s - The node to keep after contraction
+ * @param t - The node to merge into s
  */
-function contractNodes(
-    graph: Map<string, Map<string, number>>,
-    nodes: string[],
-    s: string,
-    t: string,
-): void {
+function contractNodes(graph: Map<string, Map<string, number>>, nodes: string[], s: string, t: string): void {
     // Merge t into s
     const sNeighbors = graph.get(s);
     const tNeighbors = graph.get(t);
@@ -279,10 +273,10 @@ function contractNodes(
 
 /**
  * Convert directed graph to undirected
+ * @param graph - The directed graph to convert
+ * @returns An undirected graph with edges in both directions
  */
-function makeUndirected(
-    graph: Map<string, Map<string, number>>,
-): Map<string, Map<string, number>> {
+function makeUndirected(graph: Map<string, Map<string, number>>): Map<string, Map<string, number>> {
     const undirected = new Map<string, Map<string, number>>();
 
     // Initialize all nodes
@@ -315,17 +309,13 @@ function makeUndirected(
 /**
  * Karger's randomized min-cut algorithm
  * Probabilistic algorithm that finds min cut with high probability
- *
  * @param graph - Undirected graph - accepts Graph class or Map representation
  * @param iterations - Number of iterations (higher = better accuracy)
  * @returns Minimum cut found
  *
  * Time Complexity: O(V² * iterations)
  */
-export function kargerMinCut(
-    graph: Graph | Map<string, Map<string, number>>,
-    iterations = 100,
-): MinCutResult {
+export function kargerMinCut(graph: Graph | Map<string, Map<string, number>>, iterations = 100): MinCutResult {
     // Convert Graph to Map representation if needed
     const graphMap = graph instanceof Map ? graph : graphToMap(graph);
     let minCutValue = Infinity;
@@ -343,13 +333,13 @@ export function kargerMinCut(
     }
 
     // Find cut edges
-    const cutEdges: {from: string, to: string, weight: number}[] = [];
+    const cutEdges: { from: string; to: string; weight: number }[] = [];
     for (const u of bestPartition1) {
         const neighbors = graphMap.get(u);
         if (neighbors) {
             for (const [v, weight] of neighbors) {
                 if (bestPartition2.has(v)) {
-                    cutEdges.push({from: u, to: v, weight});
+                    cutEdges.push({ from: u, to: v, weight });
                 }
             }
         }
@@ -365,10 +355,14 @@ export function kargerMinCut(
 
 /**
  * Single run of Karger's algorithm
+ * @param graph - The undirected weighted graph
+ * @returns The cut result with cut value and two partitions
  */
-function kargerSingleRun(
-    graph: Map<string, Map<string, number>>,
-): {cutValue: number, partition1: Set<string>, partition2: Set<string>} {
+function kargerSingleRun(graph: Map<string, Map<string, number>>): {
+    cutValue: number;
+    partition1: Set<string>;
+    partition2: Set<string>;
+} {
     // Create a copy of the graph
     const workGraph = new Map<string, Map<string, number>>();
     const superNodes = new Map<string, Set<string>>();
@@ -381,11 +375,12 @@ function kargerSingleRun(
 
     // Contract until 2 nodes remain
     while (workGraph.size > 2) {
-    // Pick random edge
+        // Pick random edge
         const edges: [string, string, number][] = [];
         for (const [u, neighbors] of workGraph) {
             for (const [v, weight] of neighbors) {
-                if (u < v) { // Avoid duplicates
+                if (u < v) {
+                    // Avoid duplicates
                     edges.push([u, v, weight]);
                 }
             }
@@ -440,6 +435,10 @@ function kargerSingleRun(
 
 /**
  * Contract edge in Karger's algorithm
+ * @param graph - The working graph to modify
+ * @param superNodes - Map tracking which original nodes are in each super node
+ * @param u - First endpoint of the edge to contract
+ * @param v - Second endpoint of the edge to contract (merged into u)
  */
 function contractKarger(
     graph: Map<string, Map<string, number>>,
@@ -489,4 +488,3 @@ function contractKarger(
     graph.delete(v);
     superNodes.delete(v);
 }
-

package/src/index.ts

@@ -1,12 +1,13 @@
 /**
- * @graphty/algorithms - Graph algorithms library for browser environments
+ * graphty/algorithms - Graph algorithms library for browser environments
  *
  * A comprehensive TypeScript library implementing fundamental graph algorithms
  * optimized for browser environments and visualization applications.
+ * @module
  */
 
 // Core exports
-export {Graph} from "./core/graph.js";
+export { Graph } from "./core/graph.js";
 
 // Type exports
 export type {