more tests; fixed an infinite loop when no path found

Author: j50n

README.md

@@ -1,12 +1,9 @@
 # Dijkstra's Shortest Path Algorithm
 
-A pretty good implementation of Dijkstra's shortest-path algorithm.
+A pretty good implementation of Dijkstra's shortest-path algorithm for Deno.
 
-This implementation is designed to process large in-memory graphs. It will
-perform reasonably well even when the number of edges is in the millions. Using
-numbered indexes for nodes, rather than string labels or objects, was by design.
-This reduced the memory footprint needed for the graph and speeds up graph
-creation and lookups.
+This implementation is able to process large in-memory graphs. It will
+perform reasonably well even when the number of edges is in the millions. 
 
 This code was adapted from Typescript/Deno from
 [A Walkthrough of Dijkstra's Algorithm (In JavaScript!)](https://medium.com/@adriennetjohnson/a-walkthrough-of-dijkstras-algorithm-in-javascript-e94b74192026)

dijkstra.example.test.ts

@@ -0,0 +1,38 @@
+import { DijkstraShortestPathSolver } from "./dijkstra.ts";
+import { assertEquals } from "./deps.ts";
+
+const FULLSTACK = 0;
+const DIGINN = 1;
+const DUBLINER = 2;
+const STARBUCKS = 3;
+const CAFEGRUMPY = 4;
+const INSOMNIACOOKIES = 5;
+
+const cafes = DijkstraShortestPathSolver.init(6);
+
+cafes.addBidirEdge(DIGINN, FULLSTACK, 7);
+cafes.addBidirEdge(FULLSTACK, STARBUCKS, 6);
+cafes.addBidirEdge(DIGINN, DUBLINER, 4);
+cafes.addBidirEdge(FULLSTACK, DUBLINER, 2);
+cafes.addBidirEdge(DUBLINER, STARBUCKS, 3);
+cafes.addBidirEdge(DIGINN, CAFEGRUMPY, 9);
+cafes.addBidirEdge(CAFEGRUMPY, INSOMNIACOOKIES, 5);
+cafes.addBidirEdge(DUBLINER, INSOMNIACOOKIES, 7);
+cafes.addBidirEdge(STARBUCKS, INSOMNIACOOKIES, 6);
+
+Deno.test("demonstrate finding shortest path", () => {
+  const path = cafes.calculateFor(FULLSTACK).shortestPathTo(CAFEGRUMPY);
+  assertEquals(
+    path,
+    [FULLSTACK, DUBLINER, INSOMNIACOOKIES, CAFEGRUMPY],
+    "shortest path from FULLSTACK to CAFEGRUMPY",
+  );
+});
+
+Deno.test("demonstrate finding the weight of the shortest path", () => {
+  assertEquals(
+    cafes.calculateFor(FULLSTACK).totalWeight(CAFEGRUMPY),
+    14,
+    "weight of the shortest path",
+  );
+});

dijkstra.test.ts

@@ -1,38 +1,31 @@
 import { DijkstraShortestPathSolver } from "./dijkstra.ts";
-import { assertEquals } from "./deps.ts";
+import { assertEquals, assertThrows } from "./deps.ts";
 
-const FULLSTACK = 0;
-const DIGINN = 1;
-const DUBLINER = 2;
-const STARBUCKS = 3;
-const CAFEGRUMPY = 4;
-const INSOMNIACOOKIES = 5;
+Deno.test("graph contains at least 2 nodes", () => {
+  assertThrows(() => DijkstraShortestPathSolver.init(1), RangeError);
+});
 
-const cafes = DijkstraShortestPathSolver.init(6);
+Deno.test("throws if no path found", () => {
+  const solver = DijkstraShortestPathSolver.init(2);
+  const shortestPath = solver.calculateFor(0);
+  assertThrows(() => shortestPath.shortestPathTo(1), Error);
+});
 
-cafes.addBidirEdge(DIGINN, FULLSTACK, 7);
-cafes.addBidirEdge(FULLSTACK, STARBUCKS, 6);
-cafes.addBidirEdge(DIGINN, DUBLINER, 4);
-cafes.addBidirEdge(FULLSTACK, DUBLINER, 2);
-cafes.addBidirEdge(DUBLINER, STARBUCKS, 3);
-cafes.addBidirEdge(DIGINN, CAFEGRUMPY, 9);
-cafes.addBidirEdge(CAFEGRUMPY, INSOMNIACOOKIES, 5);
-cafes.addBidirEdge(DUBLINER, INSOMNIACOOKIES, 7);
-cafes.addBidirEdge(STARBUCKS, INSOMNIACOOKIES, 6);
+Deno.test("some paths are valid, others are not", () => {
+  const solver = DijkstraShortestPathSolver.init(3);
+  solver.addEdge(0, 2, 42);
 
-Deno.test("demonstrate finding shortest path", () => {
-  const path = cafes.calculateFor(FULLSTACK).shortestPathTo(CAFEGRUMPY);
-  assertEquals(
-    path,
-    [FULLSTACK, DUBLINER, INSOMNIACOOKIES, CAFEGRUMPY],
-    "shortest path from FULLSTACK to CAFEGRUMPY",
-  );
+  const shortestPath = solver.calculateFor(0);
+  assertThrows(() => shortestPath.shortestPathTo(1), Error);
+  assertEquals(shortestPath.shortestPathTo(2), [0, 2]);
+  assertEquals(shortestPath.totalWeight(2), 42);
 });
 
-Deno.test("demonstrate finding the weight of the shortest path", () => {
-  assertEquals(
-    cafes.calculateFor(FULLSTACK).weights[CAFEGRUMPY],
-    14,
-    "weight of the shortest path",
-  );
+Deno.test("finds shortest path between two nodes", () => {
+  const solver = DijkstraShortestPathSolver.init(2);
+  solver.addEdge(0, 1, 1);
+
+  const shortestPath = solver.calculateFor(0);
+  assertEquals(shortestPath.shortestPathTo(1), [0, 1]);
+  assertEquals(shortestPath.totalWeight(1), 1);
 });

dijkstra.ts

@@ -22,6 +22,10 @@ interface IPath {
  *
  * Nodes are numbered from 0 to n-1.
  *
+ * This supports having a template graph and adding variable nodes for processing with {@link DijkstraShortestPathSolver.clone}
+ * and {@link DijkstraShortestPathSolver.addNode}. This operations are additive. There is not a good general way to remove nodes
+ * and edges (subtractive) once they have been added.
+ *
  * Adapted from https://medium.com/@adriennetjohnson/a-walkthrough-of-dijkstras-algorithm-in-javascript-e94b74192026
  * This has been made much faster by treating nodes as an index rather than a string (name). We use `tinyqueue`
  * as our priority queue. All map-likes have been eliminated, but there are still object references. So this is
@@ -39,14 +43,23 @@ export class DijkstraShortestPathSolver {
    * @returns A new solver.
    */
   static init(nodes: number): DijkstraShortestPathSolver {
+    if (nodes < 2) {
+      throw new RangeError(`solver requires at least 2 nodes: ${nodes}`);
+    }
+
     return new DijkstraShortestPathSolver(
       new Array(nodes).fill(null).map((_v) => new Array(0)),
     );
   }
 
   /**
    * A clone of this solver.
+   *
+   * This clone operation is generally very fast, as it is based on array shallow copies.
+   *
    * @returns A cloned solver.
+   *
+   * @see {@link DijkstraShortestPathSolver.addNode}
    */
   clone(): DijkstraShortestPathSolver {
     return new DijkstraShortestPathSolver(
@@ -61,6 +74,23 @@ export class DijkstraShortestPathSolver {
     return this.adjacencyList.length;
   }
 
+  /**
+   * Add a new node to the graph.
+   *
+   * The typical use case for this is when you have a static graph and you need to add a small number
+   * of additional nodes and edges prior to each compute. You would clone the solver, add your variable
+   * nodes and edges, and then solve, saving you the time of having to recreate the whole graph from
+   * scratch each time.
+   *
+   * @returns The index of the new node.
+   *
+   * @see {@link DijkstraShortestPathSolver.clone}
+   */
+  addNode(): number {
+    this.adjacencyList.push(new Array(0));
+    return this.nodes - 1;
+  }
+
   /**
    * Add an edge (in one direction).
    * @param fromNode Starting node.
@@ -135,23 +165,21 @@ export class DijkstraShortestPathSolver {
 
     while (pq.length !== 0) {
       const shortestStep = pq.pop();
-      if (shortestStep === undefined) {
-        throw new Error("shortest-step undefined");
-      }
-      const currentNode = shortestStep.toNode;
 
-      this.adjacencyList[currentNode].forEach((neighbor) => {
+      const currentNode = shortestStep!.toNode;
+
+      for (const neighbor of this.adjacencyList[currentNode]) {
         const weight = weights[currentNode] + neighbor.weight;
 
         if (weight < weights[neighbor.toNode]) {
           weights[neighbor.toNode] = weight;
           backtrace[neighbor.toNode] = currentNode;
           pq.push({ toNode: neighbor.toNode, weight: weight });
         }
-      });
+      }
     }
 
-    return new ShortestPaths(startNode, backtrace, weights);
+    return new ShortestPaths(this.nodes, startNode, backtrace, weights);
   }
 }
 
@@ -160,22 +188,33 @@ export class DijkstraShortestPathSolver {
  */
 export class ShortestPaths {
   constructor(
+    public readonly nodes: number,
     public readonly startNode: number,
-    public readonly backtrace: number[],
-    public readonly weights: number[],
+    private readonly backtrace: number[],
+    private readonly weights: number[],
   ) {}
 
   /**
    * Find the shortest path to the given end node.
    * @param endNode The end node.
+   * @throws {@link Error} No path found.
    */
   shortestPathTo(endNode: number): number[] {
+    if (endNode < 0 || endNode >= this.nodes) {
+      throw new RangeError(
+        `end-node must be in range 0 to ${this.nodes - 1}: ${endNode}`,
+      );
+    }
+
     const path = [endNode];
     let lastStep = endNode;
 
     while (lastStep != this.startNode) {
       path.unshift(this.backtrace[lastStep]);
       lastStep = this.backtrace[lastStep];
+      if (lastStep === undefined) {
+        throw new Error(`no path from ${this.startNode} to ${endNode}`);
+      }
     }
 
     return path;
@@ -186,6 +225,12 @@ export class ShortestPaths {
    * @param endNode The end node.
    */
   totalWeight(endNode: number): number {
+    if (endNode < 0 || endNode >= this.nodes) {
+      throw new RangeError(
+        `end-node must be in range 0 to ${this.nodes - 1}: ${endNode}`,
+      );
+    }
+
     return this.weights[endNode];
   }
 }