@graphty/algorithms 1.3.1 → 1.5.0

package/src/optimized/direction-optimized-bfs.ts

@@ -1,6 +1,6 @@
-import type {NodeId} from "../types/index.js";
-import {CompactDistanceArray, GraphBitSet} from "./bit-packed.js";
-import {CSRGraph} from "./csr-graph.js";
+import type { NodeId } from "../types/index.js";
+import { CompactDistanceArray, GraphBitSet } from "./bit-packed.js";
+import { CSRGraph } from "./csr-graph.js";
 
 /**
  * Options for Direction-Optimized BFS
@@ -40,6 +40,11 @@ export class DirectionOptimizedBFS<TNodeId = NodeId> {
     private nextFrontier: GraphBitSet; // Next level frontier
     private distances: CompactDistanceArray;
 
+    /**
+     * Creates a new DirectionOptimizedBFS instance.
+     * @param graph - The CSR graph to perform BFS on
+     * @param options - Optional configuration for switching thresholds
+     */
     constructor(graph: CSRGraph<TNodeId>, options?: DirectionOptimizedBFSOptions) {
         this.graph = graph;
         this.alpha = options?.alpha ?? 15;
@@ -53,8 +58,10 @@ export class DirectionOptimizedBFS<TNodeId = NodeId> {
     }
 
     /**
-   * Perform BFS from a single source
-   */
+     * Perform BFS from a single source node.
+     * @param source - The source node ID to start the BFS from
+     * @returns The BFS result containing distances and parent pointers
+     */
     search(source: TNodeId): BFSResult<TNodeId> {
         const sourceIndex = this.graph.nodeToIndex(source);
         this.parent[sourceIndex] = -2; // Mark as source
@@ -76,8 +83,7 @@ export class DirectionOptimizedBFS<TNodeId = NodeId> {
 
             if (useBottomUp) {
                 // Check if we should switch back to top-down
-                if (awakeCount >= oldAwakeCount ||
-            awakeCount > this.graph.nodeCount() / this.beta) {
+                if (awakeCount >= oldAwakeCount || awakeCount > this.graph.nodeCount() / this.beta) {
                     useBottomUp = false;
                 }
             } else {
@@ -106,8 +112,9 @@ export class DirectionOptimizedBFS<TNodeId = NodeId> {
     }
 
     /**
-   * Top-down BFS step - explore from frontier
-   */
+     * Top-down BFS step - explore from frontier.
+     * @returns The scout count (total degree of newly discovered nodes)
+     */
     private topDownStep(): number {
         let scoutCount = 0;
 
@@ -129,8 +136,9 @@ export class DirectionOptimizedBFS<TNodeId = NodeId> {
     }
 
     /**
-   * Bottom-up BFS step - check unvisited nodes
-   */
+     * Bottom-up BFS step - check unvisited nodes for frontier neighbors.
+     * @returns The number of newly discovered nodes
+     */
     private bottomUpStep(): number {
         const nodeCount = this.graph.nodeCount();
         let awakeCount = 0;
@@ -156,8 +164,9 @@ export class DirectionOptimizedBFS<TNodeId = NodeId> {
     }
 
     /**
-   * Calculate edges to check for switching heuristic
-   */
+     * Calculate edges to check for switching heuristic.
+     * @returns The total number of outgoing edges from frontier nodes
+     */
     private calculateEdgesToCheck(): number {
         let count = 0;
         for (const node of this.frontier) {
@@ -167,8 +176,9 @@ export class DirectionOptimizedBFS<TNodeId = NodeId> {
     }
 
     /**
-   * Build result map from internal data structures
-   */
+     * Build result map from internal data structures.
+     * @returns The BFS result containing distances and parent pointers
+     */
     private buildResult(): BFSResult<TNodeId> {
         const distances = new Map<TNodeId, number>();
         const parents = new Map<TNodeId, TNodeId | null>();
@@ -194,14 +204,16 @@ export class DirectionOptimizedBFS<TNodeId = NodeId> {
             }
         }
 
-        return {distances, parents, visitedCount};
+        return { distances, parents, visitedCount };
     }
 
     /**
-   * Perform multi-source BFS
-   */
+     * Perform multi-source BFS from multiple source nodes.
+     * @param sources - Array of source node IDs to start the BFS from
+     * @returns The BFS result containing distances and parent pointers
+     */
     searchMultiple(sources: TNodeId[]): BFSResult<TNodeId> {
-    // Initialize multiple sources
+        // Initialize multiple sources
         for (const source of sources) {
             const sourceIndex = this.graph.nodeToIndex(source);
             this.parent[sourceIndex] = -2; // Mark as source
@@ -228,8 +240,7 @@ export class DirectionOptimizedBFS<TNodeId = NodeId> {
             oldAwakeCount = awakeCount;
 
             if (useBottomUp) {
-                if (awakeCount >= oldAwakeCount ||
-            awakeCount > this.graph.nodeCount() / this.beta) {
+                if (awakeCount >= oldAwakeCount || awakeCount > this.graph.nodeCount() / this.beta) {
                     useBottomUp = false;
                 }
             } else {
@@ -256,8 +267,8 @@ export class DirectionOptimizedBFS<TNodeId = NodeId> {
     }
 
     /**
-   * Reset internal state for reuse
-   */
+     * Reset internal state for reuse
+     */
     reset(): void {
         this.parent.fill(-1);
         this.frontier.clear();
@@ -267,7 +278,11 @@ export class DirectionOptimizedBFS<TNodeId = NodeId> {
 }
 
 /**
- * Convenience function for single-source BFS
+ * Convenience function for single-source BFS.
+ * @param graph - The CSR graph to perform BFS on
+ * @param source - The source node ID to start the BFS from
+ * @param options - Optional configuration for switching thresholds
+ * @returns The BFS result containing distances and parent pointers
  */
 export function directionOptimizedBFS<TNodeId = NodeId>(
     graph: CSRGraph<TNodeId>,
@@ -279,7 +294,11 @@ export function directionOptimizedBFS<TNodeId = NodeId>(
 }
 
 /**
- * Convenience function for multi-source BFS
+ * Convenience function for multi-source BFS.
+ * @param graph - The CSR graph to perform BFS on
+ * @param sources - Array of source node IDs to start the BFS from
+ * @param options - Optional configuration for switching thresholds
+ * @returns The BFS result containing distances and parent pointers
  */
 export function directionOptimizedBFSMultiple<TNodeId = NodeId>(
     graph: CSRGraph<TNodeId>,

package/src/optimized/graph-adapter.ts

@@ -1,6 +1,6 @@
-import type {Graph} from "../core/graph.js";
-import type {NodeId} from "../types/index.js";
-import {CSRGraph, type ReadonlyGraph} from "./csr-graph.js";
+import type { Graph } from "../core/graph.js";
+import type { NodeId } from "../types/index.js";
+import { CSRGraph, type ReadonlyGraph } from "./csr-graph.js";
 
 /**
  * Adapter to convert standard Graph to CSR format
@@ -10,8 +10,12 @@ import {CSRGraph, type ReadonlyGraph} from "./csr-graph.js";
 export class GraphAdapter<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
     private csrGraph: CSRGraph<TNodeId>;
 
+    /**
+     * Creates a new GraphAdapter that wraps or converts a graph to CSR format.
+     * @param graph - The graph to adapt (either standard Graph or ReadonlyGraph)
+     */
     constructor(graph: Graph | ReadonlyGraph<TNodeId>) {
-    // Check if already a CSRGraph
+        // Check if already a CSRGraph
         if (graph instanceof CSRGraph) {
             this.csrGraph = graph as CSRGraph<TNodeId>;
         } else {
@@ -21,8 +25,10 @@ export class GraphAdapter<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
     }
 
     /**
-   * Convert standard graph to CSR format
-   */
+     * Convert standard graph to CSR format.
+     * @param graph - The graph to convert
+     * @returns A new CSRGraph instance
+     */
     private convertToCSR(graph: Graph | ReadonlyGraph<TNodeId>): CSRGraph<TNodeId> {
         const adjacencyList = new Map<TNodeId, TNodeId[]>();
         const weights = new Map<string, number>();
@@ -31,7 +37,7 @@ export class GraphAdapter<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
         if ("nodes" in graph && typeof graph.nodes === "function") {
             // Build adjacency list from Graph
             for (const node of graph.nodes()) {
-                const nodeId = (node as {id: TNodeId}).id;
+                const nodeId = (node as { id: TNodeId }).id;
                 const neighbors: TNodeId[] = [];
 
                 const graphTyped = graph as Graph;
@@ -53,7 +59,7 @@ export class GraphAdapter<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
             // Handle ReadonlyGraph with nodeIds method
             interface ReadonlyGraphWithNodeIds {
                 nodeIds(): Iterable<TNodeId>;
-                edges?(): Iterable<{source: TNodeId, target: TNodeId, weight?: number}>;
+                edges?(): Iterable<{ source: TNodeId; target: TNodeId; weight?: number }>;
             }
             const readonlyGraph = graph as ReadonlyGraphWithNodeIds;
             for (const nodeId of readonlyGraph.nodeIds()) {
@@ -78,37 +84,71 @@ export class GraphAdapter<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
     }
 
     // Delegate all methods to CSR implementation
+    /**
+     * Get the total number of nodes in the graph.
+     * @returns The number of nodes
+     */
     nodeCount(): number {
         return this.csrGraph.nodeCount();
     }
 
+    /**
+     * Get the total number of edges in the graph.
+     * @returns The number of edges
+     */
     edgeCount(): number {
         return this.csrGraph.edgeCount();
     }
 
+    /**
+     * Check if a node exists in the graph.
+     * @param nodeId - The node ID to check
+     * @returns True if the node exists, false otherwise
+     */
     hasNode(nodeId: TNodeId): boolean {
         return this.csrGraph.hasNode(nodeId);
     }
 
+    /**
+     * Check if an edge exists between two nodes.
+     * @param source - The source node ID
+     * @param target - The target node ID
+     * @returns True if the edge exists, false otherwise
+     */
     hasEdge(source: TNodeId, target: TNodeId): boolean {
         return this.csrGraph.hasEdge(source, target);
     }
 
+    /**
+     * Get neighbors of a node as node IDs.
+     * @param nodeId - The node ID to get neighbors for
+     * @returns An iterator over neighbor node IDs
+     */
     neighbors(nodeId: TNodeId): IterableIterator<TNodeId> {
         return this.csrGraph.neighbors(nodeId);
     }
 
+    /**
+     * Get the out-degree (number of outgoing edges) of a node.
+     * @param nodeId - The node ID to get the out-degree for
+     * @returns The number of outgoing edges from the node
+     */
     outDegree(nodeId: TNodeId): number {
         return this.csrGraph.outDegree(nodeId);
     }
 
+    /**
+     * Get all nodes in the graph.
+     * @returns An iterator over all node IDs
+     */
     nodes(): IterableIterator<TNodeId> {
         return this.csrGraph.nodes();
     }
 
     /**
-   * Get the underlying CSR graph
-   */
+     * Get the underlying CSR graph.
+     * @returns The CSRGraph instance used internally
+     */
     getCSRGraph(): CSRGraph<TNodeId> {
         return this.csrGraph;
     }
@@ -133,31 +173,36 @@ export interface GraphAlgorithmConfig {
 }
 
 /**
- * Configure optimizations globally
+ * Configure optimizations globally.
  * @deprecated This function is a no-op and will be removed in a future version
+ * @param _config - The configuration object (ignored)
  */
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
 export function configureOptimizations(_config: GraphAlgorithmConfig): void {
     // No-op for backward compatibility
 }
 
 /**
- * Get current configuration
+ * Get current configuration.
  * @deprecated This function returns empty config and will be removed in a future version
+ * @returns An empty configuration object
  */
 export function getOptimizationConfig(): GraphAlgorithmConfig {
     return {};
 }
 
 /**
- * Check if a graph is already in CSR format
+ * Check if a graph is already in CSR format.
+ * @param graph - The graph to check
+ * @returns True if the graph is a CSRGraph instance
  */
 export function isCSRGraph<TNodeId = NodeId>(graph: unknown): graph is CSRGraph<TNodeId> {
     return graph instanceof CSRGraph;
 }
 
 /**
- * Convert any graph to CSR format
+ * Convert any graph to CSR format.
+ * @param graph - The graph to convert
+ * @returns A CSRGraph instance (either the original if already CSR, or a new converted one)
  */
 export function toCSRGraph<TNodeId = NodeId>(
     graph: Graph | ReadonlyGraph<TNodeId> | CSRGraph<TNodeId>,
@@ -171,7 +216,10 @@ export function toCSRGraph<TNodeId = NodeId>(
 }
 
 /**
- * Create an optimized graph from nodes and edges
+ * Create an optimized graph from nodes and edges.
+ * @param nodes - Array of node IDs
+ * @param edges - Array of edge tuples [source, target, weight?]
+ * @returns A new CSRGraph instance
  */
 export function createOptimizedGraph<TNodeId = NodeId>(
     nodes: TNodeId[],

package/src/optimized/index.ts

@@ -8,11 +8,9 @@
  */
 
 // Configuration and optimization control
-export {
-    configureOptimizations,
-    getOptimizationConfig,
-    type GraphAlgorithmConfig,
-} from "./graph-adapter.js";
+// These deprecated functions are intentionally re-exported for backward compatibility
+// eslint-disable-next-line @typescript-eslint/no-deprecated
+export { configureOptimizations, getOptimizationConfig, type GraphAlgorithmConfig } from "./graph-adapter.js";
 
 // Note: The main BFS functions in algorithms/traversal/bfs.ts automatically
 // use these optimizations for large graphs (>10k nodes) when optimizations are enabled.
@@ -28,9 +26,9 @@ export {
 // for large graphs without requiring manual configuration.
 
 // Export data structures for advanced users
-export {CompactDistanceArray, GraphBitSet, VisitedBitArray} from "./bit-packed.js";
-export {CSRGraph} from "./csr-graph.js";
-export {DirectionOptimizedBFS} from "./direction-optimized-bfs.js";
+export { CompactDistanceArray, GraphBitSet, VisitedBitArray } from "./bit-packed.js";
+export { CSRGraph } from "./csr-graph.js";
+export { DirectionOptimizedBFS } from "./direction-optimized-bfs.js";
 
 // Export utilities
-export {createOptimizedGraph, isCSRGraph, toCSRGraph} from "./graph-adapter.js";
+export { createOptimizedGraph, isCSRGraph, toCSRGraph } from "./graph-adapter.js";

package/src/pathfinding/astar.ts

@@ -1,11 +1,10 @@
-import {graphNode} from "../utils/graphNode.js";
-import {MinPriorityQueue} from "../utils/priorityQueue.js";
-import {pathfindingUtils} from "./utils.js";
+import { graphNode } from "../utils/graphNode.js";
+import { MinPriorityQueue } from "../utils/priorityQueue.js";
+import { pathfindingUtils } from "./utils.js";
 
 /**
  * A* pathfinding algorithm
  * Finds the shortest path from start to goal using a heuristic function
- *
  * @param graph - The graph represented as an adjacency list
  * @param start - The starting node
  * @param goal - The goal node
@@ -20,7 +19,7 @@ export function astar<T>(
     start: T,
     goal: T,
     heuristic: (node: T, goal: T) => number,
-): {path: T[], cost: number} | null {
+): { path: T[]; cost: number } | null {
     if (!graph.has(start) || !graph.has(goal)) {
         return null;
     }
@@ -40,7 +39,7 @@ export function astar<T>(
         return null;
     }
 
-    openSet.insert({node: start, distance: startFScore});
+    openSet.insert({ node: start, distance: startFScore });
 
     while (!openSet.isEmpty()) {
         const current = openSet.extractMin();
@@ -58,7 +57,7 @@ export function astar<T>(
                 return null;
             }
 
-            return {path, cost: goalCost};
+            return { path, cost: goalCost };
         }
 
         closedSet.add(currentNode);
@@ -90,7 +89,7 @@ export function astar<T>(
                 // Add to open set if not already there
                 const neighborFScore = fScore.get(neighbor);
                 if (neighborFScore !== undefined) {
-                    openSet.insert({node: neighbor, distance: neighborFScore});
+                    openSet.insert({ node: neighbor, distance: neighborFScore });
                 }
             }
         }
@@ -102,6 +101,11 @@ export function astar<T>(
 /**
  * A* pathfinding with path reconstruction details
  * Returns detailed information about the search process
+ * @param graph - The graph represented as an adjacency list
+ * @param start - The starting node
+ * @param goal - The goal node
+ * @param heuristic - Heuristic function that estimates distance from node to goal
+ * @returns Detailed result including path, cost, visited nodes, and score maps
  */
 export function astarWithDetails<T>(
     graph: Map<T, Map<T, number>>,
@@ -109,12 +113,12 @@ export function astarWithDetails<T>(
     goal: T,
     heuristic: (node: T, goal: T) => number,
 ): {
-        path: T[] | null;
-        cost: number;
-        visited: Set<T>;
-        gScores: Map<T, number>;
-        fScores: Map<T, number>;
-    } {
+    path: T[] | null;
+    cost: number;
+    visited: Set<T>;
+    gScores: Map<T, number>;
+    fScores: Map<T, number>;
+} {
     const openSet = new MinPriorityQueue<graphNode<T>>();
     const gScore = new Map<T, number>();
     const fScore = new Map<T, number>();
@@ -134,7 +138,7 @@ export function astarWithDetails<T>(
         };
     }
 
-    openSet.insert({node: start, distance: startFScore});
+    openSet.insert({ node: start, distance: startFScore });
 
     while (!openSet.isEmpty()) {
         const current = openSet.extractMin();
@@ -181,7 +185,7 @@ export function astarWithDetails<T>(
                 fScore.set(neighbor, tentativeGScore + heuristic(neighbor, goal));
                 const neighborFScore = fScore.get(neighbor);
                 if (neighborFScore !== undefined) {
-                    openSet.insert({node: neighbor, distance: neighborFScore});
+                    openSet.insert({ node: neighbor, distance: neighborFScore });
                 }
             }
         }
@@ -201,29 +205,40 @@ export function astarWithDetails<T>(
  */
 export const heuristics = {
     /**
-   * Manhattan distance heuristic for grid-based graphs
-   */
+     * Manhattan distance heuristic for grid-based graphs
+     * @param a - First coordinate as [x, y] tuple
+     * @param b - Second coordinate as [x, y] tuple
+     * @returns The Manhattan distance between the two points
+     */
     manhattan: (a: [number, number], b: [number, number]): number => {
         return Math.abs(a[0] - b[0]) + Math.abs(a[1] - b[1]);
     },
 
     /**
-   * Euclidean distance heuristic
-   */
+     * Euclidean distance heuristic
+     * @param a - First coordinate as [x, y] tuple
+     * @param b - Second coordinate as [x, y] tuple
+     * @returns The Euclidean distance between the two points
+     */
     euclidean: (a: [number, number], b: [number, number]): number => {
         return Math.sqrt(Math.pow(a[0] - b[0], 2) + Math.pow(a[1] - b[1], 2));
     },
 
     /**
-   * Chebyshev distance heuristic (diagonal movement allowed)
-   */
+     * Chebyshev distance heuristic (diagonal movement allowed)
+     * @param a - First coordinate as [x, y] tuple
+     * @param b - Second coordinate as [x, y] tuple
+     * @returns The Chebyshev distance between the two points
+     */
     chebyshev: (a: [number, number], b: [number, number]): number => {
         return Math.max(Math.abs(a[0] - b[0]), Math.abs(a[1] - b[1]));
     },
 
     /**
-   * Zero heuristic (makes A* behave like Dijkstra)
-   */
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+     * Zero heuristic (makes A* behave like Dijkstra)
+     * @param _a - First node (unused)
+     * @param _b - Second node (unused)
+     * @returns Always returns 0
+     */
     zero: <T>(_a: T, _b: T): number => 0,
 };

package/src/pathfinding/utils.ts

@@ -4,8 +4,11 @@
 
 export const pathfindingUtils = {
     /**
-   * Reconstructs a path from start to goal using the cameFrom map
-   */
+     * Reconstructs a path from start to goal using the cameFrom map
+     * @param cameFrom - Map of each node to its predecessor on the path
+     * @param goal - The goal node to reconstruct the path to
+     * @returns An array of nodes representing the path from start to goal
+     */
     reconstructPath<T>(cameFrom: Map<T, T>, goal: T): T[] {
         const path: T[] = [goal];
         let current = goal;
@@ -24,13 +27,13 @@ export const pathfindingUtils = {
     },
 
     /**
-   * Creates a grid graph for testing pathfinding algorithms
-   */
-    createGridGraph(
-        width: number,
-        height: number,
-        obstacles = new Set<string>(),
-    ): Map<string, Map<string, number>> {
+     * Creates a grid graph for testing pathfinding algorithms
+     * @param width - The width of the grid
+     * @param height - The height of the grid
+     * @param obstacles - Set of obstacle coordinates as "x,y" strings
+     * @returns A grid graph with 4-directional movement
+     */
+    createGridGraph(width: number, height: number, obstacles = new Set<string>()): Map<string, Map<string, number>> {
         const graph = new Map<string, Map<string, number>>();
 
         for (let x = 0; x < width; x++) {
@@ -44,7 +47,10 @@ export const pathfindingUtils = {
 
                 // Add 4-directional neighbors
                 const directions = [
-                    [0, 1], [1, 0], [0, -1], [-1, 0],
+                    [0, 1],
+                    [1, 0],
+                    [0, -1],
+                    [-1, 0],
                 ];
 
                 for (const dir of directions) {
@@ -71,8 +77,10 @@ export const pathfindingUtils = {
     },
 
     /**
-   * Parses a grid coordinate string
-   */
+     * Parses a grid coordinate string
+     * @param coord - The coordinate string in "x,y" format
+     * @returns A tuple of [x, y] coordinates
+     */
     parseGridCoordinate(coord: string): [number, number] {
         const parts = coord.split(",").map(Number);
         const x = parts[0];
@@ -84,4 +92,3 @@ export const pathfindingUtils = {
         return [x, y];
     },
 };
-