Rewrite codebase in TypeScript for v3.0.0 - Clean types with documented interfaces and strict ESLint rules

.eslintrc

@@ -1,7 +1,32 @@
 {
-    "extends": ["plugin:import/recommended", "plugin:jsx-a11y/recommended", "prettier"],
-    "plugins": ["import", "jsx-a11y", "prettier"],
-    "rules": {
-      "prettier/prettier": ["error"]
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 2020,
+    "sourceType": "module"
+  },
+  "plugins": ["@typescript-eslint"],
+  "extends": [
+    "eslint:recommended"
+  ],
+  "rules": {
+    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
+    "no-dupe-class-members": "off"
+  },
+  "env": {
+    "node": true,
+    "es2020": true
+  },
+  "overrides": [
+    {
+      "files": ["test/**/*.ts"],
+      "env": {
+        "mocha": true
+      },
+      "rules": {
+        "no-unused-vars": "off",
+        "@typescript-eslint/no-unused-vars": "off"
+      }
     }
+  ]
 }

.github/workflows/test.yml

@@ -13,13 +13,13 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node-version: [16.x, 18.x]
+        node-version: [16.x, 18.x, 20.x, latest]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
           cache: "npm"
@@ -28,6 +28,6 @@ jobs:
 
       - run: npm test
 
-      - uses: codecov/codecov-action@v3
+      - uses: codecov/codecov-action@v4
         with:
           directory: ./coverage

.gitignore

@@ -1,4 +1,6 @@
 node_modules
 *.log
 coverage
-.nyc_output
+.nyc_output
+dist
+*.tsbuildinfo

.prettierrc

@@ -0,0 +1,8 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false
+}

README.md

