@graphty/algorithms 1.3.1 → 1.4.2

package/src/data-structures/priority-queue.ts

@@ -5,9 +5,13 @@
  * Uses a min-heap by default but supports custom comparison functions.
  */
 export class PriorityQueue<T> {
-    private heap: {item: T, priority: number}[];
+    private heap: { item: T; priority: number }[];
     private compareFn: (a: number, b: number) => number;
 
+    /**
+     * Creates a new PriorityQueue instance.
+     * @param compareFn - Custom comparison function for priorities. Returns negative if a has higher priority than b.
+     */
     constructor(compareFn?: (a: number, b: number) => number) {
         this.heap = [];
         // Default to min-heap (smaller priority values have higher priority)
@@ -16,15 +20,18 @@ export class PriorityQueue<T> {
 
     /**
      * Add an item with the given priority to the queue
+     * @param item - The item to add to the queue
+     * @param priority - The priority value for the item (lower values have higher priority in min-heap)
      */
     enqueue(item: T, priority: number): void {
-        const element = {item, priority};
+        const element = { item, priority };
         this.heap.push(element);
         this.heapifyUp(this.heap.length - 1);
     }
 
     /**
      * Remove and return the item with the highest priority
+     * @returns The item with the highest priority, or undefined if the queue is empty
      */
     dequeue(): T | undefined {
         if (this.heap.length === 0) {
@@ -52,6 +59,7 @@ export class PriorityQueue<T> {
 
     /**
      * View the item with the highest priority without removing it
+     * @returns The item with the highest priority, or undefined if the queue is empty
      */
     peek(): T | undefined {
         const first = this.heap[0];
@@ -60,6 +68,7 @@ export class PriorityQueue<T> {
 
     /**
      * Check if the queue is empty
+     * @returns True if the queue has no items, false otherwise
      */
     isEmpty(): boolean {
         return this.heap.length === 0;
@@ -67,6 +76,7 @@ export class PriorityQueue<T> {
 
     /**
      * Get the number of items in the queue
+     * @returns The number of items currently in the queue
      */
     size(): number {
         return this.heap.length;
@@ -74,7 +84,9 @@ export class PriorityQueue<T> {
 
     /**
      * Update the priority of an item if it exists in the queue
-     * Returns true if the item was found and updated
+     * @param item - The item whose priority should be updated
+     * @param newPriority - The new priority value for the item
+     * @returns True if the item was found and updated, false otherwise
      */
     updatePriority(item: T, newPriority: number): boolean {
         const index = this.heap.findIndex((element) => element.item === item);
@@ -110,13 +122,15 @@ export class PriorityQueue<T> {
 
     /**
      * Convert queue to array (for testing/debugging)
+     * @returns An array of all items with their priorities
      */
-    toArray(): {item: T, priority: number}[] {
-        return [... this.heap];
+    toArray(): { item: T; priority: number }[] {
+        return [...this.heap];
     }
 
     /**
      * Move element up the heap until heap property is satisfied
+     * @param index - The index of the element to heapify up
      */
     private heapifyUp(index: number): void {
         if (index === 0) {
@@ -136,26 +150,35 @@ export class PriorityQueue<T> {
 
     /**
      * Move element down the heap until heap property is satisfied
+     * @param index - The index of the element to heapify down
      */
     private heapifyDown(index: number): void {
-        const leftChildIndex = (2 * index) + 1;
-        const rightChildIndex = (2 * index) + 2;
+        const leftChildIndex = 2 * index + 1;
+        const rightChildIndex = 2 * index + 2;
         let targetIndex = index;
 
         // Find the child with highest priority (lowest value for min-heap)
         const leftChild = this.heap[leftChildIndex];
         const target = this.heap[targetIndex];
 
-        if (leftChildIndex < this.heap.length && leftChild && target &&
-            this.compareFn(leftChild.priority, target.priority) < 0) {
+        if (
+            leftChildIndex < this.heap.length &&
+            leftChild &&
+            target &&
+            this.compareFn(leftChild.priority, target.priority) < 0
+        ) {
             targetIndex = leftChildIndex;
         }
 
         const rightChild = this.heap[rightChildIndex];
         const newTarget = this.heap[targetIndex];
 
-        if (rightChildIndex < this.heap.length && rightChild && newTarget &&
-            this.compareFn(rightChild.priority, newTarget.priority) < 0) {
+        if (
+            rightChildIndex < this.heap.length &&
+            rightChild &&
+            newTarget &&
+            this.compareFn(rightChild.priority, newTarget.priority) < 0
+        ) {
             targetIndex = rightChildIndex;
         }
 
@@ -168,6 +191,8 @@ export class PriorityQueue<T> {
 
     /**
      * Swap two elements in the heap
+     * @param i - Index of the first element
+     * @param j - Index of the second element
      */
     private swap(i: number, j: number): void {
         const temp = this.heap[i];

package/src/data-structures/union-find.ts

@@ -1,4 +1,4 @@
-import type {NodeId} from "../types/index.js";
+import type { NodeId } from "../types/index.js";
 
 /**
  * Union-Find (Disjoint Set) data structure with path compression and union by rank
@@ -11,6 +11,10 @@ export class UnionFind {
     private rank: Map<NodeId, number>;
     private componentCount: number;
 
+    /**
+     * Creates a new UnionFind data structure with the given elements.
+     * @param elements - Array of elements to initialize the data structure with
+     */
     constructor(elements: NodeId[]) {
         this.parent = new Map();
         this.rank = new Map();
@@ -25,6 +29,8 @@ export class UnionFind {
 
     /**
      * Find the root of the set containing the element with path compression
+     * @param element - The element to find the root for
+     * @returns The root element of the set containing the given element
      */
     find(element: NodeId): NodeId {
         const parent = this.parent.get(element);
@@ -48,6 +54,8 @@ export class UnionFind {
 
     /**
      * Union two sets using union by rank
+     * @param elementA - The first element whose set should be merged
+     * @param elementB - The second element whose set should be merged
      */
     union(elementA: NodeId, elementB: NodeId): void {
         const rootA = this.find(elementA);
@@ -80,6 +88,9 @@ export class UnionFind {
 
     /**
      * Check if two elements are in the same connected component
+     * @param elementA - The first element to check
+     * @param elementB - The second element to check
+     * @returns True if both elements are in the same component, false otherwise
      */
     connected(elementA: NodeId, elementB: NodeId): boolean {
         try {
@@ -91,6 +102,7 @@ export class UnionFind {
 
     /**
      * Get the number of connected components
+     * @returns The current count of disjoint components
      */
     getComponentCount(): number {
         return this.componentCount;
@@ -98,6 +110,8 @@ export class UnionFind {
 
     /**
      * Get all elements that belong to the same component as the given element
+     * @param element - The element whose component should be retrieved
+     * @returns Array of all elements in the same component
      */
     getComponent(element: NodeId): NodeId[] {
         const root = this.find(element);
@@ -114,6 +128,7 @@ export class UnionFind {
 
     /**
      * Get all connected components as separate arrays
+     * @returns Array of arrays, where each inner array contains elements of one component
      */
     getAllComponents(): NodeId[][] {
         const componentMap = new Map<NodeId, NodeId[]>();
@@ -136,6 +151,8 @@ export class UnionFind {
 
     /**
      * Get the size of the component containing the given element
+     * @param element - The element whose component size should be retrieved
+     * @returns The number of elements in the component containing the given element
      */
     getComponentSize(element: NodeId): number {
         return this.getComponent(element).length;
@@ -143,6 +160,7 @@ export class UnionFind {
 
     /**
      * Add a new element to the data structure
+     * @param element - The element to add as a new singleton set
      */
     addElement(element: NodeId): void {
         if (this.parent.has(element)) {
@@ -156,6 +174,8 @@ export class UnionFind {
 
     /**
      * Check if an element exists in the data structure
+     * @param element - The element to check for
+     * @returns True if the element exists, false otherwise
      */
     hasElement(element: NodeId): boolean {
         return this.parent.has(element);
@@ -163,6 +183,7 @@ export class UnionFind {
 
     /**
      * Get the total number of elements
+     * @returns The total count of all elements in the data structure
      */
     size(): number {
         return this.parent.size;

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