@graphty/algorithms 1.2.0 → 1.4.2

package/src/algorithms/traversal/bfs.ts

@@ -1,236 +1,12 @@
-import type {Graph} from "../../core/graph.js";
-import type {NodeId, ShortestPathResult, TraversalOptions, TraversalResult} from "../../types/index.js";
-
 /**
  * Breadth-First Search (BFS) implementation
  *
  * Explores graph level by level from a starting node. Guarantees shortest path
  * in unweighted graphs and can be used for various graph analysis tasks.
+ *
+ * Automatically uses optimized implementations for large graphs (>10k nodes)
+ * to provide the best performance without requiring manual configuration.
  */
 
-/**
- * Perform breadth-first search starting from a given node
- */
-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`);
-    }
-
-    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};
-}
-
-/**
- * Find shortest path between two nodes in an unweighted graph using BFS
- */
-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]]),
-        };
-    }
-
-    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;
-}
-
-/**
- * Find shortest paths from source to all reachable nodes using BFS
- */
-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`);
-    }
-
-    const results = new Map<NodeId, ShortestPathResult>();
-    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;
-        }
-
-        // Store result for current node
-        const path = reconstructPath(current.node, predecessor);
-        results.set(current.node, {
-            distance: current.distance,
-            path,
-            predecessor: new Map(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});
-            }
-        }
-    }
-
-    return results;
-}
-
-/**
- * Check if the graph is bipartite using BFS coloring
- */
-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;
-}
-
-/**
- * Reconstruct path from predecessor map
- */
-function reconstructPath(target: NodeId, predecessor: Map<NodeId, NodeId | null>): NodeId[] {
-    const path: NodeId[] = [];
-    let current: NodeId | null = target;
-
-    while (current !== null) {
-        path.unshift(current);
-        current = predecessor.get(current) ?? null;
-    }
-
-    return path;
-}
+// Re-export unified implementations that automatically optimize for large graphs
+export { breadthFirstSearch, isBipartite, shortestPathBFS, singleSourceShortestPathBFS } from "./bfs-unified.js";

package/src/algorithms/traversal/dfs.ts

@@ -1,5 +1,5 @@
-import {Graph} from "../../core/graph.js";
-import type {NodeId, TraversalOptions, TraversalResult} from "../../types/index.js";
+import { Graph } from "../../core/graph.js";
+import type { NodeId, TraversalOptions, TraversalResult } from "../../types/index.js";
 
 /**
  * Depth-First Search (DFS) implementation
@@ -18,12 +18,12 @@ export interface DFSOptions extends TraversalOptions {
 
 /**
  * Perform depth-first search starting from a given node
+ * @param graph - The input graph to traverse
+ * @param startNode - The node to start the DFS from
+ * @param options - DFS options (recursive mode, pre/post order, etc.)
+ * @returns Traversal result with visited nodes, order, and tree structure
  */
