@graphty/algorithms 1.0.1

package/src/algorithms/components/connected.ts

@@ -0,0 +1,298 @@
+import type {Graph} from "../../core/graph.js";
+import {UnionFind} from "../../data-structures/union-find.js";
+import type {NodeId} from "../../types/index.js";
+
+/**
+ * Connected components algorithms
+ *
+ * Finds connected components in undirected graphs and strongly connected
+ * components in directed graphs using various efficient algorithms.
+ */
+
+/**
+ * Find connected components in an undirected graph using Union-Find
+ */
+export function connectedComponents(graph: Graph): NodeId[][] {
+    if (graph.isDirected) {
+        throw new Error("Connected components algorithm requires an undirected graph. Use stronglyConnectedComponents for directed graphs.");
+    }
+
+    const nodes = Array.from(graph.nodes()).map((node) => node.id);
+
+    if (nodes.length === 0) {
+        return [];
+    }
+
+    const unionFind = new UnionFind(nodes);
+
+    // Union connected nodes
+    for (const edge of graph.edges()) {
+        unionFind.union(edge.source, edge.target);
+    }
+
+    return unionFind.getAllComponents();
+}
+
+/**
+ * Find connected components using DFS (alternative implementation)
+ */
+export function connectedComponentsDFS(graph: Graph): NodeId[][] {
+    if (graph.isDirected) {
+        throw new Error("Connected components algorithm requires an undirected graph");
+    }
+
+    const visited = new Set<NodeId>();
+    const components: NodeId[][] = [];
+
+    for (const node of graph.nodes()) {
+        if (!visited.has(node.id)) {
+            const component: NodeId[] = [];
+            dfsComponent(graph, node.id, visited, component);
+            components.push(component);
+        }
+    }
+
+    return components;
+}
+
+/**
+ * DFS helper for connected components
+ */
+function dfsComponent(
+    graph: Graph,
+    nodeId: NodeId,
+    visited: Set<NodeId>,
+    component: NodeId[],
+): void {
+    visited.add(nodeId);
+    component.push(nodeId);
+
+    for (const neighbor of graph.neighbors(nodeId)) {
+        if (!visited.has(neighbor)) {
+            dfsComponent(graph, neighbor, visited, component);
+        }
+    }
+}
+
+/**
+ * Find the number of connected components
+ */
+export function numberOfConnectedComponents(graph: Graph): number {
+    return connectedComponents(graph).length;
+}
+
+/**
+ * Check if the graph is connected (has exactly one connected component)
+ */
+export function isConnected(graph: Graph): boolean {
+    return numberOfConnectedComponents(graph) <= 1;
+}
+
+/**
+ * Find the largest connected component
+ */
+export function largestConnectedComponent(graph: Graph): NodeId[] {
+    const components = connectedComponents(graph);
+
+    if (components.length === 0) {
+        return [];
+    }
+
+    return components.reduce((largest, current) =>
+        current.length > largest.length ? current : largest,
+    );
+}
+
+/**
+ * Get the connected component containing a specific node
+ */
+export function getConnectedComponent(graph: Graph, nodeId: NodeId): NodeId[] {
+    if (!graph.hasNode(nodeId)) {
+        throw new Error(`Node ${String(nodeId)} not found in graph`);
+    }
+
+    if (graph.isDirected) {
+        throw new Error("Connected components algorithm requires an undirected graph");
+    }
+
+    const visited = new Set<NodeId>();
+    const component: NodeId[] = [];
+
+    dfsComponent(graph, nodeId, visited, component);
+
+    return component;
+}
+
+/**
+ * Find strongly connected components using Tarjan's algorithm
+ */
+export function stronglyConnectedComponents(graph: Graph): NodeId[][] {
+    if (!graph.isDirected) {
+        throw new Error("Strongly connected components require a directed graph");
+    }
+
+    const nodes = Array.from(graph.nodes()).map((node) => node.id);
+    const components: NodeId[][] = [];
+    const indices = new Map<NodeId, number>();
+    const lowLinks = new Map<NodeId, number>();
+    const onStack = new Set<NodeId>();
+    const stack: NodeId[] = [];
+    let index = 0;
+
+    function tarjanSCC(nodeId: NodeId): void {
+        // Set the depth index for this node
+        indices.set(nodeId, index);
+        lowLinks.set(nodeId, index);
+        index++;
+        stack.push(nodeId);
+        onStack.add(nodeId);
+
+        // Consider successors
+        for (const neighbor of graph.neighbors(nodeId)) {
+            if (!indices.has(neighbor)) {
+                // Successor has not yet been visited; recurse on it
+                tarjanSCC(neighbor);
+                const nodeLL = lowLinks.get(nodeId) ?? 0;
+                const neighborLL = lowLinks.get(neighbor) ?? 0;
+                lowLinks.set(nodeId, Math.min(nodeLL, neighborLL));
+            } else if (onStack.has(neighbor)) {
+                // Successor is in stack and hence in the current SCC
+                const nodeLL = lowLinks.get(nodeId) ?? 0;
+                const neighborIndex = indices.get(neighbor) ?? 0;
+                lowLinks.set(nodeId, Math.min(nodeLL, neighborIndex));
+            }
+        }
+
+        // If nodeId is a root node, pop the stack and create an SCC
+        const nodeIndex = indices.get(nodeId) ?? 0;
+        const nodeLowLink = lowLinks.get(nodeId) ?? 0;
+
+        if (nodeLowLink === nodeIndex) {
+            const component: NodeId[] = [];
+            let w: NodeId;
+
+            do {
+                const popped = stack.pop();
+                if (popped === undefined) {
+                    break;
+                }
+
+                w = popped;
+
+                onStack.delete(w);
+                component.push(w);
+            } while (w !== nodeId);
+
+            components.push(component);
+        }
+    }
+
+    for (const nodeId of nodes) {
+        if (!indices.has(nodeId)) {
+            tarjanSCC(nodeId);
+        }
+    }
+
+    return components;
+}
+
+/**
+ * Check if a directed graph is strongly connected
+ */
+export function isStronglyConnected(graph: Graph): boolean {
+    if (!graph.isDirected) {
+        throw new Error("Strong connectivity check requires a directed graph");
+    }
+
+    const components = stronglyConnectedComponents(graph);
+    return components.length <= 1;
+}
+
+/**
+ * Find weakly connected components in a directed graph
+ * (treat the graph as undirected for connectivity)
+ */
+export function weaklyConnectedComponents(graph: Graph): NodeId[][] {
+    if (!graph.isDirected) {
+        throw new Error("Weakly connected components are for directed graphs. Use connectedComponents for undirected graphs.");
+    }
+
+    const nodes = Array.from(graph.nodes()).map((node) => node.id);
+
+    if (nodes.length === 0) {
+        return [];
+    }
+
+    const unionFind = new UnionFind(nodes);
+
+    // Union nodes connected by edges (ignore direction)
+    for (const edge of graph.edges()) {
+        unionFind.union(edge.source, edge.target);
+    }
+
+    return unionFind.getAllComponents();
+}
+
+/**
+ * Check if a directed graph is weakly connected
+ */
+export function isWeaklyConnected(graph: Graph): boolean {
+    if (!graph.isDirected) {
+        throw new Error("Weak connectivity check requires a directed graph");
+    }
+
+    return weaklyConnectedComponents(graph).length <= 1;
+}
+
+/**
+ * Find condensation graph (quotient graph of strongly connected components)
+ */
+export function condensationGraph(graph: Graph): {
+    condensedGraph: Graph;
+    componentMap: Map<NodeId, number>;
+    components: NodeId[][];
+} {
+    if (!graph.isDirected) {
+        throw new Error("Condensation graph requires a directed graph");
+    }
+
+    const components = stronglyConnectedComponents(graph);
+    const componentMap = new Map<NodeId, number>();
+    const condensedGraph = new (graph.constructor as new (config: {directed: boolean}) => Graph)({directed: true});
+
+    // Map each node to its component index
+    for (let i = 0; i < components.length; i++) {
+        const component = components[i];
+        if (component) {
+            for (const nodeId of component) {
+                componentMap.set(nodeId, i);
+            }
+            // Add component as a node in condensed graph
+            condensedGraph.addNode(i);
+        }
+    }
+
+    // Add edges between components
+    const addedEdges = new Set<string>();
+
+    for (const edge of graph.edges()) {
+        const sourceComponent = componentMap.get(edge.source);
+        const targetComponent = componentMap.get(edge.target);
+
+        if (sourceComponent !== undefined && targetComponent !== undefined &&
+            sourceComponent !== targetComponent) {
+            const edgeKey = `${sourceComponent}-${targetComponent}`;
+
+            if (!addedEdges.has(edgeKey)) {
+                condensedGraph.addEdge(sourceComponent, targetComponent);
+                addedEdges.add(edgeKey);
+            }
+        }
+    }
+
+    return {
+        condensedGraph,
+        componentMap,
+        components,
+    };
+}

