@graphty/algorithms 1.2.0 → 1.4.2

package/src/research/terahac.ts

@@ -1,5 +1,5 @@
-import type {Graph} from "../core/graph.js";
-import type {NodeId} from "../types/index.js";
+import type { Graph } from "../core/graph.js";
+import type { NodeId } from "../types/index.js";
 
 /**
  * Configuration options for the TeraHAC (Hierarchical Agglomerative Clustering) algorithm
@@ -15,6 +15,8 @@ export interface TeraHACConfig {
     maxNodes?: number;
     /** Use graph structure for distance calculation */
     useGraphDistance?: boolean;
+    /** Custom warning handler (default: console.warn) */
+    onWarning?: (message: string) => void;
 }
 
 /**
@@ -58,7 +60,6 @@ export interface TeraHACResult {
  *
  * Based on: "Scaling Hierarchical Agglomerative Clustering to Trillion-Edge Graphs"
  * Google Research 2024
- *
  * @param graph - Input graph to cluster
  * @param config - Configuration options
  * @returns Hierarchical clustering result
@@ -70,8 +71,14 @@ export function teraHAC(graph: Graph, config: TeraHACConfig = {}): TeraHACResult
         distanceThreshold,
         maxNodes = 10000,
         useGraphDistance = true,
+        onWarning = console.warn,
     } = config;
 
+    // Input validation
+    if (numClusters !== undefined && (numClusters < 1 || !Number.isInteger(numClusters))) {
+        throw new Error("numClusters must be a positive integer");
+    }
+
     const nodes = Array.from(graph.nodes());
     const nodeCount = nodes.length;
 
@@ -80,7 +87,9 @@ export function teraHAC(graph: Graph, config: TeraHACConfig = {}): TeraHACResult
     }
 
     if (nodeCount > maxNodes) {
-        console.warn(`Graph has ${String(nodeCount)} nodes, which exceeds maxNodes (${String(maxNodes)}). Performance may be degraded.`);
+        onWarning(
+            `Graph has ${String(nodeCount)} nodes, which exceeds maxNodes (${String(maxNodes)}). Performance may be degraded.`,
+        );
     }
 
     // Initialize each node as its own cluster
@@ -112,9 +121,9 @@ export function teraHAC(graph: Graph, config: TeraHACConfig = {}): TeraHACResult
     let dendrogram: ClusterNode | undefined;
 
     // Perform agglomerative clustering
-    while (clusters.size > 1) {
+    while (clusters.size > 1 && mergeCandidates.length > 0) {
         // Find closest pair of clusters
-        const {cluster1Id, cluster2Id, distance} = findClosestPair(mergeCandidates);
+        const { cluster1Id, cluster2Id, distance } = findClosestPair(mergeCandidates);
 
         // Check stopping criteria
         if (numClusters && clusters.size <= numClusters) {
@@ -134,7 +143,7 @@ export function teraHAC(graph: Graph, config: TeraHACConfig = {}): TeraHACResult
 
         // Create new merged cluster
         const newClusterId = (nextClusterId++).toString();
-        const mergedMembers = new Set([... cluster1.members, ... cluster2.members]);
+        const mergedMembers = new Set([...cluster1.members, ...cluster2.members]);
 
         const newCluster: ClusterNode = {
             id: newClusterId,
@@ -174,7 +183,7 @@ export function teraHAC(graph: Graph, config: TeraHACConfig = {}): TeraHACResult
 
                 const newRoot: ClusterNode = {
                     id: (nextClusterId++).toString(),
-                    members: new Set([... root.members, ... currentCluster.members]),
+                    members: new Set([...root.members, ...currentCluster.members]),
                     left: root,
                     right: currentCluster,
                     distance: Infinity,
@@ -208,10 +217,14 @@ export function teraHAC(graph: Graph, config: TeraHACConfig = {}): TeraHACResult
 
 /**
  * Calculate distance matrix between all pairs of nodes
+ * @param graph - The input graph
+ * @param nodes - Array of nodes to calculate distances between
+ * @param useGraphDistance - Whether to use graph-based shortest path distances
+ * @returns 2D distance matrix
  */
