feat: enhance pathfinding options with maxCost, maxNodes, and allowedCallback

.github/workflows/release.yml

@@ -2,12 +2,12 @@ name: Release to NPM
 
 on:
   release:
-    types: [published]
+    types: [ published ]
 
 jobs:
   publish:
     runs-on: ubuntu-latest
-    
+
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -22,10 +22,13 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Run lint
+        run: npm lint
+
       - name: Run tests
         run: npm test
 
       - name: Publish to NPM
         run: npm publish
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/test.yml

@@ -2,9 +2,9 @@ name: Unit Tests
 
 on:
   push:
-    branches: ["master"]
+    branches: [ "master" ]
   pull_request:
-    branches: ["master"]
+    branches: [ "master" ]
 
 jobs:
   tests:
@@ -13,7 +13,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node-version: [16.x, 18.x]
+        node-version: [ 16.x, 18.x ]
 
     steps:
       - uses: actions/checkout@v3
@@ -24,9 +24,14 @@ jobs:
           node-version: ${{ matrix.node-version }}
           cache: "npm"
 
-      - run: npm ci
+      - name: Install dependencies
+        run: npm ci
 
-      - run: npm test
+      - name: Run lint
+        run: npm lint
+
+      - name: Run tests
+        run: npm test
 
       - uses: codecov/codecov-action@v3
         with:

.gitignore

@@ -1,4 +1,5 @@
 node_modules
 *.log
 coverage
-.nyc_output
+.nyc_output
+.idea

libs/Graph.js

