@graphty/algorithms 1.2.0 → 1.4.2

package/src/algorithms/centrality/closeness.ts

@@ -1,5 +1,6 @@
-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";
+import { bfsDistancesOnly, bfsWeightedDistances } from "../traversal/bfs-variants.js";
 
 /**
  * Closeness centrality implementation
@@ -25,39 +26,26 @@ export interface ClosenessCentralityOptions {
      * Consider only nodes within this distance (default: undefined = all nodes)
      */
     cutoff?: number;
+    /**
+     * Whether to use optimized BFS implementation for large graphs
+     */
+    optimized?: boolean;
 }
 
 /**
- * Calculate closeness centrality for all nodes
- */
-export function closenessCentrality(
-    graph: Graph,
-    options: ClosenessCentralityOptions = {},
-): Record<string, number> {
-    const nodes = Array.from(graph.nodes()).map((node) => node.id);
-    const centrality: Record<string, number> = {};
-
-    for (const sourceNode of nodes) {
-        centrality[String(sourceNode)] = nodeClosenessCentrality(graph, sourceNode, options);
-    }
-
-    return centrality;
-}
-
-/**
- * Calculate closeness centrality for a specific node
+ * Calculate closeness centrality from distances
+ * @param distances - Map of node IDs to their distances from source
+ * @param sourceNode - The source node for distance calculations
+ * @param totalNodes - Total number of nodes in the graph
+ * @param options - Algorithm configuration options
+ * @returns The closeness centrality score for the source node
  */