@@ -2,220 +2,86 @@
 
 [![Unit Tests](https://github.com/albertorestifo/node-dijkstra/actions/workflows/test.yml/badge.svg)](https://github.com/albertorestifo/node-dijkstra/actions/workflows/test.yml) [![codecov.io](http://codecov.io/github/albertorestifo/node-dijkstra/coverage.svg?branch=master)](http://codecov.io/github/albertorestifo/node-dijkstra?branch=master)
 
-> Fast JavaScript implementation of the Dijkstra's shortest path problem for NodeJS
+> Fast TypeScript implementation of Dijkstra's shortest path algorithm for NodeJS
 
 ## Installation
 
-Since version 2 this plugin uses some ES6 features. You can run the latest version on **NodeJS `v4.0.0` or newer**
+Requires Node.js 16.0.0 or newer.
 
 ```shell
-npm install node-dijkstra --save
+npm install node-dijkstra
 ```
 
-### NodeJS prior `v4.0.0`
-
-On versions of NodeJS prior `v4.0.0`, although less performant, it's safe to use the version `1.1.3` that you can install as follows:
-
-```shell
-npm install [email protected] --save
-```
-
-You can then refer to the [`v1.1.3` documentation](https://github.com/albertorestifo/node-dijkstra/blob/v1.1.3/README.md#api)
-
 ## Usage
 
-Basic example:
+### TypeScript
 
-```js
-const Graph = require("node-dijkstra");
+```typescript
+import { Graph } from 'node-dijkstra';
 
 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.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' ]
-```
-
-## API
-
-### `Graph([nodes])`
-
-#### Parameters
-
-- `Object|Map nodes` _optional_: Initial nodes graph.
-
-A nodes graph must follow this structure:
-
-```
-{
-  node: {
-    neighbor: cost Number
-  }
-}
-```
-
-```js
-{
-  'A': {
-    'B': 1
-  },
-  'B': {
-    'A': 1,
-    'C': 2,
-    'D': 4
-  }
-}
-```
-
-#### Example
-
-```js
-const route = new Graph();
-
-// or with pre-populated graph
-const route = new Graph({
-  A: { B: 1 },
-  B: { A: 1, C: 2, D: 4 },
-});
-```
-
-It's possible to pass the constructor a deep `Map`. This allows using numbers as keys for the nodes.
-
-```js
-const graph = 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);
-
-graph.set("A", a);
-graph.set("B", b);
-
-const route = new Graph(graph);
+route.path('A', 'D'); // => ['A', 'B', 'C', 'D']
 ```
 
-### `Graph#addNode(name, edges)`
-
-Add a node to the nodes graph
+### JavaScript
 
-#### Parameters
+```javascript
+const { Graph } = require('node-dijkstra');
 
-- `String name`: name of the node
-- `Object|Map edges`: object or `Map` containing the name of the neighboring nodes and their cost
-
-#### Returns
-
-Returns `this` allowing chained calls.
-
-```js
 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.addNode("A", { B: 1 });
-
-// chaining is possible
-route.addNode("B", { A: 1 }).addNode("C", { A: 3 });
-
-// passing a Map directly is possible
-const c = new Map();
-c.set("A", 4);
-
-route.addNode("C", c);
+route.path('A', 'D'); // => ['A', 'B', 'C', 'D']
 ```
 
-### `Graph#removeNode(name)`
-
-Removes a node and all its references from the graph
-
-#### Parameters
-
-- `String name`: name of the node to remove
+## API
 
-#### Returns
+### Types
 
-Returns `this` allowing chained calls.
+```typescript
+type NodeKey = string | number;
+type EdgeWeight = number;
+type GraphData = Record<string, Record<string, EdgeWeight>>;
 
-```js
-const route = new Graph({
-  a: { b: 3, c: 10 },
-  b: { a: 5, c: 2 },
-  c: { b: 1 },
-});
+interface PathOptions {
+  trim?: boolean;
+  reverse?: boolean;
+  cost?: boolean;
+  avoid?: NodeKey[];
+}
 
-route.removeNode("c");
-// => The graph now is:
-// {
-//   a: { b: 3 },
-//   b: { a: 5 },
-// }
+interface PathResult {
+  path: NodeKey[] | null;
+  cost: EdgeWeight;
+}
 ```
 
-### `Graph#path(start, goal [, options])`
-
-#### Parameters
-
-- `String start`: Name of the starting node
-- `String goal`: Name of out goal node
-- `Object options` _optional_: Addittional options:
-  - `Boolean trim`, default `false`: If set to true, the result won't include the start and goal nodes
-  - `Boolean reverse`, default `false`: If set to true, the result will be in reverse order, from goal to start
-  - `Boolean cost`, default `false`: If set to true, an object will be returned with the following keys:
-    - `Array path`: Computed path (subject to other options)
-    - `Number cost`: Total cost for the found path
-  - `Array avoid`, default `[]`: Nodes to be avoided
-
-#### Returns
-
-If `options.cost` is `false` (default behaviour) an `Array` will be returned, containing the name of the crossed nodes. By default it will be ordered from start to goal, and those nodes will also be included. This behaviour can be changes with `options.trim` and `options.reverse` (see above)
-
-If `options.cost` is `true`, an `Object` with keys `path` and `cost` will be returned. `path` follows the same rules as above and `cost` is the total cost of the found route between nodes.
-
-When to route can be found, the path will be set to `null`.
+### Graph
 
-```js
-const Graph = require("node-dijkstra");
+#### `new Graph(nodes?: GraphData)`
 
-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 });
+Creates a new Graph instance with optional initial data.
 
-route.path("A", "D"); // => ['A', 'B', 'C', 'D']
+#### `addNode(name: NodeKey, neighbors: Record<string, EdgeWeight>): this`
 
-// trimmed
-route.path("A", "D", { trim: true }); // => [B', 'C']
+Adds a node with its neighbors and edge weights.
 
-// 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
-//    }
-```
+#### `removeNode(key: NodeKey): this`
 
-## Upgrading from `v1`
+Removes a node and all references to it.
 
-- The `v2` release in not compatible with NodeJS prior to the version 4.0
-- The method `Graph#shortestPath` has been deprecated, use `Graph#path` instead
-- The method `Graph#addVertex` has been deprecated, use `Graph#addNode` instead
+#### `path(start: NodeKey, goal: NodeKey, options?: PathOptions): NodeKey[] | PathResult | null`
 
-## Testing
-
-```shell
-npm test
-```
+Finds the shortest path between two nodes. Returns `PathResult` when `options.cost` is true.
 
-[![js-standard-style](https://cdn.rawgit.com/feross/standard/master/badge.svg)](https://github.com/feross/standard)
+## License
 
-[1]: https://github.com/andrewhayward/dijkstra
+MIT