chore: updating types

jarrodek · jarrodek · commit cebeb92e91a6 · 2021-06-21T19:32:37.000-07:00
Signed-off-by: Pawel Psztyc &lt;jarrodek@gmail.com&gt;
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -5,6 +5,7 @@
     "Pettitt",
     "Warshall",
     "chainable",
+    "eqls",
     "graphlib",
     "heapify",
     "postorder",
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@api-modeling/graphlib",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "A directed and undirected multi-graph library",
   "author": "Chris Pettitt <cpettitt@gmail.com>",
   "license": "MIT",
diff --git a/src/alg/components.d.ts b/src/alg/components.d.ts
@@ -1,4 +1,12 @@
 import { Graph } from "../graph";
 import { NodeIdentifier } from "../types";
 
+/**
+ * Finds all connected components in a graph and returns an array of these components.
+ * Each component is itself an array that contains the ids of nodes in the component.
+ * Complexity: O(|V|).
+ * 
+ * @argument graph - graph to find components in.
+ * @returns array of nodes list representing components
+ */
 export default function components(g: Graph): NodeIdentifier[][];
diff --git a/src/alg/components.js b/src/alg/components.js
@@ -2,8 +2,12 @@
 /** @typedef {import('../types').NodeIdentifier} NodeIdentifier */
 
 /**
- * @param {Graph} g 
- * @returns {NodeIdentifier[][]}
+ * Finds all connected components in a graph and returns an array of these components.
+ * Each component is itself an array that contains the ids of nodes in the component.
+ * Complexity: O(|V|).
+ * 
+ * @param {Graph} g graph to find components in.
+ * @returns {NodeIdentifier[][]} array of nodes list representing components
  */
 export default function components(g) {
 
diff --git a/src/alg/dijkstra-all.d.ts b/src/alg/dijkstra-all.d.ts
@@ -1,4 +1,18 @@
 import { Graph } from "../graph.js";
-import { Edge, FloydWarshallItem, NodeIdentifier } from "../types.js";
+import { Edge, NodePath, NodeIdentifier } from "../types.js";
 
-export default function dijkstraAll(g: Graph, weightFunc?: (edge: Edge) => number, edgeFunc?: (v: NodeIdentifier) => Edge[]): Record<NodeIdentifier, Record<NodeIdentifier, FloydWarshallItem>>;
+/**
+ * This function finds the shortest path from each node to every other reachable node in
+ * the graph. It is similar to alg.dijkstra, but instead of returning a single-source
+ * array, it returns a mapping of source -> alg.dijksta(g, source, weightFn, edgeFn).
+ * Complexity: O(|V| * (|E| + |V|) * log |V|).
+ *
+ * @argument graph graph where to search paths.
+ * @argument weightFn function which takes edge e and returns the weight of it. If no weightFn
+ * is supplied then each edge is assumed to have a weight of 1. This function throws an
+ * Error if any of the traversed edges have a negative edge weight.
+ * @argument edgeFn function which takes a node v and returns the ids of all edges incident to it
+ * for the purposes of shortest path traversal. By default this function uses the graph.outEdges.
+ * @returns shortest paths map.
+ */
+export default function dijkstraAll(g: Graph, weightFunc?: (edge: Edge) => number, edgeFunc?: (v: NodeIdentifier) => Edge[]): Record<NodeIdentifier, Record<NodeIdentifier, NodePath>>;
diff --git a/src/alg/dijkstra-all.js b/src/alg/dijkstra-all.js
@@ -3,16 +3,21 @@ import dijkstra from "./dijkstra.js";
 /** @typedef {import('../graph').Graph} Graph */
 /** @typedef {import('../types').NodeIdentifier} NodeIdentifier */
 /** @typedef {import('../types').Edge} Edge */
-/** @typedef {import('../types').FloydWarshallItem} FloydWarshallItem */
+/** @typedef {import('../types').NodePath} NodePath */
 
 /**
+ * This function finds the shortest path from each node to every other reachable node in
+ * the graph. It is similar to alg.dijkstra, but instead of returning a single-source
+ * array, it returns a mapping of source -> alg.dijksta(g, source, weightFn, edgeFn).
+ * Complexity: O(|V| * (|E| + |V|) * log |V|).
+ * 
  * @param {Graph} g 
  * @param {(edge: Edge) => number=} weightFunc 
  * @param {(v: NodeIdentifier) => Edge[]=} edgeFunc 
- * @returns {Record<NodeIdentifier, Record<NodeIdentifier, FloydWarshallItem>>}
+ * @returns {Record<NodeIdentifier, Record<NodeIdentifier, NodePath>>}
  */
 export default function dijkstraAll(g, weightFunc, edgeFunc) {
-  /** @type Record<NodeIdentifier, Record<NodeIdentifier, FloydWarshallItem>> */
+  /** @type Record<NodeIdentifier, Record<NodeIdentifier, NodePath>> */
   const result = {};
   const ids = g.nodes();
   ids.forEach((id) => {
diff --git a/src/alg/dijkstra.d.ts b/src/alg/dijkstra.d.ts
@@ -1,4 +1,22 @@
 import { Graph } from "../graph";
-import { Edge, FloydWarshallItem, NodeIdentifier } from "../types";
+import { Edge, NodePath, NodeIdentifier } from "../types";
 
-export default function dijkstra(g: Graph, source: NodeIdentifier, weightFn?: ((edge: Edge) => number), edgeFn?: ((v: NodeIdentifier) => Edge[])): Record<NodeIdentifier, FloydWarshallItem>;
+/**
+ * This function is an implementation of Dijkstra's algorithm which finds the shortest
+ * path from source to all other nodes in graph. This function returns a map of
+ * v -> { distance, predecessor }. The distance property holds the sum of the weights
+ * from source to v along the shortest path or Number.POSITIVE_INFINITY if there is no path
+ * from source. The predecessor property can be used to walk the individual elements of the
+ * path from source to v in reverse order.
+ * Complexity: O((|E| + |V|) * log |V|).
+ *
+ * @argument graph - graph where to search pathes.
+ * @argument source - node to start pathes from.
+ * @argument weightFn - function which takes edge e and returns the weight of it. If no weightFn
+ * is supplied then each edge is assumed to have a weight of 1. This function throws an
+ * Error if any of the traversed edges have a negative edge weight.
+ * @argument edgeFn - function which takes a node v and returns the ids of all edges incident to it
+ * for the purposes of shortest path traversal. By default this function uses the graph.outEdges.
+ * @returns shortest pathes map that starts from node source
+ */
+export default function dijkstra(g: Graph, source: NodeIdentifier, weightFn?: ((edge: Edge) => number), edgeFn?: ((v: NodeIdentifier) => Edge[])): Record<NodeIdentifier, NodePath>;
diff --git a/src/alg/dijkstra.js b/src/alg/dijkstra.js
@@ -3,7 +3,7 @@ import { PriorityQueue } from '../data/PriorityQueue.js';
 /** @typedef {import('../graph').Graph} Graph */
 /** @typedef {import('../types').Edge} Edge */
 /** @typedef {import('../types').NodeIdentifier} NodeIdentifier */
-/** @typedef {import('../types').FloydWarshallItem} FloydWarshallItem */
+/** @typedef {import('../types').NodePath} NodePath */
 
 const DEFAULT_WEIGHT_FUNC = () => 1;
 
@@ -13,14 +13,14 @@ const DEFAULT_WEIGHT_FUNC = () => 1;
  * @param {string} source 
  * @param {(edge: Edge) => number} weightFn 
  * @param {(v: NodeIdentifier) => Edge[]} edgeFn 
- * @returns {Record<NodeIdentifier, FloydWarshallItem>}
+ * @returns {Record<NodeIdentifier, NodePath>}
  */
 function runDijkstra(g, source, weightFn, edgeFn) {
-  /** @type {Record<NodeIdentifier, FloydWarshallItem>} */
+  /** @type {Record<NodeIdentifier, NodePath>} */
   const results = {};
   const pq = new PriorityQueue();
   let v; 
-  /** @type FloydWarshallItem */
+  /** @type NodePath */
   let vEntry;
 
   /**
@@ -64,11 +64,22 @@ function runDijkstra(g, source, weightFn, edgeFn) {
 }
 
 /**
- * @param {Graph} g
- * @param {NodeIdentifier} source 
- * @param {((edge: Edge) => number)=} weightFn 
- * @param {((v: NodeIdentifier) => Edge[])=} edgeFn 
- * @returns {Record<NodeIdentifier, FloydWarshallItem>}
+ * This function is an implementation of Dijkstra's algorithm which finds the shortest
+ * path from source to all other nodes in graph. This function returns a map of
+ * v -> { distance, predecessor }. The distance property holds the sum of the weights
+ * from source to v along the shortest path or Number.POSITIVE_INFINITY if there is no path
+ * from source. The predecessor property can be used to walk the individual elements of the
+ * path from source to v in reverse order.
+ * Complexity: O((|E| + |V|) * log |V|).
+ * 
+ * @param {Graph} g - graph where to search paths.
+ * @param {NodeIdentifier} source node to start paths from.
+ * @param {((edge: Edge) => number)=} weightFn function which takes edge e and returns the weight of it. If no weightFn
+ * is supplied then each edge is assumed to have a weight of 1. This function throws an
+ * Error if any of the traversed edges have a negative edge weight.
+ * @param {((v: NodeIdentifier) => Edge[])=} edgeFn function which takes a node v and returns the ids of all edges incident to it
+ * for the purposes of shortest path traversal. By default this function uses the graph.outEdges.
+ * @returns {Record<NodeIdentifier, NodePath>} shortest paths map that starts from node source
  */
 export default function dijkstra(g, source, weightFn, edgeFn) {
   return runDijkstra(g, String(source), weightFn || DEFAULT_WEIGHT_FUNC, edgeFn || (v => g.outEdges(v)));
diff --git a/src/alg/find-cycles.d.ts b/src/alg/find-cycles.d.ts
@@ -1,4 +1,15 @@
 import { Graph } from "../graph";
 import { NodeIdentifier } from "../types";
 
+/**
+ * Given a Graph, graph, this function returns all nodes that are part of a cycle. As there
+ * may be more than one cycle in a graph this function return an array of these cycles,
+ * where each cycle is itself represented by an array of ids for each node involved in
+ * that cycle. Method alg.isAcyclic is more efficient if you only need to determine whether a graph has a
+ * cycle or not.
+ * Complexity: O(|V| + |E|).
+ * 
+ * @argument graph - graph where to search cycles.
+ * @returns cycles list.
+ */
 export default function findCycles(g: Graph): NodeIdentifier[][];
diff --git a/src/alg/find-cycles.js b/src/alg/find-cycles.js
@@ -4,8 +4,15 @@ import tarjan from "./tarjan.js";
 /** @typedef {import('../types').NodeIdentifier} NodeIdentifier */
 
 /**
- * @param {Graph} g 
- * @returns {NodeIdentifier[][]}
+ * Given a Graph, graph, this function returns all nodes that are part of a cycle. As there
+ * may be more than one cycle in a graph this function return an array of these cycles,
+ * where each cycle is itself represented by an array of ids for each node involved in
+ * that cycle. Method alg.isAcyclic is more efficient if you only need to determine whether a graph has a
+ * cycle or not.
+ * Complexity: O(|V| + |E|).
+ * 
+ * @param {Graph} g graph where to search cycles.
+ * @returns {NodeIdentifier[][]} cycles list.
  */
 export default function findCycles(g) {
   const items = tarjan(g);
diff --git a/src/alg/floyd-warshall.d.ts b/src/alg/floyd-warshall.d.ts
@@ -1,4 +1,23 @@
 import { Graph } from "../graph";
 import { Edge, FloydWarshallResult, NodeIdentifier } from "../types";
 
+/**
+ * This function is an implementation of the Floyd-Warshall algorithm, which finds the
+ * shortest path from each node to every other reachable node in the graph. It is similar
+ * to alg.dijkstraAll, but it handles negative edge weights and is more efficient for some types
+ * of graphs. This function returns a map of source -> { target -> { distance, predecessor }.
+ * The distance property holds the sum of the weights from source to target along the shortest
+ * path of Number.POSITIVE_INFINITY if there is no path from source. The predecessor property
+ * can be used to walk the individual elements of the path from source to target in reverse
+ * order.
+ * Complexity: O(|V|^3).
+ *
+ * @argument graph - graph where to search pathes.
+ * @argument weightFn - function which takes edge e and returns the weight of it. If no weightFn
+ * is supplied then each edge is assumed to have a weight of 1. This function throws an
+ * Error if any of the traversed edges have a negative edge weight.
+ * @argument edgeFn - function which takes a node v and returns the ids of all edges incident to it
+ * for the purposes of shortest path traversal. By default this function uses the graph.outEdges.
+ * @returns shortest pathes map.
+ */
 export default function floydWarshall(g: Graph, weightFn?: (edge: Edge) => number, edgeFn?: (v: NodeIdentifier) => Edge[]): FloydWarshallResult;
diff --git a/src/alg/floyd-warshall.js b/src/alg/floyd-warshall.js
@@ -3,7 +3,6 @@ const DEFAULT_WEIGHT_FUNC = () => 1;
 /** @typedef {import('../graph').Graph} Graph */
 /** @typedef {import('../types').NodeIdentifier} NodeIdentifier */
 /** @typedef {import('../types').Edge} Edge */
-/** @typedef {import('../types').FloydWarshallItem} FloydWarshallItem */
 /** @typedef {import('../types').FloydWarshallResult} FloydWarshallResult */
 
 /**
@@ -52,6 +51,16 @@ function runFloydWarshall(g, weightFn, edgeFn) {
 }
 
 /**
+ * This function is an implementation of the Floyd-Warshall algorithm, which finds the
+ * shortest path from each node to every other reachable node in the graph. It is similar
+ * to alg.dijkstraAll, but it handles negative edge weights and is more efficient for some types
+ * of graphs. This function returns a map of source -> { target -> { distance, predecessor }.
+ * The distance property holds the sum of the weights from source to target along the shortest
+ * path of Number.POSITIVE_INFINITY if there is no path from source. The predecessor property
+ * can be used to walk the individual elements of the path from source to target in reverse
+ * order.
+ * Complexity: O(|V|^3).
+ * 
  * @param {Graph} g 
  * @param {(edge: Edge) => number=} weightFn 
  * @param {(v: NodeIdentifier) => Edge[]=} edgeFn 
diff --git a/src/alg/is-acyclic.d.ts b/src/alg/is-acyclic.d.ts
@@ -1,3 +1,11 @@
 import { Graph } from "../graph";
 
+/**
+ * Given a Graph, graph, this function returns true if the graph has no cycles and returns false if it
+ * does. This algorithm returns as soon as it detects the first cycle. You can use alg.findCycles
+ * to get the actual list of cycles in the graph.
+ * 
+ * @argument graph graph to detect whether it acyclic ot not.
+ * @returns whether graph contain cycles or not.
+ */
 export default function isAcyclic(g: Graph): boolean;
diff --git a/src/alg/is-acyclic.js b/src/alg/is-acyclic.js
@@ -3,6 +3,10 @@ import topSort, { CycleException } from "./topsort.js";
 /** @typedef {import('../graph').Graph} Graph */
 
 /**
+ * Given a Graph, graph, this function returns true if the graph has no cycles and returns false if it
+ * does. This algorithm returns as soon as it detects the first cycle. You can use alg.findCycles
+ * to get the actual list of cycles in the graph.
+ * 
  * @param {Graph} g 
  * @returns {boolean}
  */
diff --git a/src/alg/postorder.d.ts b/src/alg/postorder.d.ts
@@ -1,4 +1,13 @@
 import { Graph } from "../graph";
 import { NodeIdentifier } from "../types";
 
+/**
+ * Performs post-order depth first traversal on the input graph. If the graph is
+ * undirected then this algorithm will navigate using neighbors. If the graph
+ * is directed then this algorithm will navigate using successors.
+ * 
+ * @argument graph - depth first traversal target.
+ * @argument vs - nodes list to traverse.
+ * @returns the nodes in the order they were visited as a list of their names.
+ */
 export default function postOrder(g: Graph, vs: NodeIdentifier|NodeIdentifier[]): NodeIdentifier[];
diff --git a/src/alg/preorder.d.ts b/src/alg/preorder.d.ts
@@ -1,4 +1,13 @@
 import { Graph } from "../graph";
 import { NodeIdentifier } from "../types";
 
+/**
+ * Performs pre-order depth first traversal on the input graph. If the graph is
+ * undirected then this algorithm will navigate using neighbors. If the graph
+ * is directed then this algorithm will navigate using successors.
+ * 
+ * @argument graph - depth first traversal target.
+ * @argument vs - nodes list to traverse.
+ * @returns the nodes in the order they were visited as a list of their names.
+ */
 export default function preOrder(g: Graph, vs: NodeIdentifier|NodeIdentifier[]): NodeIdentifier[];
diff --git a/src/alg/prim.d.ts b/src/alg/prim.d.ts
@@ -1,4 +1,15 @@
 import { Graph } from "../graph";
 import { Edge } from "../types";
 
+/**
+ * Prim's algorithm takes a connected undirected graph and generates a minimum spanning tree. This
+ * function returns the minimum spanning tree as an undirected graph. This algorithm is derived
+ * from the description in "Introduction to Algorithms", Third Edition, Cormen, et al., Pg 634.
+ * Complexity: O(|E| * log |V|);
+ *
+ * @argument graph graph to generate a minimum spanning tree of.
+ * @argument weightFn function which takes edge e and returns the weight of it. 
+ * It throws an Error if the graph is not connected.
+ * @returns minimum spanning tree of graph.
+ */
 export default function prim(g: Graph, weightFunc: (edge: Edge) => number): Graph;
diff --git a/src/alg/prim.js b/src/alg/prim.js
@@ -4,7 +4,12 @@ import { PriorityQueue } from "../data/PriorityQueue.js";
 /** @typedef {import('../types').Edge} Edge */
 
 /**
- * @param {Graph} g
+ * Prim's algorithm takes a connected undirected graph and generates a minimum spanning tree. This
+ * function returns the minimum spanning tree as an undirected graph. This algorithm is derived
+ * from the description in "Introduction to Algorithms", Third Edition, Cormen, et al., Pg 634.
+ * Complexity: O(|E| * log |V|);
+ * 
+ * @param {Graph} g graph to generate a minimum spanning tree of.
  * @param {(edge: Edge) => number} weightFunc 
  * @returns {Graph}
  */
diff --git a/src/alg/tarjan.d.ts b/src/alg/tarjan.d.ts
@@ -1,4 +1,17 @@
 import { Graph } from "../graph";
 import { NodeIdentifier } from "../types";
 
+/**
+ * This function is an implementation of Tarjan's algorithm which finds all strongly connected
+ * components in the directed graph g. Each strongly connected component is composed of nodes that
+ * can reach all other nodes in the component via directed edges. A strongly connected component
+ * can consist of a single node if that node cannot both reach and be reached by any other
+ * specific node in the graph. Components of more than one node are guaranteed to have at least
+ * one cycle.
+ * Complexity: O(|V| + |E|).
+ *
+ * @argument graph - graph to find all strongly connected components of.
+ * @return an array of components. Each component is itself an array that contains
+ * the ids of all nodes in the component.
+ */
 export default function tarjan(g: Graph): NodeIdentifier[][];
diff --git a/src/alg/topsort.d.ts b/src/alg/topsort.d.ts
@@ -3,4 +3,12 @@ import { NodeIdentifier } from "../types";
 
 export class CycleException extends Error {}
 
+/**
+ * Given a Graph graph this function applies topological sorting to it.
+ * If the graph has a cycle it is impossible to generate such a list and CycleException is thrown.
+ * Complexity: O(|V| + |E|).
+ * 
+ * @argument graph - graph to apply topological sorting to.
+ * @returns an array of nodes such that for each edge u -> v, u appears before v in the array.
+ */
 export default function topSort(g: Graph): NodeIdentifier[];
diff --git a/src/graph.d.ts b/src/graph.d.ts
diff --git a/src/graph.js b/src/graph.js
diff --git a/src/json.d.ts b/src/json.d.ts
diff --git a/src/types.d.ts b/src/types.d.ts
diff --git a/test/graph.test.js b/test/graph.test.js

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@api-modeling/graphlib",`
`3`		`- "version": "3.0.0",`
	`3`	`+ "version": "3.0.1",`
`4`	`4`	`"description": "A directed and undirected multi-graph library",`
`5`	`5`	`"author": "Chris Pettitt <[email protected]>",`
`6`	`6`	`"license": "MIT",`