@graphty/algorithms 1.0.1 → 1.2.0

package/src/pathfinding/astar.ts

@@ -0,0 +1,229 @@
+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
+ * @param heuristic - Heuristic function that estimates distance from node to goal
+ * @returns Object containing the shortest path and its cost, or null if no path exists
+ *
+ * Time Complexity: O(E) with good heuristic, O(b^d) worst case
+ * Space Complexity: O(V)
+ */
+export function astar<T>(
+    graph: Map<T, Map<T, number>>,
+    start: T,
+    goal: T,
+    heuristic: (node: T, goal: T) => number,
+): {path: T[], cost: number} | null {
+    if (!graph.has(start) || !graph.has(goal)) {
+        return null;
+    }
+
+    // Priority queue ordered by f(n) = g(n) + h(n)
+    const openSet = new MinPriorityQueue<graphNode<T>>();
+    const gScore = new Map<T, number>(); // Cost from start to node
+    const fScore = new Map<T, number>(); // Estimated total cost
+    const cameFrom = new Map<T, T>();
+    const closedSet = new Set<T>();
+
+    // Initialize start node
+    gScore.set(start, 0);
+    fScore.set(start, heuristic(start, goal));
+    const startFScore = fScore.get(start);
+    if (startFScore === undefined) {
+        return null;
+    }
+
+    openSet.insert({node: start, distance: startFScore});
+
+    while (!openSet.isEmpty()) {
+        const current = openSet.extractMin();
+        if (!current) {
+            break;
+        }
+
+        const currentNode = current.node;
+
+        if (currentNode === goal) {
+            // Reconstruct path
+            const path = pathfindingUtils.reconstructPath(cameFrom, goal);
+            const goalCost = gScore.get(goal);
+            if (goalCost === undefined) {
+                return null;
+            }
+
+            return {path, cost: goalCost};
+        }
+
+        closedSet.add(currentNode);
+
+        const neighbors = graph.get(currentNode);
+        if (!neighbors) {
+            continue;
+        }
+
+        for (const [neighbor, weight] of neighbors) {
+            if (closedSet.has(neighbor)) {
+                continue;
+            }
+
+            const currentNodeGScore = gScore.get(currentNode);
+            if (currentNodeGScore === undefined) {
+                continue;
+            }
+
+            const tentativeGScore = currentNodeGScore + weight;
+            const currentGScore = gScore.get(neighbor) ?? Infinity;
+
+            if (tentativeGScore < currentGScore) {
+                // This path to neighbor is better
+                cameFrom.set(neighbor, currentNode);
+                gScore.set(neighbor, tentativeGScore);
+                fScore.set(neighbor, tentativeGScore + heuristic(neighbor, goal));
+
+                // Add to open set if not already there
+                const neighborFScore = fScore.get(neighbor);
+                if (neighborFScore !== undefined) {
+                    openSet.insert({node: neighbor, distance: neighborFScore});
+                }
+            }
+        }
+    }
+
+    return null; // No path found
+}
+
+/**
+ * A* pathfinding with path reconstruction details
+ * Returns detailed information about the search process
+ */
+export function astarWithDetails<T>(
+    graph: Map<T, Map<T, number>>,
+    start: 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>;
+    } {
+    const openSet = new MinPriorityQueue<graphNode<T>>();
+    const gScore = new Map<T, number>();
+    const fScore = new Map<T, number>();
+    const cameFrom = new Map<T, T>();
+    const closedSet = new Set<T>();
+
+    gScore.set(start, 0);
+    fScore.set(start, heuristic(start, goal));
+    const startFScore = fScore.get(start);
+    if (startFScore === undefined) {
+        return {
+            path: null,
+            cost: Infinity,
+            visited: new Set(),
+            gScores: new Map(),
+            fScores: new Map(),
+        };
+    }
+
+    openSet.insert({node: start, distance: startFScore});
+
+    while (!openSet.isEmpty()) {
+        const current = openSet.extractMin();
+        if (!current) {
+            break;
+        }
+
+        const currentNode = current.node;
+
+        if (currentNode === goal) {
+            const path = pathfindingUtils.reconstructPath(cameFrom, goal);
+            return {
+                path,
+                cost: gScore.get(goal) ?? Infinity,
+                visited: closedSet,
+                gScores: gScore,
+                fScores: fScore,
+            };
+        }
+
+        closedSet.add(currentNode);
+
+        const neighbors = graph.get(currentNode);
+        if (!neighbors) {
+            continue;
+        }
+
+        for (const [neighbor, weight] of neighbors) {
+            if (closedSet.has(neighbor)) {
+                continue;
+            }
+
+            const currentNodeGScore = gScore.get(currentNode);
+            if (currentNodeGScore === undefined) {
+                continue;
+            }
+
+            const tentativeGScore = currentNodeGScore + weight;
+            const currentGScore = gScore.get(neighbor) ?? Infinity;
+
+            if (tentativeGScore < currentGScore) {
+                cameFrom.set(neighbor, currentNode);
+                gScore.set(neighbor, tentativeGScore);
+                fScore.set(neighbor, tentativeGScore + heuristic(neighbor, goal));
+                const neighborFScore = fScore.get(neighbor);
+                if (neighborFScore !== undefined) {
+                    openSet.insert({node: neighbor, distance: neighborFScore});
+                }
+            }
+        }
+    }
+
+    return {
+        path: null,
+        cost: Infinity,
+        visited: closedSet,
+        gScores: gScore,
+        fScores: fScore,
+    };
+}
+
+/**
+ * Common heuristic functions for A*
+ */
+export const heuristics = {
+    /**
+   * Manhattan distance heuristic for grid-based graphs
+   */
+    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: (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: (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: <T>(_a: T, _b: T): number => 0,
+};

package/src/pathfinding/index.ts

@@ -0,0 +1,2 @@
+export * from "./astar.js";
+export * from "./utils.js";

package/src/pathfinding/utils.ts

@@ -0,0 +1,87 @@
+/**
+ * Utility functions for pathfinding algorithms
+ */
+
+export const pathfindingUtils = {
+    /**
+   * Reconstructs a path from start to goal using the cameFrom map
+   */
+    reconstructPath<T>(cameFrom: Map<T, T>, goal: T): T[] {
+        const path: T[] = [goal];
+        let current = goal;
+
+        while (cameFrom.has(current)) {
+            const next = cameFrom.get(current);
+            if (next === undefined) {
+                break;
+            }
+
+            current = next;
+            path.unshift(current);
+        }
+
+        return path;
+    },
+
+    /**
+   * Creates a grid graph for testing pathfinding algorithms
+   */
+    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++) {
+            for (let y = 0; y < height; y++) {
+                const node = `${String(x)},${String(y)}`;
+                if (obstacles.has(node)) {
+                    continue;
+                }
+
+                const neighbors = new Map<string, number>();
+
+                // Add 4-directional neighbors
+                const directions = [
+                    [0, 1], [1, 0], [0, -1], [-1, 0],
+                ];
+
+                for (const dir of directions) {
+                    const dx = dir[0];
+                    const dy = dir[1];
+                    if (dx === undefined || dy === undefined) {
+                        continue;
+                    }
+
+                    const nx = x + dx;
+                    const ny = y + dy;
+                    const neighbor = `${String(nx)},${String(ny)}`;
+
+                    if (nx >= 0 && nx < width && ny >= 0 && ny < height && !obstacles.has(neighbor)) {
+                        neighbors.set(neighbor, 1); // Unit cost for grid movement
+                    }
+                }
+
+                graph.set(node, neighbors);
+            }
+        }
+
+        return graph;
+    },
+
+    /**
+   * Parses a grid coordinate string
+   */
+    parseGridCoordinate(coord: string): [number, number] {
+        const parts = coord.split(",").map(Number);
+        const x = parts[0];
+        const y = parts[1];
+        if (x === undefined || y === undefined) {
+            throw new Error(`Invalid coordinate: ${coord}`);
+        }
+
+        return [x, y];
+    },
+};
+