@graphty/algorithms 1.3.1 → 1.4.2

package/src/utils/graph-converters.ts

@@ -1,9 +1,11 @@
-import {Graph} from "../core/graph.js";
-import type {NodeId} from "../types/index.js";
+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>>();
@@ -38,12 +40,12 @@ export function graphToMap(graph: Graph): Map<string, Map<string, number>> {
 
 /**
  * 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});
+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()) {
@@ -78,6 +80,11 @@ 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;
@@ -85,13 +92,15 @@ export class GraphAdapter {
 
     /**
      * Get all nodes
+     * @returns Array of node objects with their ids
      */
-    nodes(): {id: NodeId}[] {
-        return Array.from(this.map.keys()).map((id) => ({id}));
+    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;
@@ -99,6 +108,8 @@ export class GraphAdapter {
 
     /**
      * 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));
@@ -106,6 +117,8 @@ export class GraphAdapter {
 
     /**
      * 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));
@@ -118,8 +131,11 @@ export class GraphAdapter {
 
     /**
      * 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 {
+    getEdge(source: NodeId, target: NodeId): { source: NodeId; target: NodeId; weight?: number } | null {
         const sourceNeighbors = this.map.get(String(source));
         if (!sourceNeighbors) {
             return null;
@@ -130,11 +146,14 @@ export class GraphAdapter {
             return null;
         }
 
-        return {source, target, weight};
+        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));
@@ -147,9 +166,10 @@ export class GraphAdapter {
 
     /**
      * 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}[] = [];
+    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) {
@@ -161,7 +181,7 @@ export class GraphAdapter {
                     continue;
                 }
 
-                edges.push({source, target, weight});
+                edges.push({ source, target, weight });
                 processedEdges.add(edgeKey);
             }
         }
@@ -171,6 +191,7 @@ export class GraphAdapter {
 
     /**
      * Get edge count
+     * @returns The total number of edges in the graph
      */
     get edgeCount(): number {
         if (this.isDirected) {
@@ -199,6 +220,8 @@ export class GraphAdapter {
 
     /**
      * 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));
@@ -207,6 +230,8 @@ export class GraphAdapter {
 
     /**
      * 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) {
@@ -227,6 +252,8 @@ export class GraphAdapter {
 
     /**
      * 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);
@@ -234,6 +261,7 @@ export class GraphAdapter {
 
     /**
      * 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

@@ -1,5 +1,5 @@
-import {Graph} from "../core/graph.js";
-import type {NodeId} from "../types/index.js";
+import { Graph } from "../core/graph.js";
+import type { NodeId } from "../types/index.js";
 
 /**
  * Reconstructs a path from source to target using a predecessor map
@@ -7,10 +7,7 @@ import type {NodeId} from "../types/index.js";
  * @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[] {
+export function reconstructPath<T>(target: T, predecessor: Map<T, T | null>): T[] {
     const path: T[] = [];
     let current: T | null = target;
 
@@ -37,18 +34,9 @@ export function reconstructPath<T>(
  * @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),
-    );
+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) {
@@ -68,11 +56,7 @@ export function getCommonNeighbors(
  * @param target - Second node
  * @returns Set of intermediate node IDs
  */
-export function getIntermediateNodes(
-    graph: Graph,
-    source: NodeId,
-    target: NodeId,
-): Set<NodeId> {
+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));
 
@@ -93,11 +77,7 @@ export function getIntermediateNodes(
  * @param isDirected - Whether the graph is directed
  * @returns A consistent edge identifier
  */
-export function getEdgeKey(
-    source: NodeId,
-    target: NodeId,
-    isDirected: boolean,
-): string {
+export function getEdgeKey(source: NodeId, target: NodeId, isDirected: boolean): string {
     if (isDirected) {
         return `${String(source)}->${String(target)}`;
     }
@@ -127,11 +107,7 @@ export function getTotalEdgeWeight(graph: Graph): number {
  * @param mode - Degree mode for directed graphs
  * @returns Node degree
  */
-export function getNodeDegree(
-    graph: Graph,
-    nodeId: NodeId,
-    mode: "in" | "out" | "total" = "total",
-): number {
+export function getNodeDegree(graph: Graph, nodeId: NodeId, mode: "in" | "out" | "total" = "total"): number {
     if (!graph.isDirected || mode === "total") {
         return graph.degree(nodeId);
     }
@@ -153,7 +129,7 @@ export function makeUndirected(graph: Graph): Graph {
         return graph;
     }
 
-    const undirected = new Graph({directed: false});
+    const undirected = new Graph({ directed: false });
 
     // Add all nodes
     for (const node of graph.nodes()) {
@@ -176,9 +152,7 @@ export function makeUndirected(graph: Graph): Graph {
  * @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> {
+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;

package/src/utils/math-utilities.ts

@@ -7,6 +7,10 @@ export class SeededRandom {
     private readonly a = 1103515245;
     private readonly c = 12345;
 
+    /**
+     * Creates a new SeededRandom instance with the given seed.
+     * @param seed - The seed value for reproducible random number generation
+     */
     constructor(seed: number) {
         // Handle negative seeds correctly
         this.seed = ((seed % this.m) + this.m) % this.m;
@@ -14,14 +18,17 @@ export class SeededRandom {
 
     /**
      * Generate next random number between 0 and 1
+     * @returns A pseudo-random number in the range [0, 1]
      */
     next(): number {
-        this.seed = ((this.a * this.seed) + this.c) % this.m;
+        this.seed = (this.a * this.seed + this.c) % this.m;
         return this.seed / (this.m - 1);
     }
 
     /**
      * Create a generator function for backward compatibility
+     * @param seed - The seed value for reproducible random number generation
+     * @returns A function that returns the next random number when called
      */
     static createGenerator(seed: number): () => number {
         const rng = new SeededRandom(seed);
@@ -75,11 +82,12 @@ export function euclideanDistance(a: number[], b: number[]): number {
 export const normalize = {
     /**
      * Min-max normalization to [0, 1] range
+     * @param values - Map of values to normalize in place
      */
     minMax(values: Map<string, number>): void {
         const vals = Array.from(values.values());
-        const min = Math.min(... vals);
-        const max = Math.max(... vals);
+        const min = Math.min(...vals);
+        const max = Math.max(...vals);
         const range = max - min;
 
         if (range === 0) {
@@ -93,9 +101,10 @@ export const normalize = {
 
     /**
      * Normalize by maximum value
+     * @param values - Map of values to normalize in place
      */
     byMax(values: Map<string, number>): void {
-        const max = Math.max(... values.values());
+        const max = Math.max(...values.values());
         if (max === 0) {
             return;
         }
@@ -107,10 +116,10 @@ export const normalize = {
 
     /**
      * L2 (Euclidean) normalization
+     * @param values - Map of values to normalize in place
      */
     l2Norm(values: Map<string, number>): void {
-        const sumSquares = Array.from(values.values())
-            .reduce((sum, val) => sum + (val * val), 0);
+        const sumSquares = Array.from(values.values()).reduce((sum, val) => sum + val * val, 0);
         const norm = Math.sqrt(sumSquares);
 
         if (norm === 0) {
@@ -124,10 +133,10 @@ export const normalize = {
 
     /**
      * Normalize to sum to 1
+     * @param values - Map of values to normalize in place
      */
     sumToOne(values: Map<string, number>): void {
-        const sum = Array.from(values.values())
-            .reduce((acc, val) => acc + val, 0);
+        const sum = Array.from(values.values()).reduce((acc, val) => acc + val, 0);
 
         if (sum === 0) {
             return;

package/src/utils/optimization-helpers.ts

@@ -1,4 +1,4 @@
-import type {Graph} from "../core/graph.js";
+import type { Graph } from "../core/graph.js";
 
 /**
  * Common interface for algorithm options with optimization support
@@ -15,6 +15,9 @@ export interface OptimizableOptions {
 
 /**
  * Check if a graph should use optimizations based on its size
+ * @param nodeCount - The number of nodes in the graph
+ * @param edgeCount - The number of edges in the graph
+ * @returns True if the graph is large enough to benefit from optimizations
  */
 function shouldUseOptimizations(nodeCount: number, edgeCount: number): boolean {
     // Use optimizations for graphs with more than 10k nodes or 100k edges
@@ -23,12 +26,12 @@ function shouldUseOptimizations(nodeCount: number, edgeCount: number): boolean {
 
 /**
  * Determine if optimizations should be used for a given graph
+ * @param graph - The graph to check for optimization eligibility
+ * @param options - Options containing the optimization preference
+ * @returns True if optimizations should be used for this graph
  */
-export function shouldOptimize(
-    graph: Graph,
-    options: OptimizableOptions = {},
-): boolean {
-    const {optimized = "auto"} = options;
+export function shouldOptimize(graph: Graph, options: OptimizableOptions = {}): boolean {
+    const { optimized = "auto" } = options;
 
     if (optimized === "auto") {
         // Check graph size
@@ -40,42 +43,45 @@ export function shouldOptimize(
 
 /**
  * Merge optimization options with algorithm-specific options
+ * @param graph - The graph to determine optimization settings for
+ * @param options - Algorithm options that may include optimization settings
+ * @returns The options with resolved optimization boolean flag
  */
 export function mergeOptimizationOptions<T extends Record<string, unknown>>(
     graph: Graph,
     options: T & OptimizableOptions,
-): T & {optimized?: boolean} {
-    const {optimized: userOptimized, ... rest} = options;
+): T & { optimized?: boolean } {
+    const { optimized: userOptimized, ...rest } = options;
 
     return {
-        ... rest,
-        optimized: shouldOptimize(graph, userOptimized !== undefined ? {optimized: userOptimized} : {}),
-    } as T & {optimized?: boolean};
+        ...rest,
+        optimized: shouldOptimize(graph, userOptimized !== undefined ? { optimized: userOptimized } : {}),
+    } as T & { optimized?: boolean };
 }
 
 /**
  * Create an optimized version of an algorithm
+ * @param algorithm - The algorithm function to wrap with optimization support
+ * @param optionsTransformer - Optional function to transform options before passing to the algorithm
+ * @returns A wrapped version of the algorithm that applies optimization transformations
  * @example
  * const optimizedBetweenness = createOptimizedAlgorithm(
  *     betweennessCentrality,
  *     (graph, options) => ({...options, optimized: true})
  * );
  */
-export function createOptimizedAlgorithm<
-    TArgs extends [Graph, ...unknown[]],
-    TResult,
->(
-    algorithm: (... args: TArgs) => TResult,
+export function createOptimizedAlgorithm<TArgs extends [Graph, ...unknown[]], TResult>(
+    algorithm: (...args: TArgs) => TResult,
     optionsTransformer?: (graph: Graph, options: unknown) => unknown,
-): (... args: TArgs) => TResult {
-    return (... args: TArgs): TResult => {
-        const [graph, options, ... rest] = args;
+): (...args: TArgs) => TResult {
+    return (...args: TArgs): TResult => {
+        const [graph, options, ...rest] = args;
 
         if (optionsTransformer && options !== undefined) {
             const transformedOptions = optionsTransformer(graph, options);
-            return algorithm(... ([graph, transformedOptions, ... rest] as unknown as TArgs));
+            return algorithm(...([graph, transformedOptions, ...rest] as unknown as TArgs));
         }
 
-        return algorithm(... args);
+        return algorithm(...args);
     };
 }

package/src/utils/priorityQueue.ts

@@ -5,13 +5,17 @@ export class MinPriorityQueue<T> {
     private heap: T[] = [];
     private compare: (a: T, b: T) => number;
 
+    /**
+     * Creates a new MinPriorityQueue instance.
+     * @param compareFunction - Custom comparison function. Returns negative if a has higher priority than b.
+     */
     constructor(compareFunction?: (a: T, b: T) => number) {
         this.compare = compareFunction ?? ((a: T, b: T) => this.defaultCompare(a, b));
     }
 
     private defaultCompare(a: T, b: T): number {
-        const aWithDistance = a as T & {distance?: number};
-        const bWithDistance = b as T & {distance?: number};
+        const aWithDistance = a as T & { distance?: number };
+        const bWithDistance = b as T & { distance?: number };
 
         if (aWithDistance.distance !== undefined && bWithDistance.distance !== undefined) {
             return aWithDistance.distance - bWithDistance.distance;
@@ -25,11 +29,11 @@ export class MinPriorityQueue<T> {
     }
 
     private leftChild(i: number): number {
-        return (2 * i) + 1;
+        return 2 * i + 1;
     }
 
     private rightChild(i: number): number {
-        return (2 * i) + 2;
+        return 2 * i + 2;
     }
 
     private swap(i: number, j: number): void {
@@ -63,13 +67,23 @@ export class MinPriorityQueue<T> {
 
             const leftItem = this.heap[left];
             const minItem = this.heap[minIndex];
-            if (left < this.heap.length && leftItem !== undefined && minItem !== undefined && this.compare(leftItem, minItem) < 0) {
+            if (
+                left < this.heap.length &&
+                leftItem !== undefined &&
+                minItem !== undefined &&
+                this.compare(leftItem, minItem) < 0
+            ) {
                 minIndex = left;
             }
 
             const rightItem = this.heap[right];
             const newMinItem = this.heap[minIndex];
-            if (right < this.heap.length && rightItem !== undefined && newMinItem !== undefined && this.compare(rightItem, newMinItem) < 0) {
+            if (
+                right < this.heap.length &&
+                rightItem !== undefined &&
+                newMinItem !== undefined &&
+                this.compare(rightItem, newMinItem) < 0
+            ) {
                 minIndex = right;
             }
 
@@ -82,11 +96,19 @@ export class MinPriorityQueue<T> {
         }
     }
 
+    /**
+     * Insert a value into the priority queue.
+     * @param value - The value to insert
+     */
     insert(value: T): void {
         this.heap.push(value);
         this.heapifyUp(this.heap.length - 1);
     }
 
+    /**
+     * Remove and return the minimum value from the priority queue.
+     * @returns The minimum value, or undefined if the queue is empty
+     */
     extractMin(): T | undefined {
         if (this.heap.length === 0) {
             return undefined;
@@ -106,14 +128,26 @@ export class MinPriorityQueue<T> {
         return min;
     }
 
+    /**
+     * View the minimum value without removing it.
+     * @returns The minimum value, or undefined if the queue is empty
+     */
     peek(): T | undefined {
         return this.heap[0];
     }
 
+    /**
+     * Check if the priority queue is empty.
+     * @returns True if the queue has no items, false otherwise
+     */
     isEmpty(): boolean {
         return this.heap.length === 0;
     }
 
+    /**
+     * Get the number of items in the priority queue.
+     * @returns The number of items currently in the queue
+     */
     size(): number {
         return this.heap.length;
     }