@@ -134,9 +134,12 @@ class Graph {
    * @param {string}  goal      - Node we want to reach
    * @param {object}  [options] - Options
    *
-   * @param {boolean} [options.trim]    - Exclude the origin and destination nodes from the result
-   * @param {boolean} [options.reverse] - Return the path in reversed order
-   * @param {boolean} [options.cost]    - Also return the cost of the path when set to true
+   * @param {boolean} [options.trim]      - Exclude the origin and destination nodes from the result
+   * @param {boolean} [options.reverse]   - Return the path in reversed order
+   * @param {boolean} [options.cost]      - Also return the cost of the path when set to true
+   * @param {number}  [options.maxCost]   - Only consider paths with total cost less than or equal to this value
+   * @param {number}  [options.maxNodes]  - Maximum number of nodes allowed in the resulting path (including start and goal)
+   * @param {function} [options.canVisit] - A predicate invoked for each potential edge expansion. Receives an object { from, to, cost, accumulatedCost, depth } and must return true to allow the move
    *
    * @return {array|object} Computed path between the nodes.
    *
@@ -179,6 +182,7 @@ class Graph {
     const explored = new Set();
     const frontier = new Queue();
     const previous = new Map();
+    const depth = new Map();
 
     let path = [];
     let totalCost = 0;
@@ -192,14 +196,32 @@ class Graph {
       throw new Error(`Ending node (${goal}) cannot be avoided`);
     }
 
+    const hasMaxCost =
+      typeof options.maxCost === "number" && !Number.isNaN(options.maxCost);
+    const maxCost = hasMaxCost ? Number(options.maxCost) : undefined;
+    const hasMaxNodes =
+      typeof options.maxNodes === "number" && !Number.isNaN(options.maxNodes);
+    const maxNodes = hasMaxNodes
+      ? Math.max(1, Math.floor(options.maxNodes))
+      : undefined;
+    const canVisit = typeof options.canVisit === "function" ? options.canVisit : null;
+
     // Add the starting point to the frontier, it will be the first node visited
     frontier.set(start, 0);
+    depth.set(start, 1);
 
     // Run until we have visited every node in the frontier
     while (!frontier.isEmpty()) {
       // Get the node in the frontier with the lowest cost (`priority`)
       const node = frontier.next();
 
+      // If the cheapest node already exceeds maxCost, no valid path can be found
+      if (hasMaxCost && node.priority > maxCost) {
+        // ensure path remains empty so we return null later
+        path = [];
+        break;
+      }
+
       // When the node with the lowest cost in the frontier in our goal node,
       // we can compute the path and exit the loop
       if (node.key === goal) {
@@ -224,21 +246,44 @@ class Graph {
         // If we already explored the node, or the node is to be avoided, skip it
         if (explored.has(nNode) || avoid.includes(nNode)) return null;
 
+        const newCost = node.priority + nCost;
+        const currentDepth = depth.get(node.key) || 1;
+        const newDepth = currentDepth + 1;
+
+        // Enforce maximum number of nodes in the resulting path (including start and goal)
+        if (hasMaxNodes && newDepth > maxNodes) return null;
+
+        // Enforce maximum cost constraint
+        if (hasMaxCost && newCost > maxCost) return null;
+
+        // If provided, consult the canVisit to decide whether to expand this edge
+        if (canVisit) {
+          const allowed = canVisit({
+            from: node.key,
+            to: nNode,
+            cost: nCost,
+            accumulatedCost: newCost,
+            depth: newDepth,
+          });
+          if (!allowed) return null;
+        }
+
         // If the neighboring node is not yet in the frontier, we add it with
         // the correct cost
         if (!frontier.has(nNode)) {
           previous.set(nNode, node.key);
-          return frontier.set(nNode, node.priority + nCost);
+          depth.set(nNode, newDepth);
+          return frontier.set(nNode, newCost);
         }
 
         const frontierPriority = frontier.get(nNode).priority;
-        const nodeCost = node.priority + nCost;
 
         // Otherwise we only update the cost of this node in the frontier when
         // it's below what's currently set
-        if (nodeCost < frontierPriority) {
+        if (newCost < frontierPriority) {
           previous.set(nNode, node.key);
-          return frontier.set(nNode, nodeCost);
+          depth.set(nNode, newDepth);
+          return frontier.set(nNode, newCost);
         }
 
         return null;

libs/index.d.ts

@@ -0,0 +1,160 @@
+declare class Graph {
+    /**
+     * Creates a new Graph, optionally initializing it a nodes graph representation.
+     *
+     * A graph representation is an object that has as keys the name of the point and as values
+     * the points reachable from that node, with the cost to get there:
+     *
+     *     {
+     *       node (Number|String): {
+     *         neighbor (Number|String): cost (Number),
+     *         ...,
+     *       },
+     *     }
+     *
+     * In alternative to an object, you can pass a `Map` of `Map`. This will
+     * allow you to specify numbers as keys.
+     *
+     * @param [graph] - Initial graph definition
+     * @example
+     *
+     * const route = new Graph();
+     *
+     * // Pre-populated graph
+     * const route = new Graph({
+     *   A: { B: 1 },
+     *   B: { A: 1, C: 2, D: 4 },
+     * });
+     *
+     * // Passing a Map
+     * const g = new Map()
+     *
+     * const a = new Map()
+     * a.set('B', 1)
+     *
+     * const b = new Map()
+     * b.set('A', 1)
+     * b.set('C', 2)
+     * b.set('D', 4)
+     *
+     * g.set('A', a)
+     * g.set('B', b)
+     *
+     * const route = new Graph(g)
+     */
+    constructor(nodes?: { [key: string]: { [key: string]: number } } | Map<string, Map<string, number>>);
+
+    /**
+     * Adds a node to the graph
+     *
+     * @param name      - Name of the node
+     * @param neighbors - Neighboring nodes and cost to reach them
+     * @example
+     *
+     * const route = new Graph();
+     *
+     * route.addNode('A', { B: 1 });
+     *
+     * // It's possible to chain the calls
+     * route
+     *   .addNode('B', { A: 1 })
+     *   .addNode('C', { A: 3 });
+     *
+     * // The neighbors can be expressed in a Map
+     * const d = new Map()
+     * d.set('A', 2)
+     * d.set('B', 8)
+     *
+     * route.addNode('D', d)
+     */
+    addNode(name: string, neighbors: any): Graph;
+
+    /**
+     * Removes a node and all of its references from the graph
+     *
+     * @param key - Key of the node to remove from the graph
+     * @example
+     *
+     * const route = new Graph({
+     *   A: { B: 1, C: 5 },
+     *   B: { A: 3 },
+     *   C: { B: 2, A: 2 },
+     * });
+     *
+     * route.removeNode('C');
+     * // The graph now is:
+     * // { A: { B: 1 }, B: { A: 3 } }
+     */
+    removeNode(name: string): Graph;
+
+    /**
+     * Compute the shortest path between the specified nodes
+     *
+     * @param start     - Starting node
+     * @param goal      - Node we want to reach
+     * @param [options] - Options
+     *
+     * @param [options.trim]     - Exclude the origin and destination nodes from the result
+     * @param [options.reverse]  - Return the path in reversed order
+     * @param [options.cost]     - Also return the cost of the path when set to true
+     * @param [options.maxCost]  - Only consider paths with total cost ≤ this value
+     * @param [options.maxNodes] - Maximum number of nodes allowed in the resulting path (including start and goal)
+     * @param [options.canVisit] - Predicate called for each potential expansion; returns true to allow the move
+     *
+     * @return Computed path between the nodes.
+     *
+     *  When `option.cost` is set to true, the returned value will be an object with shape:
+     *    - `path` *(Array)*: Computed path between the nodes
+     *    - `cost` *(Number)*: Cost of the path
+     *
+     * @example
+     *
+     * const route = new Graph()
+     *
+     * route.addNode('A', { B: 1 })
+     * route.addNode('B', { A: 1, C: 2, D: 4 })
+     * route.addNode('C', { B: 2, D: 1 })
+     * route.addNode('D', { C: 1, B: 4 })
+     *
+     * route.path('A', 'D') // => ['A', 'B', 'C', 'D']
+     *
+     * // trimmed
+     * route.path('A', 'D', { trim: true }) // => [B', 'C']
+     *
+     * // reversed
+     * route.path('A', 'D', { reverse: true }) // => ['D', 'C', 'B', 'A']
+     *
+     * // include the cost
+     * route.path('A', 'D', { cost: true })
+     * // => {
+     * //       path: [ 'A', 'B', 'C', 'D' ],
+     * //       cost: 4
+     * //    }
+     */
+    path(start: any, goal: any, options?: PathOption): string[] | PathResult;
+}
+
+interface PathOption {
+    trim?: boolean | undefined;
+    reverse?: boolean | undefined;
+    cost?: boolean | undefined;
+    avoid?: any[] | undefined;
+    maxCost?: number | undefined;
+    maxNodes?: number | undefined;
+    canVisit?: ((arg: CanVisitArg) => boolean) | undefined;
+}
+
+interface CanVisitArg {
+    from: string;
+    to: string;
+    cost: number;
+    accumulatedCost: number;
+    depth: number;
+}
+
+interface PathResult {
+    path: string[] | null;
+    cost: number;
+}
+
+export = Graph;

package.json

@@ -4,12 +4,13 @@
   "description": "A NodeJS implementation of Dijkstra's algorithm",
   "author": "Alberto Restifo <[email protected]>",
   "main": "libs/Graph.js",
+  "types": "libs/index.d.ts",
   "repository": {
     "type": "git",
     "url": "https://github.com/albertorestifo/node-dijkstra"
   },
   "scripts": {
-    "test": "eslint . && nyc --reporter=html mocha -t 5000",
+    "test": "nyc --reporter=html mocha -t 5000",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "compile": "gulp build"