-export function nodeClosenessCentrality(
-    graph: Graph,
-    node: NodeId,
-    options: ClosenessCentralityOptions = {},
+function calculateClosenessFromDistances(
+    distances: Map<NodeId, number>,
+    sourceNode: NodeId,
+    totalNodes: number,
+    options: ClosenessCentralityOptions,
 ): number {
-    if (!graph.hasNode(node)) {
-        throw new Error(`Node ${String(node)} not found in graph`);
-    }
-
-    const distances = singleSourceShortestPathLengths(graph, node, options.cutoff);
-
     if (distances.size <= 1) {
         return 0; // No other nodes reachable
     }
@@ -66,18 +54,23 @@ export function nodeClosenessCentrality(
 
     if (options.harmonic) {
         // Harmonic centrality: sum of reciprocals of distances
-        for (const [targetNode, distance] of Array.from(distances)) {
-            if (targetNode !== node && distance > 0) {
+        for (const [targetNode, distance] of distances) {
+            if (targetNode !== sourceNode && distance > 0 && distance < Infinity) {
                 centrality += 1 / distance;
             }
         }
+
+        // Normalization for harmonic centrality
+        if (options.normalized && totalNodes > 1) {
+            centrality = centrality / (totalNodes - 1);
+        }
     } else {
         // Standard closeness: reciprocal of sum of distances
         let totalDistance = 0;
         let reachableNodes = 0;
 
-        for (const [targetNode, distance] of Array.from(distances)) {
-            if (targetNode !== node) {
+        for (const [targetNode, distance] of distances) {
+            if (targetNode !== sourceNode && distance < Infinity) {
                 totalDistance += distance;
                 reachableNodes++;
             }
@@ -87,74 +80,77 @@ export function nodeClosenessCentrality(
             centrality = 1 / totalDistance;
 
             // Wasserman and Faust normalization for disconnected graphs
-            if (options.normalized) {
-                const n = Array.from(graph.nodes()).length;
-                centrality = centrality * reachableNodes / (n - 1);
+            if (options.normalized && totalNodes > 1) {
+                centrality = (centrality * reachableNodes) / (totalNodes - 1);
             }
         }
     }
 
-    // Normalization for harmonic centrality
-    if (options.harmonic && options.normalized) {
-        const n = Array.from(graph.nodes()).length;
-        if (n > 1) {
-            centrality = centrality / (n - 1);
-        }
-    }
-
     return centrality;
 }
 
 /**
- * Single-source shortest path lengths using BFS (for unweighted graphs)
+ * Calculate closeness centrality for all nodes in the graph
+ *
+ * Closeness centrality measures how close a node is to all other nodes
+ * in the graph. It is the reciprocal of the sum of the shortest path
+ * distances to all other reachable nodes.
+ * @param graph - The input graph
+ * @param options - Algorithm options
+ * @returns Centrality scores for each node
+ * @example
+ * ```typescript
+ * const graph = new Graph();
+ * graph.addEdge("A", "B");
+ * graph.addEdge("B", "C");
+ *
+ * const centrality = closenessCentrality(graph);
+ * // { A: 0.5, B: 1.0, C: 0.5 }
+ * ```
+ *
+ * Time Complexity: O(V * (V + E)) for unweighted graphs
+ * Space Complexity: O(V)
  */
-function singleSourceShortestPathLengths(
-    graph: Graph,
-    source: NodeId,
-    cutoff?: number,
-): Map<NodeId, number> {
-    const distances = new Map<NodeId, number>();
-    const visited = new Set<NodeId>();
-    const queue: {node: NodeId, distance: number}[] = [];
-
-    // Initialize
-    queue.push({node: source, distance: 0});
-    visited.add(source);
-    distances.set(source, 0);
-
-    while (queue.length > 0) {
-        const current = queue.shift();
-        if (!current) {
-            break;
-        }
-
-        // Skip if beyond cutoff
-        if (cutoff !== undefined && current.distance >= cutoff) {
-            continue;
-        }
+export function closenessCentrality(graph: Graph, options: ClosenessCentralityOptions = {}): Record<string, number> {
+    const nodes = Array.from(graph.nodes()).map((node) => node.id);
+    const centrality: Record<string, number> = {};
 
-        // Explore neighbors
-        for (const neighbor of Array.from(graph.neighbors(current.node))) {
-            if (!visited.has(neighbor)) {
-                const newDistance = current.distance + 1;
+    for (const sourceNode of nodes) {
+        centrality[String(sourceNode)] = nodeClosenessCentrality(graph, sourceNode, options);
+    }
 
-                // Skip if beyond cutoff
-                if (cutoff !== undefined && newDistance > cutoff) {
-                    continue;
-                }
+    return centrality;
+}
 
-                visited.add(neighbor);
-                distances.set(neighbor, newDistance);
-                queue.push({node: neighbor, distance: newDistance});
-            }
-        }
+/**
+ * Calculate closeness centrality for a specific node
+ * @param graph - The input graph to analyze
+ * @param node - The node to calculate centrality for
+ * @param options - Algorithm configuration options
+ * @returns The closeness centrality score for the node
+ */
+export function nodeClosenessCentrality(graph: Graph, node: NodeId, options: ClosenessCentralityOptions = {}): number {
+    if (!graph.hasNode(node)) {
+        throw new Error(`Node ${String(node)} not found in graph`);
     }
 
-    return distances;
+    // Use optimized BFS variant for unweighted graphs
+    const distances = bfsDistancesOnly(
+        graph,
+        node,
+        options.cutoff,
+        options.optimized !== undefined ? { optimized: options.optimized } : {},
+    );
+    const totalNodes = graph.nodeCount;
+
+    return calculateClosenessFromDistances(distances, node, totalNodes, options);
 }
 
 /**
  * Calculate weighted closeness centrality using Dijkstra's algorithm
+ * @param graph - The input graph to analyze
+ * @param options - Algorithm configuration options
+ * @returns Centrality scores for each node keyed by node ID
  */
 export function weightedClosenessCentrality(
     graph: Graph,
@@ -172,6 +168,10 @@ export function weightedClosenessCentrality(
 
 /**
  * Calculate weighted closeness centrality for a specific node using Dijkstra
+ * @param graph - The input graph to analyze
+ * @param node - The node to calculate centrality for
+ * @param options - Algorithm configuration options
+ * @returns The weighted closeness centrality score for the node
  */
 export function nodeWeightedClosenessCentrality(
     graph: Graph,
@@ -182,115 +182,14 @@ export function nodeWeightedClosenessCentrality(
         throw new Error(`Node ${String(node)} not found in graph`);
     }
 
-    const distances = dijkstraDistances(graph, node, options.cutoff);
-
-    if (distances.size <= 1) {
-        return 0; // No other nodes reachable
-    }
-
-    let centrality = 0;
-
-    if (options.harmonic) {
-        // Harmonic centrality: sum of reciprocals of distances
-        for (const [targetNode, distance] of Array.from(distances)) {
-            if (targetNode !== node && distance > 0 && distance < Infinity) {
-                centrality += 1 / distance;
-            }
-        }
-    } else {
-        // Standard closeness: reciprocal of sum of distances
-        let totalDistance = 0;
-        let reachableNodes = 0;
-
-        for (const [targetNode, distance] of Array.from(distances)) {
-            if (targetNode !== node && distance < Infinity) {
-                totalDistance += distance;
-                reachableNodes++;
-            }
-        }
-
-        if (totalDistance > 0) {
-            centrality = 1 / totalDistance;
-
-            // Wasserman and Faust normalization for disconnected graphs
-            if (options.normalized) {
-                const n = Array.from(graph.nodes()).length;
-                centrality = centrality * reachableNodes / (n - 1);
-            }
-        }
-    }
-
-    // Normalization for harmonic centrality
-    if (options.harmonic && options.normalized) {
-        const n = Array.from(graph.nodes()).length;
-        if (n > 1) {
-            centrality = centrality / (n - 1);
-        }
-    }
-
-    return centrality;
-}
-
-/**
- * Single-source shortest path distances using Dijkstra's algorithm
- */
-function dijkstraDistances(
-    graph: Graph,
-    source: NodeId,
-    cutoff?: number,
-): Map<NodeId, number> {
-    const distances = new Map<NodeId, number>();
-    const visited = new Set<NodeId>();
-    const pq: {node: NodeId, distance: number}[] = [];
-
-    // Initialize distances
-    for (const node of Array.from(graph.nodes())) {
-        distances.set(node.id, node.id === source ? 0 : Infinity);
-    }
-
-    pq.push({node: source, distance: 0});
-
-    while (pq.length > 0) {
-        // Simple priority queue (could be optimized with a proper heap)
-        pq.sort((a, b) => a.distance - b.distance);
-        const current = pq.shift();
-
-        if (!current || visited.has(current.node)) {
-            continue;
-        }
-
-        visited.add(current.node);
-
-        // Skip if beyond cutoff
-        if (cutoff !== undefined && current.distance > cutoff) {
-            continue;
-        }
-
-        // Explore neighbors
-        for (const neighbor of Array.from(graph.neighbors(current.node))) {
-            if (visited.has(neighbor)) {
-                continue;
-            }
-
-            const edge = graph.getEdge(current.node, neighbor);
-            if (!edge) {
-                continue;
-            }
-
-            const edgeWeight = edge.weight ?? 1;
-            const tentativeDistance = current.distance + edgeWeight;
-            const currentDistance = distances.get(neighbor) ?? Infinity;
-
-            if (tentativeDistance < currentDistance) {
-                distances.set(neighbor, tentativeDistance);
-
-                // Skip if beyond cutoff
-                if (cutoff === undefined || tentativeDistance <= cutoff) {
-                    pq.push({node: neighbor, distance: tentativeDistance});
-                }
-            }
-        }
-    }
+    // Use optimized weighted BFS variant (simplified Dijkstra)
+    const distances = bfsWeightedDistances(
+        graph,
+        node,
+        options.cutoff,
+        options.optimized !== undefined ? { optimized: options.optimized } : {},
+    );
+    const totalNodes = graph.nodeCount;
 
-    return distances;
+    return calculateClosenessFromDistances(distances, node, totalNodes, options);
 }

package/src/algorithms/centrality/degree.ts

@@ -1,5 +1,5 @@
-import type {Graph} from "../../core/graph.js";
-import type {CentralityOptions, CentralityResult} from "../../types/index.js";
+import type { Graph } from "../../core/graph.js";
+import type { CentralityOptions, CentralityResult } from "../../types/index.js";
 
 /**
  * Degree centrality implementation
@@ -10,18 +10,18 @@ import type {CentralityOptions, CentralityResult} from "../../types/index.js";
 
 /**
  * Calculate degree centrality for all nodes in the graph
+ * @param graph - The input graph to analyze
+ * @param options - Algorithm configuration options
+ * @returns Centrality scores for each node keyed by node ID
  */
-export function degreeCentrality(
-    graph: Graph,
-    options: CentralityOptions = {},
-): CentralityResult {
+export function degreeCentrality(graph: Graph, options: CentralityOptions = {}): CentralityResult {
     const centrality: CentralityResult = {};
-    const {nodeCount} = graph;
+    const { nodeCount } = graph;
 
-    // Calculate normalization factor
-    const maxPossibleDegree = graph.isDirected ? nodeCount - 1 : nodeCount - 1;
+    // Calculate normalization factor (same for both directed and undirected graphs)
+    const maxPossibleDegree = nodeCount - 1;
 
-    for (const node of Array.from(graph.nodes())) {
+    for (const node of graph.nodes()) {
         let degree: number;
 
         if (graph.isDirected && options.mode) {
@@ -49,9 +49,7 @@ export function degreeCentrality(
         }
 
         // Apply normalization if requested
-        const normalizedDegree = options.normalized && maxPossibleDegree > 0 ?
-            degree / maxPossibleDegree :
-            degree;
+        const normalizedDegree = options.normalized && maxPossibleDegree > 0 ? degree / maxPossibleDegree : degree;
 
         centrality[node.id.toString()] = normalizedDegree;
     }
@@ -61,17 +59,17 @@ export function degreeCentrality(
 
 /**
  * Calculate degree centrality for a specific node
+ * @param graph - The input graph to analyze
+ * @param nodeId - The node to calculate centrality for
+ * @param options - Algorithm configuration options
+ * @returns The degree centrality score for the node
  */
-export function nodeDegreeCentrality(
-    graph: Graph,
-    nodeId: string | number,
-    options: CentralityOptions = {},
-): number {
+export function nodeDegreeCentrality(graph: Graph, nodeId: string | number, options: CentralityOptions = {}): number {
     if (!graph.hasNode(nodeId)) {
         throw new Error(`Node ${String(nodeId)} not found in graph`);
     }
 
-    const {nodeCount} = graph;
+    const { nodeCount } = graph;
     let degree: number;
 
     if (graph.isDirected && options.mode) {
@@ -99,7 +97,5 @@ export function nodeDegreeCentrality(
     // Apply normalization if requested
     const maxPossibleDegree = nodeCount - 1;
 
-    return options.normalized && maxPossibleDegree > 0 ?
-        degree / maxPossibleDegree :
-        degree;
+    return options.normalized && maxPossibleDegree > 0 ? degree / maxPossibleDegree : degree;
 }