@graphty/algorithms 1.0.1

package/src/algorithms/traversal/dfs.ts

@@ -0,0 +1,367 @@
+import {Graph} from "../../core/graph.js";
+import type {NodeId, TraversalOptions, TraversalResult} from "../../types/index.js";
+
+/**
+ * Depth-First Search (DFS) implementation
+ *
+ * Explores graph by going as deep as possible before backtracking.
+ * Useful for cycle detection, topological sorting, and connectivity analysis.
+ */
+
+/**
+ * DFS traversal options
+ */
+export interface DFSOptions extends TraversalOptions {
+    recursive?: boolean; // Use recursive implementation (default: false for browser safety)
+    preOrder?: boolean; // Visit nodes in pre-order (default: true)
+}
+
+/**
+ * Perform depth-first search starting from a given node
+ */
+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`);
+    }
+
+    const visited = new Set<NodeId>();
+    const order: NodeId[] = [];
+    const tree = new Map<NodeId, NodeId | null>();
+
+    if (options.recursive) {
+        dfsRecursive(graph, startNode, visited, order, tree, options, 0);
+    } else {
+        dfsIterative(graph, startNode, visited, order, tree, options);
+    }
+
+    return {visited, order, tree};
+}
+
+/**
+ * Iterative DFS implementation (safer for browsers)
+ */
+function dfsIterative(
+    graph: Graph,
+    startNode: NodeId,
+    visited: Set<NodeId>,
+    order: NodeId[],
+    tree: Map<NodeId, NodeId | null>,
+    options: DFSOptions,
+): void {
+    if (options.preOrder === false) {
+        // For post-order, use a simpler recursive approach to ensure correctness
+        dfsRecursive(graph, startNode, visited, order, tree, options, 0, null);
+        return;
+    }
+
+    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();
+        if (!current) {
+            break;
+        }
+
+        if (!visited.has(current.node)) {
+            visited.add(current.node);
+            tree.set(current.node, current.parent);
+
+            // Pre-order processing
+            order.push(current.node);
+
+            // Call visitor callback if provided
+            if (options.visitCallback) {
+                options.visitCallback(current.node, current.depth);
+            }
+
+            // Early termination if target found
+            if (options.targetNode && current.node === options.targetNode) {
+                break;
+            }
+
+            // Add neighbors to stack in reverse order to maintain left-to-right traversal
+            const neighbors = Array.from(graph.neighbors(current.node));
+            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});
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Recursive DFS implementation
+ */
+function dfsRecursive(
+    graph: Graph,
+    node: NodeId,
+    visited: Set<NodeId>,
+    order: NodeId[],
+    tree: Map<NodeId, NodeId | null>,
+    options: DFSOptions,
+    depth: number,
+    parent: NodeId | null = null,
+): void {
+    visited.add(node);
+    tree.set(node, parent);
+
+    // Pre-order processing
+    if (options.preOrder !== false) {
+        order.push(node);
+
+        if (options.visitCallback) {
+            options.visitCallback(node, depth);
+        }
+
+        // Early termination if target found
+        if (options.targetNode && node === options.targetNode) {
+            return;
+        }
+    }
+
+    // Recursively visit neighbors
+    for (const neighbor of graph.neighbors(node)) {
+        if (!visited.has(neighbor)) {
+            dfsRecursive(graph, neighbor, visited, order, tree, options, depth + 1, node);
+        }
+    }
+
+    // Post-order processing
+    if (options.preOrder === false) {
+        order.push(node);
+
+        if (options.visitCallback) {
+            options.visitCallback(node, depth);
+        }
+    }
+}
+
+/**
+ * Detect cycles in a graph using DFS
+ */
+export function hasCycleDFS(graph: Graph): boolean {
+    const visited = new Set<NodeId>();
+
+    // Check each unvisited node for cycles
+    for (const node of graph.nodes()) {
+        if (!visited.has(node.id)) {
+            if (graph.isDirected) {
+                const recursionStack = new Set<NodeId>();
+                if (hasCycleUtilDirected(graph, node.id, visited, recursionStack)) {
+                    return true;
+                }
+            } else {
+                if (hasCycleUtilUndirected(graph, node.id, visited, null)) {
+                    return true;
+                }
+            }
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Utility function for cycle detection in directed graphs
+ */
+function hasCycleUtilDirected(
+    graph: Graph,
+    node: NodeId,
+    visited: Set<NodeId>,
+    recursionStack: Set<NodeId>,
+): boolean {
+    visited.add(node);
+    recursionStack.add(node);
+
+    // Check all neighbors
+    for (const neighbor of graph.neighbors(node)) {
+        if (!visited.has(neighbor)) {
+            if (hasCycleUtilDirected(graph, neighbor, visited, recursionStack)) {
+                return true;
+            }
+        } else if (recursionStack.has(neighbor)) {
+            // Back edge found - cycle detected
+            return true;
+        }
+    }
+
+    recursionStack.delete(node);
+    return false;
+}
+
+/**
+ * Utility function for cycle detection in undirected graphs
+ */
+function hasCycleUtilUndirected(
+    graph: Graph,
+    node: NodeId,
+    visited: Set<NodeId>,
+    parent: NodeId | null,
+): boolean {
+    visited.add(node);
+
+    // Check all neighbors
+    for (const neighbor of graph.neighbors(node)) {
+        if (!visited.has(neighbor)) {
+            if (hasCycleUtilUndirected(graph, neighbor, visited, node)) {
+                return true;
+            }
+        } else if (neighbor !== parent) {
+            // Found a visited node that's not the parent - cycle detected
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Topological sorting using DFS (for directed acyclic graphs)
+ */
+export function topologicalSort(graph: Graph): NodeId[] | null {
+    if (!graph.isDirected) {
+        throw new Error("Topological sort requires a directed graph");
+    }
+
+    // First check if graph has cycles
+    if (hasCycleDFS(graph)) {
+        return null; // Cannot topologically sort a graph with cycles
+    }
+
+    const visited = new Set<NodeId>();
+    const stack: NodeId[] = [];
+
+    // Perform DFS from each unvisited node
+    for (const node of graph.nodes()) {
+        if (!visited.has(node.id)) {
+            topologicalSortUtil(graph, node.id, visited, stack);
+        }
+    }
+
+    // Return nodes in reverse order of finishing times
+    return stack.reverse();
+}
+
+/**
+ * Utility function for topological sorting
+ */
+function topologicalSortUtil(
+    graph: Graph,
+    node: NodeId,
+    visited: Set<NodeId>,
+    stack: NodeId[],
+): void {
+    visited.add(node);
+
+    // Visit all neighbors first
+    for (const neighbor of graph.neighbors(node)) {
+        if (!visited.has(neighbor)) {
+            topologicalSortUtil(graph, neighbor, visited, stack);
+        }
+    }
+
+    // Add current node to stack after visiting all neighbors
+    stack.push(node);
+}
+
+/**
+ * Find strongly connected components using DFS (for directed graphs)
+ */
+export function findStronglyConnectedComponents(graph: Graph): NodeId[][] {
+    if (!graph.isDirected) {
+        throw new Error("Strongly connected components require a directed graph");
+    }
+
+    const visited = new Set<NodeId>();
+    const finishOrder: NodeId[] = [];
+
+    // Step 1: Get nodes in order of finishing times
+    for (const node of graph.nodes()) {
+        if (!visited.has(node.id)) {
+            dfsFinishOrder(graph, node.id, visited, finishOrder);
+        }
+    }
+
+    // Step 2: Create transpose graph (reverse all edges)
+    const transposeGraph = createTransposeGraph(graph);
+
+    // Step 3: DFS on transpose graph in reverse finish order
+    const visited2 = new Set<NodeId>();
+    const components: NodeId[][] = [];
+
+    for (let i = finishOrder.length - 1; i >= 0; i--) {
+        const node = finishOrder[i];
+        if (node !== undefined && !visited2.has(node)) {
+            const component: NodeId[] = [];
+            dfsCollectComponent(transposeGraph, node, visited2, component);
+            components.push(component);
+        }
+    }
+
+    return components;
+}
+
+/**
+ * DFS to record finish order
+ */
+function dfsFinishOrder(
+    graph: Graph,
+    node: NodeId,
+    visited: Set<NodeId>,
+    finishOrder: NodeId[],
+): void {
+    visited.add(node);
+
+    for (const neighbor of graph.neighbors(node)) {
+        if (!visited.has(neighbor)) {
+            dfsFinishOrder(graph, neighbor, visited, finishOrder);
+        }
+    }
+
+    finishOrder.push(node);
+}
+
+/**
+ * DFS to collect nodes in a component
+ */
+function dfsCollectComponent(
+    graph: Graph,
+    node: NodeId,
+    visited: Set<NodeId>,
+    component: NodeId[],
+): void {
+    visited.add(node);
+    component.push(node);
+
+    for (const neighbor of graph.neighbors(node)) {
+        if (!visited.has(neighbor)) {
+            dfsCollectComponent(graph, neighbor, visited, component);
+        }
+    }
+}
+
+/**
+ * Create transpose (reverse) of a directed graph
+ */
+function createTransposeGraph(graph: Graph): Graph {
+    const transpose = new Graph({directed: true});
+
+    // Add all nodes
+    for (const node of graph.nodes()) {
+        transpose.addNode(node.id, node.data);
+    }
+
+    // Add reverse edges
+    for (const edge of graph.edges()) {
+        transpose.addEdge(edge.target, edge.source, edge.weight, edge.data);
+    }
+
+    return transpose;
+}

package/src/algorithms/traversal/index.ts

@@ -0,0 +1,7 @@
+/**
+ * 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";

package/src/core/graph.ts

@@ -0,0 +1,326 @@
+import type {Edge, GraphConfig, Node, NodeId} from "../types/index.js";
+
+/**
+ * Core Graph data structure for the Graphty Algorithms library
+ *
+ * Provides efficient graph representation with support for both directed and undirected graphs.
+ * Uses adjacency lists for optimal performance with sparse graphs.
+ */
+export class Graph {
+    private nodeMap: Map<NodeId, Node>;
+    private adjacencyList: Map<NodeId, Map<NodeId, Edge>>;
+    private incomingEdges: Map<NodeId, Map<NodeId, Edge>>; // For directed graphs
+    private config: GraphConfig;
+    private edgeCount: number;
+
+    constructor(config: Partial<GraphConfig> = {}) {
+        this.config = {
+            directed: false,
+            allowSelfLoops: true,
+            allowParallelEdges: false,
+            ... config,
+        };
+        this.nodeMap = new Map();
+        this.adjacencyList = new Map();
+        this.incomingEdges = new Map();
+        this.edgeCount = 0;
+    }
+
+    /**
+     * Add a node to the graph
+     */
+    addNode(id: NodeId, data?: Record<string, unknown>): void {
+        if (!this.nodeMap.has(id)) {
+            this.nodeMap.set(id, {id, data});
+            this.adjacencyList.set(id, new Map());
+
+            if (this.config.directed) {
+                this.incomingEdges.set(id, new Map());
+            }
+        }
+    }
+
+    /**
+     * Remove a node from the graph
+     */
+    removeNode(id: NodeId): boolean {
+        if (!this.nodeMap.has(id)) {
+            return false;
+        }
+
+        // Remove all edges connected to this node
+        const outgoingEdges = this.adjacencyList.get(id);
+        if (outgoingEdges) {
+            for (const targetId of outgoingEdges.keys()) {
+                this.removeEdge(id, targetId);
+            }
+        }
+
+        if (this.config.directed) {
+            const incomingEdges = this.incomingEdges.get(id);
+            if (incomingEdges) {
+                for (const sourceId of incomingEdges.keys()) {
+                    this.removeEdge(sourceId, id);
+                }
+            }
+        } else {
+            // For undirected graphs, also remove edges where this node is the target
+            for (const [nodeId, edges] of this.adjacencyList) {
+                if (edges.has(id)) {
+                    this.removeEdge(nodeId, id);
+                }
+            }
+        }
+
+        // Remove the node itself
+        this.nodeMap.delete(id);
+        this.adjacencyList.delete(id);
+
+        if (this.config.directed) {
+            this.incomingEdges.delete(id);
+        }
+
+        return true;
+    }
+
+    /**
+     * Add an edge to the graph
+     */
+    addEdge(source: NodeId, target: NodeId, weight = 1, data?: Record<string, unknown>): void {
+        // Ensure both nodes exist
+        this.addNode(source);
+        this.addNode(target);
+
+        // Check self-loops
+        if (!this.config.allowSelfLoops && source === target) {
+            throw new Error("Self-loops are not allowed in this graph");
+        }
+
+        // Check parallel edges
+        if (!this.config.allowParallelEdges && this.hasEdge(source, target)) {
+            throw new Error("Parallel edges are not allowed in this graph");
+        }
+
+        const edge: Edge = {source, target, weight, data};
+
+        // Add to adjacency list
+        const sourceAdjacency = this.adjacencyList.get(source);
+
+        if (sourceAdjacency) {
+            sourceAdjacency.set(target, edge);
+        }
+
+        if (this.config.directed) {
+            // For directed graphs, add to incoming edges list
+            const targetIncoming = this.incomingEdges.get(target);
+
+            if (targetIncoming) {
+                targetIncoming.set(source, edge);
+            }
+        } else {
+            // For undirected graphs, add the reverse edge
+            if (source !== target) {
+                const reverseEdge: Edge = {source: target, target: source, weight, data};
+                const targetAdjacency = this.adjacencyList.get(target);
+
+                if (targetAdjacency) {
+                    targetAdjacency.set(source, reverseEdge);
+                }
+            }
+        }
+
+        this.edgeCount++;
+    }
+
+    /**
+     * Remove an edge from the graph
+     */
+    removeEdge(source: NodeId, target: NodeId): boolean {
+        const sourceEdges = this.adjacencyList.get(source);
+        if (!sourceEdges?.has(target)) {
+            return false;
+        }
+
+        sourceEdges.delete(target);
+
+        if (this.config.directed) {
+            const targetIncoming = this.incomingEdges.get(target);
+            if (targetIncoming) {
+                targetIncoming.delete(source);
+            }
+        } else {
+            // For undirected graphs, remove the reverse edge
+            const targetEdges = this.adjacencyList.get(target);
+            if (targetEdges) {
+                targetEdges.delete(source);
+            }
+        }
+
+        this.edgeCount--;
+        return true;
+    }
+
+    /**
+     * Check if a node exists in the graph
+     */
+    hasNode(id: NodeId): boolean {
+        return this.nodeMap.has(id);
+    }
+
+    /**
+     * Check if an edge exists in the graph
+     */
+    hasEdge(source: NodeId, target: NodeId): boolean {
+        const sourceEdges = this.adjacencyList.get(source);
+        return sourceEdges ? sourceEdges.has(target) : false;
+    }
+
+    /**
+     * Get a node by ID
+     */
+    getNode(id: NodeId): Node | undefined {
+        return this.nodeMap.get(id);
+    }
+
+    /**
+     * Get an edge by source and target
+     */
+    getEdge(source: NodeId, target: NodeId): Edge | undefined {
+        const sourceEdges = this.adjacencyList.get(source);
+        return sourceEdges ? sourceEdges.get(target) : undefined;
+    }
+
+    /**
+     * Get the number of nodes in the graph
+     */
+    get nodeCount(): number {
+        return this.nodeMap.size;
+    }
+
+    /**
+     * Get the number of edges in the graph
+     */
+    get totalEdgeCount(): number {
+        return this.edgeCount;
+    }
+
+    /**
+     * Check if the graph is directed
+     */
+    get isDirected(): boolean {
+        return this.config.directed;
+    }
+
+    /**
+     * Get all nodes in the graph
+     */
+    nodes(): IterableIterator<Node> {
+        return this.nodeMap.values();
+    }
+
+    /**
+     * Get all edges in the graph
+     */
+    *edges(): IterableIterator<Edge> {
+        for (const [source, edges] of this.adjacencyList) {
+            for (const edge of edges.values()) {
+                // For undirected graphs, only yield each edge once
+                if (!this.config.directed && source > edge.target) {
+                    continue;
+                }
+
+                yield edge;
+            }
+        }
+    }
+
+    /**
+     * Get neighbors of a node (outgoing edges)
+     */
+    neighbors(nodeId: NodeId): IterableIterator<NodeId> {
+        const edges = this.adjacencyList.get(nodeId);
+        return edges ? edges.keys() : new Map().keys();
+    }
+
+    /**
+     * Get incoming neighbors of a node (directed graphs only)
+     */
+    inNeighbors(nodeId: NodeId): IterableIterator<NodeId> {
+        if (!this.config.directed) {
+            return this.neighbors(nodeId);
+        }
+
+        const edges = this.incomingEdges.get(nodeId);
+        return edges ? edges.keys() : new Map().keys();
+    }
+
+    /**
+     * Get outgoing neighbors of a node
+     */
+    outNeighbors(nodeId: NodeId): IterableIterator<NodeId> {
+        return this.neighbors(nodeId);
+    }
+
+    /**
+     * Get the degree of a node
+     */
+    degree(nodeId: NodeId): number {
+        if (this.config.directed) {
+            return this.inDegree(nodeId) + this.outDegree(nodeId);
+        }
+
+        const edges = this.adjacencyList.get(nodeId);
+        return edges ? edges.size : 0;
+    }
+
+    /**
+     * Get the in-degree of a node
+     */
+    inDegree(nodeId: NodeId): number {
+        if (!this.config.directed) {
+            return this.degree(nodeId);
+        }
+
+        const edges = this.incomingEdges.get(nodeId);
+        return edges ? edges.size : 0;
+    }
+
+    /**
+     * Get the out-degree of a node
+     */
+    outDegree(nodeId: NodeId): number {
+        const edges = this.adjacencyList.get(nodeId);
+        return edges ? edges.size : 0;
+    }
+
+    /**
+     * Create a copy of the graph
+     */
+    clone(): Graph {
+        const cloned = new Graph(this.config);
+
+        // Copy nodes
+        for (const node of this.nodeMap.values()) {
+            cloned.addNode(node.id, node.data ? {... node.data} : undefined);
+        }
+
+        // Copy edges
+        for (const edge of this.edges()) {
+            cloned.addEdge(
+                edge.source,
+                edge.target,
+                edge.weight,
+                edge.data ? {... edge.data} : undefined,
+            );
+        }
+
+        return cloned;
+    }
+
+    /**
+     * Get graph configuration
+     */
+    getConfig(): GraphConfig {
+        return {... this.config};
+    }
+}

package/src/data-structures/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Data structures supporting graph algorithms
+ */
+
+export {PriorityQueue} from "./priority-queue.js";
+export {UnionFind} from "./union-find.js";