@graphty/algorithms 1.2.0 → 1.4.2

package/src/algorithms/shortest-path/floyd-warshall.ts

@@ -1,5 +1,5 @@
-import {Graph} from "../../core/graph.js";
-import type {NodeId} from "../../types/index.js";
+import { Graph } from "../../core/graph.js";
+import type { NodeId } from "../../types/index.js";
 
 export interface FloydWarshallResult {
     distances: Map<NodeId, Map<NodeId, number>>;
@@ -7,6 +7,11 @@ export interface FloydWarshallResult {
     hasNegativeCycle: boolean;
 }
 
+/**
+ * Computes all-pairs shortest paths using the Floyd-Warshall algorithm
+ * @param graph - The graph to compute shortest paths for
+ * @returns The distances, predecessors, and negative cycle detection result
+ */
 export function floydWarshall(graph: Graph): FloydWarshallResult {
     const nodes = Array.from(graph.nodes()).map((n) => n.id);
     const distances = new Map<NodeId, Map<NodeId, number>>();
@@ -105,11 +110,18 @@ export function floydWarshall(graph: Graph): FloydWarshallResult {
     };
 }
 
+/**
+ * Finds the shortest path between two nodes using Floyd-Warshall
+ * @param graph - The graph to search
+ * @param source - The starting node for the path
+ * @param target - The destination node for the path
+ * @returns The path and distance or null if no path exists
+ */
 export function floydWarshallPath(
     graph: Graph,
     source: NodeId,
     target: NodeId,
-): {path: NodeId[], distance: number} | null {
+): { path: NodeId[]; distance: number } | null {
     const result = floydWarshall(graph);
 
     if (!graph.hasNode(source) || !graph.hasNode(target)) {
@@ -146,12 +158,17 @@ export function floydWarshallPath(
 
     if (current === source) {
         path.unshift(source);
-        return {path, distance};
+        return { path, distance };
     }
 
     return null;
 }
 
+/**
+ * Computes the transitive closure of a graph using Floyd-Warshall
+ * @param graph - The graph to compute transitive closure for
+ * @returns A map of each node to the set of nodes reachable from it
+ */
 export function transitiveClosure(graph: Graph): Map<NodeId, Set<NodeId>> {
     const result = floydWarshall(graph);
     const closure = new Map<NodeId, Set<NodeId>>();

package/src/algorithms/shortest-path/index.ts

@@ -2,8 +2,8 @@
  * Shortest path algorithms
  */
 
-export type {BellmanFordOptions, BellmanFordResult} from "./bellman-ford.js";
-export {bellmanFord, bellmanFordPath, hasNegativeCycle} from "./bellman-ford.js";
-export {allPairsShortestPath, dijkstra, dijkstraPath, singleSourceShortestPath} from "./dijkstra.js";
-export type {FloydWarshallResult} from "./floyd-warshall.js";
-export {floydWarshall, floydWarshallPath, transitiveClosure} from "./floyd-warshall.js";
+export type { BellmanFordOptions, BellmanFordResult } from "./bellman-ford.js";
+export { bellmanFord, bellmanFordPath, hasNegativeCycle } from "./bellman-ford.js";
+export { allPairsShortestPath, dijkstra, dijkstraPath, singleSourceShortestPath } from "./dijkstra.js";
+export type { FloydWarshallResult } from "./floyd-warshall.js";
+export { floydWarshall, floydWarshallPath, transitiveClosure } from "./floyd-warshall.js";

package/src/algorithms/traversal/bfs-unified.ts

@@ -0,0 +1,437 @@
+import type { Graph } from "../../core/graph.js";
+import { CSRGraph } from "../../optimized/csr-graph.js";
+import { DirectionOptimizedBFS } from "../../optimized/direction-optimized-bfs.js";
+import { toCSRGraph } from "../../optimized/graph-adapter.js";
+import type { NodeId, ShortestPathResult, TraversalOptions, TraversalResult } from "../../types/index.js";
+import { reconstructPath } from "../../utils/graph-utilities.js";
+
+/**
+ * Unified BFS implementation that automatically optimizes for large graphs
+ *
+ * This module provides a single, user-friendly BFS implementation that:
+ * - Automatically uses Direction-Optimized BFS for large graphs (>10k nodes)
+ * - Maintains backward compatibility with existing APIs
+ * - Requires no configuration or understanding of optimization thresholds
+ * - Provides the best performance by default
+ */
+
+// Cache for CSR conversions to avoid repeated conversions
+const csrCache = new WeakMap<Graph, CSRGraph>();
+
+/**
+ * Get or create CSR representation of a graph
+ * @param graph - The input graph to convert
+ * @returns CSR graph representation (cached for efficiency)
+ */
+function getCSRGraph(graph: Graph): CSRGraph {
+    let csrGraph = csrCache.get(graph);
+    if (!csrGraph) {
+        csrGraph = toCSRGraph(graph);
+        csrCache.set(graph, csrGraph);
+    }
+
+    return csrGraph;
+}
+
+/**
+ * Perform breadth-first search starting from a given node
+ *
+ * Automatically uses the most optimized implementation based on graph size.
+ * No configuration needed - just call this function for the best performance.
+ * @param graph - The input graph to traverse
+ * @param startNode - The node to start the BFS from
+ * @param options - Traversal options (callbacks, target node, etc.)
+ * @returns Traversal result with visited nodes, order, and tree structure
+ */
+export function breadthFirstSearch(graph: Graph, startNode: NodeId, options: TraversalOptions = {}): TraversalResult {
+    if (!graph.hasNode(startNode)) {
+        throw new Error(`Start node ${String(startNode)} not found in graph`);
+    }
+
+    // Automatically use optimized implementation for large graphs
+    if (graph.nodeCount > 10000) {
+        return breadthFirstSearchOptimized(graph, startNode, options);
+    }
+
+    // Standard implementation for smaller graphs
+    return breadthFirstSearchStandard(graph, startNode, options);
+}
+
+/**
+ * Standard BFS implementation for smaller graphs
+ * @param graph - The input graph to traverse
+ * @param startNode - The node to start the BFS from
+ * @param options - Traversal options (callbacks, target node, etc.)
+ * @returns Traversal result with visited nodes, order, and tree structure
+ */
+function breadthFirstSearchStandard(graph: Graph, startNode: NodeId, options: TraversalOptions = {}): TraversalResult {
+    const visited = new Set<NodeId>();
+    const queue: { node: NodeId; level: number }[] = [];
+    const order: NodeId[] = [];
+    const tree = new Map<NodeId, NodeId | null>();
+
+    // Initialize with start node
+    queue.push({ node: startNode, level: 0 });
+    visited.add(startNode);
+    tree.set(startNode, null);
+
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current) {
+            break;
+        }
+
+        order.push(current.node);
+
+        // Call visitor callback if provided
+        if (options.visitCallback) {
+            options.visitCallback(current.node, current.level);
+        }
+
+        // Early termination if target found
+        if (options.targetNode && current.node === options.targetNode) {
+            break;
+        }
+
+        // Explore neighbors
+        for (const neighbor of graph.neighbors(current.node)) {
+            if (!visited.has(neighbor)) {
+                visited.add(neighbor);
+                tree.set(neighbor, current.node);
+                queue.push({ node: neighbor, level: current.level + 1 });
+            }
+        }
+    }
+
+    return { visited, order, tree };
+}
+
+/**
+ * Optimized BFS implementation using Direction-Optimized BFS
+ * @param graph - The input graph to traverse
+ * @param startNode - The node to start the BFS from
+ * @param options - Traversal options (callbacks, target node, etc.)
+ * @returns Traversal result with visited nodes, order, and tree structure
+ */
+function breadthFirstSearchOptimized(graph: Graph, startNode: NodeId, options: TraversalOptions = {}): TraversalResult {
+    const csrGraph = getCSRGraph(graph);
+
+    const dobfs = new DirectionOptimizedBFS(csrGraph, {
+        alpha: 15.0,
+        beta: 20.0,
+    });
+
+    const result = dobfs.search(startNode);
+
+    // Convert result to TraversalResult format
+    const visited = new Set<NodeId>();
+    const order: NodeId[] = [];
+    const tree = new Map<NodeId, NodeId | null>();
+
+    // Build traversal order using BFS from distances
+    const nodesByDistance = new Map<number, NodeId[]>();
+    let maxDistance = 0;
+
+    for (const [nodeId, distance] of result.distances) {
+        visited.add(nodeId);
+        tree.set(nodeId, result.parents.get(nodeId) ?? null);
+
+        if (!nodesByDistance.has(distance)) {
+            nodesByDistance.set(distance, []);
+        }
+
+        nodesByDistance.get(distance)?.push(nodeId);
+        maxDistance = Math.max(maxDistance, distance);
+    }
+
+    // Reconstruct BFS order
+    for (let d = 0; d <= maxDistance; d++) {
+        const nodes = nodesByDistance.get(d);
+        if (nodes) {
+            order.push(...nodes);
+        }
+    }
+
+    // Handle visit callback if provided
+    if (options.visitCallback) {
+        for (const [nodeId, distance] of result.distances) {
+            options.visitCallback(nodeId, distance);
+        }
+    }
+
+    return { visited, order, tree };
+}
+
+/**
+ * Find shortest path between two nodes using BFS
+ *
+ * Automatically optimized for large graphs. Returns null if no path exists.
+ * @param graph - The input graph to search
+ * @param source - The source node ID
+ * @param target - The target node ID
+ * @returns Shortest path result or null if no path exists
+ */
+export function shortestPathBFS(graph: Graph, source: NodeId, target: NodeId): ShortestPathResult | null {
+    if (!graph.hasNode(source)) {
+        throw new Error(`Source node ${String(source)} not found in graph`);
+    }
+
+    if (!graph.hasNode(target)) {
+        throw new Error(`Target node ${String(target)} not found in graph`);
+    }
+
+    // Special case: source equals target
+    if (source === target) {
+        return {
+            distance: 0,
+            path: [source],
+            predecessor: new Map([[source, null]]),
+        };
+    }
+
+    // Use optimized implementation for large graphs
+    if (graph.nodeCount > 10000) {
+        return shortestPathBFSOptimized(graph, source, target);
+    }
+
+    // Standard implementation
+    return shortestPathBFSStandard(graph, source, target);
+}
+
+/**
+ * Standard shortest path BFS
+ * @param graph - The input graph to search
+ * @param source - The source node ID
+ * @param target - The target node ID
+ * @returns Shortest path result or null if no path exists
+ */
+function shortestPathBFSStandard(graph: Graph, source: NodeId, target: NodeId): ShortestPathResult | null {
+    const visited = new Set<NodeId>();
+    const queue: { node: NodeId; distance: number }[] = [];
+    const predecessor = new Map<NodeId, NodeId | null>();
+
+    // Initialize BFS
+    queue.push({ node: source, distance: 0 });
+    visited.add(source);
+    predecessor.set(source, null);
+
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current) {
+            break;
+        }
+
+        // Target found
+        if (current.node === target) {
+            const path = reconstructPath(target, predecessor);
+            return {
+                distance: current.distance,
+                path,
+                predecessor,
+            };
+        }
+
+        // Explore neighbors
+        for (const neighbor of graph.neighbors(current.node)) {
+            if (!visited.has(neighbor)) {
+                visited.add(neighbor);
+                predecessor.set(neighbor, current.node);
+                queue.push({ node: neighbor, distance: current.distance + 1 });
+            }
+        }
+    }
+
+    // No path found
+    return null;
+}
+
+/**
+ * Optimized shortest path using Direction-Optimized BFS
+ * @param graph - The input graph to search
+ * @param source - The source node ID
+ * @param target - The target node ID
+ * @returns Shortest path result or null if no path exists
+ */
+function shortestPathBFSOptimized(graph: Graph, source: NodeId, target: NodeId): ShortestPathResult | null {
+    const csrGraph = getCSRGraph(graph);
+
+    const dobfs = new DirectionOptimizedBFS(csrGraph, {
+        alpha: 15.0,
+        beta: 20.0,
+    });
+
+    // Perform BFS
+    const result = dobfs.search(source);
+
+    // Check if target was reached
+    const distance = result.distances.get(target);
+    if (distance === undefined) {
+        return null; // No path found
+    }
+
+    // Reconstruct path
+    const path = reconstructPath(target, result.parents);
+
+    return {
+        distance,
+        path,
+        predecessor: result.parents,
+    };
+}
+
+/**
+ * Find shortest paths from source to all reachable nodes
+ *
+ * Automatically optimized for large graphs.
+ * @param graph - The input graph to search
+ * @param source - The source node ID to compute shortest paths from
+ * @returns Map of node IDs to their shortest path results
+ */
+export function singleSourceShortestPathBFS(graph: Graph, source: NodeId): Map<NodeId, ShortestPathResult> {
+    if (!graph.hasNode(source)) {
+        throw new Error(`Source node ${String(source)} not found in graph`);
+    }
+
+    // Use optimized implementation for large graphs
+    if (graph.nodeCount > 10000) {
+        return singleSourceShortestPathBFSOptimized(graph, source);
+    }
+
+    // Standard implementation
+    return singleSourceShortestPathBFSStandard(graph, source);
+}
+
+/**
+ * Standard single-source shortest paths
+ * @param graph - The input graph to search
+ * @param source - The source node ID to compute shortest paths from
+ * @returns Map of node IDs to their shortest path results
+ */
+function singleSourceShortestPathBFSStandard(graph: Graph, source: NodeId): Map<NodeId, ShortestPathResult> {
+    const results = new Map<NodeId, ShortestPathResult>();
+    const visited = new Set<NodeId>();
+    const queue: { node: NodeId; distance: number }[] = [];
+    const predecessor = new Map<NodeId, NodeId | null>();
+    const distances = new Map<NodeId, number>();
+
+    // Initialize BFS
+    queue.push({ node: source, distance: 0 });
+    visited.add(source);
+    predecessor.set(source, null);
+    distances.set(source, 0);
+
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current) {
+            break;
+        }
+
+        // Explore neighbors
+        for (const neighbor of graph.neighbors(current.node)) {
+            if (!visited.has(neighbor)) {
+                visited.add(neighbor);
+                predecessor.set(neighbor, current.node);
+                distances.set(neighbor, current.distance + 1);
+                queue.push({ node: neighbor, distance: current.distance + 1 });
+            }
+        }
+    }
+
+    // Build results after BFS completes
+    // This avoids copying the predecessor map for each node
+    for (const [node, distance] of distances) {
+        const path = reconstructPath(node, predecessor);
+        results.set(node, {
+            distance,
+            path,
+            predecessor, // Share the same predecessor map
+        });
+    }
+
+    return results;
+}
+
+/**
+ * Optimized single-source shortest paths
+ * @param graph - The input graph to search
+ * @param source - The source node ID to compute shortest paths from
+ * @returns Map of node IDs to their shortest path results
+ */
+function singleSourceShortestPathBFSOptimized(graph: Graph, source: NodeId): Map<NodeId, ShortestPathResult> {
+    const csrGraph = getCSRGraph(graph);
+
+    const dobfs = new DirectionOptimizedBFS(csrGraph, {
+        alpha: 15.0,
+        beta: 20.0,
+    });
+
+    const bfsResult = dobfs.search(source);
+
+    // Convert to expected format
+    const results = new Map<NodeId, ShortestPathResult>();
+
+    for (const [nodeId, distance] of bfsResult.distances) {
+        // Reconstruct path for each node
+        const path = reconstructPath(nodeId, bfsResult.parents);
+
+        results.set(nodeId, {
+            distance,
+            path,
+            predecessor: bfsResult.parents, // Share the same predecessor map
+        });
+    }
+
+    return results;
+}
+
+/**
+ * Check if the graph is bipartite using BFS coloring
+ *
+ * Note: This function does not use Direction-Optimized BFS as the
+ * coloring logic is specific and doesn't benefit from the optimization.
+ * @param graph - The undirected graph to check
+ * @returns True if the graph is bipartite, false otherwise
+ */
+export function isBipartite(graph: Graph): boolean {
+    if (graph.isDirected) {
+        throw new Error("Bipartite test requires an undirected graph");
+    }
+
+    const color = new Map<NodeId, 0 | 1>();
+    const visited = new Set<NodeId>();
+
+    // Check each connected component
+    for (const node of Array.from(graph.nodes())) {
+        if (!visited.has(node.id)) {
+            const queue: NodeId[] = [node.id];
+            color.set(node.id, 0);
+            visited.add(node.id);
+
+            while (queue.length > 0) {
+                const current = queue.shift();
+                if (!current) {
+                    break;
+                }
+
+                const currentColor = color.get(current);
+                if (currentColor === undefined) {
+                    continue;
+                }
+
+                for (const neighbor of Array.from(graph.neighbors(current))) {
+                    if (!visited.has(neighbor)) {
+                        // Color with opposite color
+                        color.set(neighbor, currentColor === 0 ? 1 : 0);
+                        visited.add(neighbor);
+                        queue.push(neighbor);
+                    } else if (color.get(neighbor) === currentColor) {
+                        // Same color as current node - not bipartite
+                        return false;
+                    }
+                }
+            }
+        }
+    }
+
+    return true;
+}