-export function depthFirstSearch(
-    graph: Graph,
-    startNode: NodeId,
-    options: DFSOptions = {},
-): TraversalResult {
+export function depthFirstSearch(graph: Graph, startNode: NodeId, options: DFSOptions = {}): TraversalResult {
     if (!graph.hasNode(startNode)) {
         throw new Error(`Start node ${String(startNode)} not found in graph`);
     }
@@ -38,11 +38,17 @@ export function depthFirstSearch(
         dfsIterative(graph, startNode, visited, order, tree, options);
     }
 
-    return {visited, order, tree};
+    return { visited, order, tree };
 }
 
 /**
  * Iterative DFS implementation (safer for browsers)
+ * @param graph - The input graph to traverse
+ * @param startNode - The node to start the DFS from
+ * @param visited - Set to track visited nodes
+ * @param order - Array to store traversal order
+ * @param tree - Map to store parent relationships
+ * @param options - DFS options (recursive mode, pre/post order, etc.)
  */
 function dfsIterative(
     graph: Graph,
@@ -58,8 +64,8 @@ function dfsIterative(
         return;
     }
 
-    const stack: {node: NodeId, parent: NodeId | null, depth: number}[] = [];
-    stack.push({node: startNode, parent: null, depth: 0});
+    const stack: { node: NodeId; parent: NodeId | null; depth: number }[] = [];
+    stack.push({ node: startNode, parent: null, depth: 0 });
 
     while (stack.length > 0) {
         const current = stack.pop();
@@ -89,7 +95,7 @@ function dfsIterative(
             for (let i = neighbors.length - 1; i >= 0; i--) {
                 const neighbor = neighbors[i];
                 if (neighbor !== undefined && !visited.has(neighbor)) {
-                    stack.push({node: neighbor, parent: current.node, depth: current.depth + 1});
+                    stack.push({ node: neighbor, parent: current.node, depth: current.depth + 1 });
                 }
             }
         }
@@ -98,6 +104,14 @@ function dfsIterative(
 
 /**
  * Recursive DFS implementation
+ * @param graph - The input graph to traverse
+ * @param node - Current node being visited
+ * @param visited - Set to track visited nodes
+ * @param order - Array to store traversal order
+ * @param tree - Map to store parent relationships
+ * @param options - DFS options (recursive mode, pre/post order, etc.)
+ * @param depth - Current depth in the traversal tree
+ * @param parent - Parent node of the current node
  */
 function dfsRecursive(
     graph: Graph,
@@ -145,6 +159,8 @@ function dfsRecursive(
 
 /**
  * Detect cycles in a graph using DFS
+ * @param graph - The input graph to check for cycles
+ * @returns True if the graph contains a cycle, false otherwise
  */
 export function hasCycleDFS(graph: Graph): boolean {
     const visited = new Set<NodeId>();
@@ -170,13 +186,13 @@ export function hasCycleDFS(graph: Graph): boolean {
 
 /**
  * Utility function for cycle detection in directed graphs
+ * @param graph - The directed graph to check
+ * @param node - Current node being visited
+ * @param visited - Set of all visited nodes
+ * @param recursionStack - Set of nodes in the current recursion path
+ * @returns True if a cycle is found, false otherwise
  */
-function hasCycleUtilDirected(
-    graph: Graph,
-    node: NodeId,
-    visited: Set<NodeId>,
-    recursionStack: Set<NodeId>,
-): boolean {
+function hasCycleUtilDirected(graph: Graph, node: NodeId, visited: Set<NodeId>, recursionStack: Set<NodeId>): boolean {
     visited.add(node);
     recursionStack.add(node);
 
@@ -198,13 +214,13 @@ function hasCycleUtilDirected(
 
 /**
  * Utility function for cycle detection in undirected graphs
+ * @param graph - The undirected graph to check
+ * @param node - Current node being visited
+ * @param visited - Set of all visited nodes
+ * @param parent - Parent node of the current node
+ * @returns True if a cycle is found, false otherwise
  */
-function hasCycleUtilUndirected(
-    graph: Graph,
-    node: NodeId,
-    visited: Set<NodeId>,
-    parent: NodeId | null,
-): boolean {
+function hasCycleUtilUndirected(graph: Graph, node: NodeId, visited: Set<NodeId>, parent: NodeId | null): boolean {
     visited.add(node);
 
     // Check all neighbors
@@ -224,6 +240,8 @@ function hasCycleUtilUndirected(
 
 /**
  * Topological sorting using DFS (for directed acyclic graphs)
+ * @param graph - The directed acyclic graph to sort
+ * @returns Array of node IDs in topological order, or null if graph has cycles
  */
 export function topologicalSort(graph: Graph): NodeId[] | null {
     if (!graph.isDirected) {
@@ -251,13 +269,12 @@ export function topologicalSort(graph: Graph): NodeId[] | null {
 
 /**
  * Utility function for topological sorting
+ * @param graph - The directed graph being sorted
+ * @param node - Current node being visited
+ * @param visited - Set of visited nodes
+ * @param stack - Stack to store nodes in reverse topological order
  */
-function topologicalSortUtil(
-    graph: Graph,
-    node: NodeId,
-    visited: Set<NodeId>,
-    stack: NodeId[],
-): void {
+function topologicalSortUtil(graph: Graph, node: NodeId, visited: Set<NodeId>, stack: NodeId[]): void {
     visited.add(node);
 
     // Visit all neighbors first
@@ -273,6 +290,8 @@ function topologicalSortUtil(
 
 /**
  * Find strongly connected components using DFS (for directed graphs)
+ * @param graph - The directed graph to analyze
+ * @returns Array of strongly connected components (each is an array of node IDs)
  */
 export function findStronglyConnectedComponents(graph: Graph): NodeId[][] {
     if (!graph.isDirected) {
@@ -310,13 +329,12 @@ export function findStronglyConnectedComponents(graph: Graph): NodeId[][] {
 
 /**
  * DFS to record finish order
+ * @param graph - The graph being traversed
+ * @param node - Current node being visited
+ * @param visited - Set of visited nodes
+ * @param finishOrder - Array to store nodes in order of completion
  */
-function dfsFinishOrder(
-    graph: Graph,
-    node: NodeId,
-    visited: Set<NodeId>,
-    finishOrder: NodeId[],
-): void {
+function dfsFinishOrder(graph: Graph, node: NodeId, visited: Set<NodeId>, finishOrder: NodeId[]): void {
     visited.add(node);
 
     for (const neighbor of Array.from(graph.neighbors(node))) {
@@ -330,13 +348,12 @@ function dfsFinishOrder(
 
 /**
  * DFS to collect nodes in a component
+ * @param graph - The graph being traversed
+ * @param node - Current node being visited
+ * @param visited - Set of visited nodes
+ * @param component - Array to collect nodes in the current component
  */
-function dfsCollectComponent(
-    graph: Graph,
-    node: NodeId,
-    visited: Set<NodeId>,
-    component: NodeId[],
-): void {
+function dfsCollectComponent(graph: Graph, node: NodeId, visited: Set<NodeId>, component: NodeId[]): void {
     visited.add(node);
     component.push(node);
 
@@ -349,9 +366,11 @@ function dfsCollectComponent(
 
 /**
  * Create transpose (reverse) of a directed graph
+ * @param graph - The directed graph to transpose
+ * @returns A new graph with all edges reversed
  */
 function createTransposeGraph(graph: Graph): Graph {
-    const transpose = new Graph({directed: true});
+    const transpose = new Graph({ directed: true });
 
     // Add all nodes
     for (const node of Array.from(graph.nodes())) {

package/src/algorithms/traversal/index.ts

@@ -2,6 +2,6 @@
  * Graph traversal algorithms
  */
 
-export {breadthFirstSearch, isBipartite, shortestPathBFS, singleSourceShortestPathBFS} from "./bfs.js";
-export type {DFSOptions} from "./dfs.js";
-export {depthFirstSearch, findStronglyConnectedComponents, hasCycleDFS, topologicalSort} from "./dfs.js";
+export { breadthFirstSearch, isBipartite, shortestPathBFS, singleSourceShortestPathBFS } from "./bfs.js";
+export type { DFSOptions } from "./dfs.js";
+export { depthFirstSearch, findStronglyConnectedComponents, hasCycleDFS, topologicalSort } from "./dfs.js";