-function calculateDistanceMatrix(graph: Graph, nodes: {id: NodeId}[], useGraphDistance: boolean): number[][] {
+function calculateDistanceMatrix(graph: Graph, nodes: { id: NodeId }[], useGraphDistance: boolean): number[][] {
     const n = nodes.length;
-    const matrix: number[][] = Array.from({length: n}, () => new Array(n).fill(Infinity) as number[]);
+    const matrix: number[][] = Array.from({ length: n }, () => new Array(n).fill(Infinity) as number[]);
 
     if (useGraphDistance) {
         // Use graph-based distances (shortest path)
@@ -278,6 +291,9 @@ function calculateDistanceMatrix(graph: Graph, nodes: {id: NodeId}[], useGraphDi
 
 /**
  * BFS-based shortest path calculation from a source node
+ * @param graph - The input graph
+ * @param source - The source node ID
+ * @returns Map of node IDs to their distances from the source
  */
 function bfsShortestPaths(graph: Graph, source: NodeId): Map<NodeId, number> {
     const distances = new Map<NodeId, number>();
@@ -309,12 +325,15 @@ function bfsShortestPaths(graph: Graph, source: NodeId): Map<NodeId, number> {
 
 /**
  * Initialize merge candidates priority queue
+ * @param clusters - Map of cluster IDs to cluster nodes
+ * @param distanceMatrix - 2D distance matrix between nodes
+ * @returns Array of merge candidates sorted by distance
  */
 function initializeMergeCandidates(
     clusters: Map<string, ClusterNode>,
     distanceMatrix: number[][],
-): {cluster1Id: string, cluster2Id: string, distance: number}[] {
-    const candidates: {cluster1Id: string, cluster2Id: string, distance: number}[] = [];
+): { cluster1Id: string; cluster2Id: string; distance: number }[] {
+    const candidates: { cluster1Id: string; cluster2Id: string; distance: number }[] = [];
     const clusterIds = Array.from(clusters.keys());
 
     for (let i = 0; i < clusterIds.length; i++) {
@@ -347,10 +366,14 @@ function initializeMergeCandidates(
 
 /**
  * Find the closest pair of clusters
+ * @param mergeCandidates - Array of merge candidates
+ * @returns The closest cluster pair with their distance
  */
-function findClosestPair(
-    mergeCandidates: {cluster1Id: string, cluster2Id: string, distance: number}[],
-): {cluster1Id: string, cluster2Id: string, distance: number} {
+function findClosestPair(mergeCandidates: { cluster1Id: string; cluster2Id: string; distance: number }[]): {
+    cluster1Id: string;
+    cluster2Id: string;
+    distance: number;
+} {
     // Return the first (closest) valid candidate
     const candidate = mergeCandidates.shift();
     if (!candidate) {
@@ -362,9 +385,16 @@ function findClosestPair(
 
 /**
  * Update merge candidates after a merge operation
+ * @param mergeCandidates - Array of merge candidates to update
+ * @param oldCluster1Id - ID of first merged cluster
+ * @param oldCluster2Id - ID of second merged cluster
+ * @param newClusterId - ID of the newly created cluster
+ * @param clusters - Map of cluster IDs to cluster nodes
+ * @param distanceMatrix - 2D distance matrix between nodes
+ * @param linkage - Linkage criterion to use
  */
 function updateMergeCandidates(
-    mergeCandidates: {cluster1Id: string, cluster2Id: string, distance: number}[],
+    mergeCandidates: { cluster1Id: string; cluster2Id: string; distance: number }[],
     oldCluster1Id: string,
     oldCluster2Id: string,
     newClusterId: string,
@@ -379,8 +409,12 @@ function updateMergeCandidates(
             continue;
         }
 
-        if (candidate.cluster1Id === oldCluster1Id || candidate.cluster1Id === oldCluster2Id ||
-            candidate.cluster2Id === oldCluster1Id || candidate.cluster2Id === oldCluster2Id) {
+        if (
+            candidate.cluster1Id === oldCluster1Id ||
+            candidate.cluster1Id === oldCluster2Id ||
+            candidate.cluster2Id === oldCluster1Id ||
+            candidate.cluster2Id === oldCluster2Id
+        ) {
             mergeCandidates.splice(i, 1);
         }
     }
@@ -408,6 +442,11 @@ function updateMergeCandidates(
 
 /**
  * Calculate distance between two clusters based on linkage criterion
+ * @param cluster1 - First cluster
+ * @param cluster2 - Second cluster
+ * @param distanceMatrix - 2D distance matrix between nodes
+ * @param linkage - Linkage criterion (single, complete, average, ward)
+ * @returns The distance between the two clusters
  */
 function calculateClusterDistance(
     cluster1: ClusterNode,
@@ -443,14 +482,14 @@ function calculateClusterDistance(
     // Apply linkage criterion
     switch (linkage) {
         case "single":
-            return Math.min(... distances);
+            return Math.min(...distances);
         case "complete":
-            return Math.max(... distances);
+            return Math.max(...distances);
         case "average":
             return distances.reduce((sum, d) => sum + d, 0) / distances.length;
         case "ward":
             // Simplified Ward linkage (would need cluster centroids for full implementation)
-            return distances.reduce((sum, d) => sum + (d * d), 0) / distances.length;
+            return distances.reduce((sum, d) => sum + d * d, 0) / distances.length;
         default:
             return distances.reduce((sum, d) => sum + d, 0) / distances.length;
     }
@@ -458,6 +497,9 @@ function calculateClusterDistance(
 
 /**
  * Extract flat clustering from dendrogram
+ * @param dendrogram - The root of the dendrogram tree
+ * @param numClusters - The target number of clusters
+ * @returns Map of node IDs to cluster assignments
  */
 function extractFlatClustering(dendrogram: ClusterNode, numClusters: number): Map<NodeId, number> {
     const clusters = new Map<NodeId, number>();

package/src/types/index.ts

@@ -72,6 +72,12 @@ export interface TraversalOptions {
 
 export interface DijkstraOptions {
     target?: NodeId;
+    /**
+     * Use bidirectional search optimization for point-to-point queries.
+     * Defaults to true for graphs with >10 nodes, false for smaller graphs.
+     * Set explicitly to override automatic heuristic.
+     */
+    bidirectional?: boolean;
 }
 
 export interface BellmanFordResult {
@@ -98,9 +104,11 @@ export interface LouvainOptions {
     resolution?: number; // Resolution parameter (default: 1.0)
     maxIterations?: number; // Maximum iterations (default: 100)
     tolerance?: number; // Improvement tolerance (default: 1e-6)
+    useOptimized?: boolean; // Use optimized implementation for large graphs (default: true for graphs > 50 nodes)
 }
 
 export interface GirvanNewmanOptions {
     maxCommunities?: number; // Stop when this many communities reached
     minCommunitySize?: number; // Minimum size for valid community
+    maxIterations?: number; // Maximum iterations to prevent infinite loops
 }

package/src/utils/algorithm-utilities.ts

@@ -0,0 +1,2 @@
+// Algorithm utility functions will be added here
+export {};

package/src/utils/graph-converters.ts

@@ -0,0 +1,269 @@
+import { Graph } from "../core/graph.js";
+import type { NodeId } from "../types/index.js";
+
+/**
+ * Convert Graph class to Map representation
+ * Used by community detection and flow algorithms
+ * @param graph - The Graph instance to convert
+ * @returns A nested Map where outer keys are source nodes and inner maps contain target nodes with edge weights
+ */
+export function graphToMap(graph: Graph): Map<string, Map<string, number>> {
+    const map = new Map<string, Map<string, number>>();
+
+    // Initialize all nodes
+    for (const node of graph.nodes()) {
+        map.set(String(node.id), new Map());
+    }
+
+    // Add edges with weights
+    for (const edge of graph.edges()) {
+        const source = String(edge.source);
+        const target = String(edge.target);
+        const weight = edge.weight ?? 1;
+
+        const sourceMap = map.get(source);
+        if (sourceMap) {
+            sourceMap.set(target, weight);
+        }
+
+        // For undirected graphs, add reverse edge
+        if (!graph.isDirected) {
+            const targetMap = map.get(target);
+            if (targetMap) {
+                targetMap.set(source, weight);
+            }
+        }
+    }
+
+    return map;
+}
+
+/**
+ * Convert Map representation to Graph class
+ * @param map - The nested Map representation of the graph
+ * @param isDirected - Whether the resulting graph should be directed (defaults to true)
+ * @returns A new Graph instance with nodes and edges from the map
+ */
+export function mapToGraph(map: Map<string, Map<string, number>>, isDirected = true): Graph {
+    const graph = new Graph({ directed: isDirected });
+
+    // Add all nodes first
+    for (const node of map.keys()) {
+        graph.addNode(node);
+    }
+
+    // Add edges
+    const processedEdges = new Set<string>();
+
+    for (const [source, neighbors] of map) {
+        for (const [target, weight] of neighbors) {
+            const edgeKey = isDirected ? `${source}->${target}` : [source, target].sort().join("-");
+
+            // Skip if we've already processed this edge (for undirected graphs)
+            if (!isDirected && processedEdges.has(edgeKey)) {
+                continue;
+            }
+
+            graph.addEdge(source, target, weight);
+            processedEdges.add(edgeKey);
+        }
+    }
+
+    return graph;
+}
+
+/**
+ * Adapter for using Graph algorithms with Map representation
+ * Implements a subset of Graph interface methods needed by algorithms
+ */
+export class GraphAdapter {
+    private map: Map<string, Map<string, number>>;
+    public readonly isDirected: boolean;
+
+    /**
+     * Creates a new GraphAdapter instance wrapping a Map representation.
+     * @param map - The nested Map representation of the graph
+     * @param isDirected - Whether the graph should be treated as directed (defaults to true)
+     */
+    constructor(map: Map<string, Map<string, number>>, isDirected = true) {
+        this.map = map;
+        this.isDirected = isDirected;
+    }
+
+    /**
+     * Get all nodes
+     * @returns Array of node objects with their ids
+     */
+    nodes(): { id: NodeId }[] {
+        return Array.from(this.map.keys()).map((id) => ({ id }));
+    }
+
+    /**
+     * Get node count
+     * @returns The total number of nodes in the graph
+     */
+    get nodeCount(): number {
+        return this.map.size;
+    }
+
+    /**
+     * Check if node exists
+     * @param nodeId - The id of the node to check
+     * @returns True if the node exists, false otherwise
+     */
+    hasNode(nodeId: NodeId): boolean {
+        return this.map.has(String(nodeId));
+    }
+
+    /**
+     * Get neighbors of a node
+     * @param nodeId - The id of the node to get neighbors for
+     * @returns Array of neighbor node ids
+     */
+    neighbors(nodeId: NodeId): NodeId[] {
+        const neighbors = this.map.get(String(nodeId));
+        if (!neighbors) {
+            return [];
+        }
+
+        return Array.from(neighbors.keys());
+    }
+
+    /**
+     * Get edge between two nodes
+     * @param source - The source node id
+     * @param target - The target node id
+     * @returns The edge object with source, target and weight, or null if no edge exists
+     */
+    getEdge(source: NodeId, target: NodeId): { source: NodeId; target: NodeId; weight?: number } | null {
+        const sourceNeighbors = this.map.get(String(source));
+        if (!sourceNeighbors) {
+            return null;
+        }
+
+        const weight = sourceNeighbors.get(String(target));
+        if (weight === undefined) {
+            return null;
+        }
+
+        return { source, target, weight };
+    }
+
+    /**
+     * Check if edge exists
+     * @param source - The source node id
+     * @param target - The target node id
+     * @returns True if an edge exists between source and target, false otherwise
+     */
+    hasEdge(source: NodeId, target: NodeId): boolean {
+        const sourceNeighbors = this.map.get(String(source));
+        if (!sourceNeighbors) {
+            return false;
+        }
+
+        return sourceNeighbors.has(String(target));
+    }
+
+    /**
+     * Get all edges
+     * @returns Array of edge objects with source, target and optional weight
+     */
+    edges(): { source: NodeId; target: NodeId; weight?: number }[] {
+        const edges: { source: NodeId; target: NodeId; weight?: number }[] = [];
+        const processedEdges = new Set<string>();
+
+        for (const [source, neighbors] of this.map) {
+            for (const [target, weight] of neighbors) {
+                const edgeKey = this.isDirected ? `${source}->${target}` : [source, target].sort().join("-");
+
+                // Skip if we've already processed this edge (for undirected graphs)
+                if (!this.isDirected && processedEdges.has(edgeKey)) {
+                    continue;
+                }
+
+                edges.push({ source, target, weight });
+                processedEdges.add(edgeKey);
+            }
+        }
+
+        return edges;
+    }
+
+    /**
+     * Get edge count
+     * @returns The total number of edges in the graph
+     */
+    get edgeCount(): number {
+        if (this.isDirected) {
+            let count = 0;
+            for (const neighbors of this.map.values()) {
+                count += neighbors.size;
+            }
+            return count;
+        }
+
+        // For undirected graphs, count each edge once
+        let count = 0;
+        const counted = new Set<string>();
+
+        for (const [source, neighbors] of this.map) {
+            for (const target of neighbors.keys()) {
+                const edgeKey = [source, target].sort().join("-");
+                if (!counted.has(edgeKey)) {
+                    counted.add(edgeKey);
+                    count++;
+                }
+            }
+        }
+        return count;
+    }
+
+    /**
+     * Get node degree
+     * @param nodeId - The id of the node to get degree for
+     * @returns The number of edges connected to the node
+     */
+    degree(nodeId: NodeId): number {
+        const neighbors = this.map.get(String(nodeId));
+        return neighbors ? neighbors.size : 0;
+    }
+
+    /**
+     * Get in-degree (for directed graphs)
+     * @param nodeId - The id of the node to get in-degree for
+     * @returns The number of incoming edges to the node
+     */
+    inDegree(nodeId: NodeId): number {
+        if (!this.isDirected) {
+            return this.degree(nodeId);
+        }
+
+        let count = 0;
+        const targetId = String(nodeId);
+
+        for (const neighbors of this.map.values()) {
+            if (neighbors.has(targetId)) {
+                count++;
+            }
+        }
+
+        return count;
+    }
+
+    /**
+     * Get out-degree (for directed graphs)
+     * @param nodeId - The id of the node to get out-degree for
+     * @returns The number of outgoing edges from the node
+     */
+    outDegree(nodeId: NodeId): number {
+        return this.degree(nodeId);
+    }
+
+    /**
+     * Get underlying map representation
+     * @returns The internal Map representation of the graph
+     */
+    getMap(): Map<string, Map<string, number>> {
+        return this.map;
+    }
+}

package/src/utils/graph-utilities.ts

@@ -0,0 +1,173 @@
+import { Graph } from "../core/graph.js";
+import type { NodeId } from "../types/index.js";
+
+/**
+ * Reconstructs a path from source to target using a predecessor map
+ * @param target - The target node
+ * @param predecessor - Map of node to its predecessor in the path
+ * @returns Array of nodes from source to target, or empty array if no path exists
+ */
+export function reconstructPath<T>(target: T, predecessor: Map<T, T | null>): T[] {
+    const path: T[] = [];
+    let current: T | null = target;
+
+    // Build path backwards from target to source
+    while (current !== null) {
+        path.unshift(current);
+        const pred = predecessor.get(current);
+        if (pred === undefined) {
+            // No path exists
+            return [];
+        }
+
+        current = pred;
+    }
+
+    return path;
+}
+
+/**
+ * Find common neighbors between two nodes
+ * @param graph - The graph
+ * @param source - First node
+ * @param target - Second node
+ * @param directed - Whether to consider edge direction
+ * @returns Set of common neighbor node IDs
+ */
+export function getCommonNeighbors(graph: Graph, source: NodeId, target: NodeId, directed = false): Set<NodeId> {
+    const sourceNeighbors = new Set(directed ? graph.outNeighbors(source) : graph.neighbors(source));
+    const targetNeighbors = new Set(directed ? graph.outNeighbors(target) : graph.neighbors(target));
+
+    const common = new Set<NodeId>();
+    for (const neighbor of sourceNeighbors) {
+        if (targetNeighbors.has(neighbor)) {
+            common.add(neighbor);
+        }
+    }
+
+    return common;
+}
+
+/**
+ * Find common neighbors for link prediction in directed graphs
+ * This finds nodes that form a path from source to target (source->X->target)
+ * @param graph - The graph
+ * @param source - First node
+ * @param target - Second node
+ * @returns Set of intermediate node IDs
+ */
+export function getIntermediateNodes(graph: Graph, source: NodeId, target: NodeId): Set<NodeId> {
+    const sourceOutNeighbors = new Set(graph.outNeighbors(source));
+    const targetInNeighbors = new Set(graph.inNeighbors(target));
+
+    const common = new Set<NodeId>();
+    for (const neighbor of sourceOutNeighbors) {
+        if (targetInNeighbors.has(neighbor)) {
+            common.add(neighbor);
+        }
+    }
+
+    return common;
+}
+
+/**
+ * Generate a consistent edge key for undirected graphs
+ * @param source - Source node
+ * @param target - Target node
+ * @param isDirected - Whether the graph is directed
+ * @returns A consistent edge identifier
+ */
+export function getEdgeKey(source: NodeId, target: NodeId, isDirected: boolean): string {
+    if (isDirected) {
+        return `${String(source)}->${String(target)}`;
+    }
+
+    // For undirected graphs, sort to ensure consistency
+    const [first, second] = source < target ? [source, target] : [target, source];
+    return `${String(first)}-${String(second)}`;
+}
+
+/**
+ * Calculate total edge weight in a graph
+ * @param graph - The graph
+ * @returns Total weight of all edges
+ */
+export function getTotalEdgeWeight(graph: Graph): number {
+    let totalWeight = 0;
+    for (const edge of graph.edges()) {
+        totalWeight += edge.weight ?? 1;
+    }
+    return graph.isDirected ? totalWeight : totalWeight / 2;
+}
+
+/**
+ * Get node degree with optional mode for directed graphs
+ * @param graph - The graph
+ * @param nodeId - The node ID
+ * @param mode - Degree mode for directed graphs
+ * @returns Node degree
+ */
+export function getNodeDegree(graph: Graph, nodeId: NodeId, mode: "in" | "out" | "total" = "total"): number {
+    if (!graph.isDirected || mode === "total") {
+        return graph.degree(nodeId);
+    }
+
+    if (mode === "in") {
+        return graph.inDegree(nodeId);
+    }
+
+    return graph.outDegree(nodeId);
+}
+
+/**
+ * Convert directed graph to undirected
+ * @param graph - The directed graph
+ * @returns A new undirected graph
+ */
+export function makeUndirected(graph: Graph): Graph {
+    if (!graph.isDirected) {
+        return graph;
+    }
+
+    const undirected = new Graph({ directed: false });
+
+    // Add all nodes
+    for (const node of graph.nodes()) {
+        undirected.addNode(node.id, node.data);
+    }
+
+    // Add edges (will automatically be made bidirectional)
+    for (const edge of graph.edges()) {
+        // For undirected, we only add each edge once
+        if (!undirected.hasEdge(edge.source, edge.target)) {
+            undirected.addEdge(edge.source, edge.target, edge.weight, edge.data);
+        }
+    }
+
+    return undirected;
+}
+
+/**
+ * Renumber communities consecutively starting from 0
+ * @param communities - Map of node to community ID
+ * @returns Map with renumbered community IDs
+ */
+export function renumberCommunities<T>(communities: Map<T, number>): Map<T, number> {
+    const uniqueCommunities = new Set(communities.values());
+    const remapping = new Map<number, number>();
+    let newId = 0;
+
+    for (const community of uniqueCommunities) {
+        remapping.set(community, newId++);
+    }
+
+    const renumbered = new Map<T, number>();
+    for (const [node, community] of communities) {
+        const newCommunity = remapping.get(community);
+        if (newCommunity !== undefined) {
+            renumbered.set(node, newCommunity);
+        }
+    }
+
+    return renumbered;
+}

package/src/utils/index.ts

@@ -0,0 +1,4 @@
+export * from "./algorithm-utilities.js";
+export * from "./graph-utilities.js";
+export * from "./math-utilities.js";
+export * from "./matrix-utilities.js";