package/src/algorithms/components/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Connected components algorithms
+ */
+
+export {
+    condensationGraph,
+    connectedComponents,
+    connectedComponentsDFS,
+    getConnectedComponent,
+    isConnected,
+    isStronglyConnected,
+    isWeaklyConnected,
+    largestConnectedComponent,
+    numberOfConnectedComponents,
+    stronglyConnectedComponents,
+    weaklyConnectedComponents,
+} from "./connected.js";

package/src/algorithms/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Graph algorithms collection
+ */
+
+// Traversal algorithms
+export * from "./traversal/index.js";
+
+// Shortest path algorithms
+export * from "./shortest-path/index.js";
+
+// Centrality algorithms
+export * from "./centrality/index.js";
+
+// Connected components algorithms
+export * from "./components/index.js";

package/src/algorithms/shortest-path/bellman-ford.ts

@@ -0,0 +1,214 @@
+import type {Graph} from "../../core/graph.js";
+import type {NodeId, ShortestPathResult} from "../../types/index.js";
+
+/**
+ * Bellman-Ford algorithm implementation for single-source shortest paths
+ *
+ * Finds shortest paths from a source node to all other nodes in a weighted graph.
+ * Unlike Dijkstra's algorithm, it can handle negative edge weights and detect
+ * negative cycles.
+ */
+
+/**
+ * Bellman-Ford algorithm options
+ */
+export interface BellmanFordOptions {
+    /**
+     * Target node for early termination (optional)
+     */
+    target?: NodeId;
+}
+
+/**
+ * Result of Bellman-Ford algorithm
+ */
+export interface BellmanFordResult {
+    /**
+     * Distance from source to each reachable node
+     */
+    distances: Map<NodeId, number>;
+    /**
+     * Predecessor of each node in shortest path tree
+     */
+    predecessors: Map<NodeId, NodeId | null>;
+    /**
+     * Whether a negative cycle was detected
+     */
+    hasNegativeCycle: boolean;
+    /**
+     * Nodes involved in negative cycle (if any)
+     */
+    negativeCycleNodes: NodeId[];
+}
+
+/**
+ * Find shortest paths from source using Bellman-Ford algorithm
+ */
+export function bellmanFord(
+    graph: Graph,
+    source: NodeId,
+    options: BellmanFordOptions = {},
+): BellmanFordResult {
+    if (!graph.hasNode(source)) {
+        throw new Error(`Source node ${String(source)} not found in graph`);
+    }
+
+    const distances = new Map<NodeId, number>();
+    const predecessors = new Map<NodeId, NodeId | null>();
+    const nodes = Array.from(graph.nodes()).map((node) => node.id);
+
+    // Initialize distances
+    for (const nodeId of nodes) {
+        distances.set(nodeId, nodeId === source ? 0 : Infinity);
+        predecessors.set(nodeId, null);
+    }
+
+    // Relax edges |V| - 1 times
+    for (let i = 0; i < nodes.length - 1; i++) {
+        let updated = false;
+
+        for (const edge of graph.edges()) {
+            const u = edge.source;
+            const v = edge.target;
+            const weight = edge.weight ?? 1;
+
+            const distanceU = distances.get(u);
+            const distanceV = distances.get(v);
+
+            if (distanceU !== undefined && distanceV !== undefined && distanceU !== Infinity) {
+                const newDistance = distanceU + weight;
+
+                if (newDistance < distanceV) {
+                    distances.set(v, newDistance);
+                    predecessors.set(v, u);
+                    updated = true;
+
+                    // Early termination if target reached
+                    if (options.target && v === options.target) {
+                        break;
+                    }
+                }
+            }
+        }
+
+        // If no update in this iteration, we can stop early
+        if (!updated) {
+            break;
+        }
+    }
+
+    // Check for negative cycles
+    const negativeCycleNodes: NodeId[] = [];
+    let hasNegativeCycle = false;
+
+    for (const edge of graph.edges()) {
+        const u = edge.source;
+        const v = edge.target;
+        const weight = edge.weight ?? 1;
+
+        const distanceU = distances.get(u);
+        const distanceV = distances.get(v);
+
+        if (distanceU !== undefined && distanceV !== undefined && distanceU !== Infinity) {
+            const newDistance = distanceU + weight;
+
+            if (newDistance < distanceV) {
+                hasNegativeCycle = true;
+                negativeCycleNodes.push(v);
+            }
+        }
+    }
+
+    return {
+        distances,
+        predecessors,
+        hasNegativeCycle,
+        negativeCycleNodes,
+    };
+}
+
+/**
+ * Find shortest path between two specific nodes using Bellman-Ford
+ */
+export function bellmanFordPath(
+    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`);
+    }
+
+    const result = bellmanFord(graph, source, {target});
+
+    if (result.hasNegativeCycle) {
+        throw new Error("Graph contains a negative cycle");
+    }
+
+    const distance = result.distances.get(target);
+
+    if (distance === undefined || distance === Infinity) {
+        return null; // No path exists
+    }
+
+    // Reconstruct path
+    const path = reconstructPath(target, result.predecessors);
+
+    return {
+        distance,
+        path,
+        predecessor: result.predecessors,
+    };
+}
+
+/**
+ * Check if graph has negative cycles using Bellman-Ford
+ */
+export function hasNegativeCycle(graph: Graph): boolean {
+    const nodes = Array.from(graph.nodes());
+
+    if (nodes.length === 0) {
+        return false;
+    }
+
+    // Need to check from multiple sources in case of disconnected components
+    const checked = new Set<NodeId>();
+
+    for (const node of nodes) {
+        if (!checked.has(node.id)) {
+            const result = bellmanFord(graph, node.id);
+
+            if (result.hasNegativeCycle) {
+                return true;
+            }
+
+            // Mark all reachable nodes as checked
+            for (const [nodeId, distance] of result.distances) {
+                if (distance !== Infinity) {
+                    checked.add(nodeId);
+                }
+            }
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Reconstruct path from predecessor map
+ */
+function reconstructPath(target: NodeId, predecessors: Map<NodeId, NodeId | null>): NodeId[] {
+    const path: NodeId[] = [];
+    let current: NodeId | null = target;
+
+    while (current !== null) {
+        path.unshift(current);
+        current = predecessors.get(current) ?? null;
+    }
+
+    return path;
+}