Merge pull request #42 from notmatthancock/enh/topo-sort-ensure-no-cycles

Add CycleError option to DFS

Author: curran

README.md

@@ -201,14 +201,20 @@ Deserializes the given serialized graph. Returns *graph* to support method chain
 
 ### Graph Algorithms
 
-<a name="dfs" href="#dfs">#</a> <i>graph</i>.<b>depthFirstSearch</b>([<i>sourceNodes</i>][, <i>includeSourceNodes</i>])
+<a name="dfs" href="#dfs">#</a> <i>graph</i>.<b>depthFirstSearch</b>([<i>sourceNodes</i>][, <i>includeSourceNodes</i>][, <i>errorOnCycle</i>])
 
 Performs [Depth-first Search](https://en.wikipedia.org/wiki/Depth-first_search). Returns an array of node identifier strings. The returned array includes nodes visited by the algorithm in the order in which they were visited. Implementation inspired by pseudocode from Cormen et al. "Introduction to Algorithms" 3rd Ed. p. 604.
 
 Arguments:
 
  * *sourceNodes* (optional) - An array of node identifier strings. This specifies the subset of nodes to use as the sources of the depth-first search. If *sourceNodes* is not specified, all **[nodes](#nodes)** in the graph are used as source nodes.
  * *includeSourceNodes* (optional) - A boolean specifying whether or not to include the source nodes in the returned array. If *includeSourceNodes* is not specified, it is treated as `true` (all source nodes are included in the returned array).
+ * *errorOnCycle* (optional) - A boolean indicating that a `CycleError` should be thrown whenever a cycle is first encountered. Defaults to `false`.
+
+
+<a name="has-cycle" href="#has-cycle">#</a> <i>graph</i>.<b>hasCycle</b>()
+
+Checks if the graph has any cycles. Returns `true` if it does and `false` otherwise.
 
 <a name="lca" href="#lca">#</a> <i>graph</i>.<b>lowestCommonAncestors</b>([<i>node1</i>][, <i>node2</i>])
 
@@ -225,6 +231,8 @@ Performs [Topological Sort](https://en.wikipedia.org/wiki/Topological_sorting).
 
 See **[depthFirstSearch](#dfs)** for documentation of the arguments *sourceNodes* and *includeSourceNodes*.
 
+Note: this function raises a `CycleError` when the input is not a DAG.
+
 <a name="shortest-path" href="#shortest-path">#</a> <i>graph</i>.<b>shortestPath</b>(<i>sourceNode</i>, <i>destinationNode</i>)
 
 Performs [Dijkstras Algorithm](https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm). Returns an array of node identifier strings. The returned array includes the nodes of the shortest path from source to destination node. The returned array also contains a `weight` property, which is the total weight over all edges in the path. Inspired by by Cormen et al. "Introduction to Algorithms" 3rd Ed. p. 658.
@@ -234,4 +242,3 @@ Performs [Dijkstras Algorithm](https://en.wikipedia.org/wiki/Dijkstra%27s_algori
     <img src="https://cloud.githubusercontent.com/assets/68416/15298394/a7a0a66a-1bbc-11e6-9636-367bed9165fc.png">
   </a>
 </p>
-

index.d.ts

@@ -21,7 +21,8 @@ declare function Graph(serialized?: Serialized): {
     getEdgeWeight: (u: NodeId, v: NodeId) => EdgeWeight;
     indegree: (node: NodeId) => number;
     outdegree: (node: NodeId) => number;
-    depthFirstSearch: (sourceNodes?: string[] | undefined, includeSourceNodes?: boolean) => string[];
+    depthFirstSearch: (sourceNodes?: string[] | undefined, includeSourceNodes?: boolean, errorOnCycle?: boolean) => string[];
+    hasCycle: () => boolean;
     lowestCommonAncestors: (node1: NodeId, node2: NodeId) => string[];
     topologicalSort: (sourceNodes: NodeId[], includeSourceNodes?: boolean) => string[];
     shortestPath: (source: NodeId, destination: NodeId) => string[] & {

index.js

@@ -1,4 +1,26 @@
 "use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+var CycleError = /** @class */ (function (_super) {
+    __extends(CycleError, _super);
+    function CycleError(message) {
+        var _this = _super.call(this, message) || this;
+        Object.setPrototypeOf(_this, CycleError.prototype);
+        return _this;
+    }
+    return CycleError;
+}(Error));
 // A graph data structure with depth-first search and topological sort.
 function Graph(serialized) {
     // Returned graph instance
@@ -14,6 +36,7 @@ function Graph(serialized) {
         indegree: indegree,
         outdegree: outdegree,
         depthFirstSearch: depthFirstSearch,
+        hasCycle: hasCycle,
         lowestCommonAncestors: lowestCommonAncestors,
         topologicalSort: topologicalSort,
         shortestPath: shortestPath,
@@ -133,20 +156,27 @@ function Graph(serialized) {
     // include or exclude the source nodes from the result (true by default).
     // If `sourceNodes` is not specified, all nodes in the graph
     // are used as source nodes.
-    function depthFirstSearch(sourceNodes, includeSourceNodes) {
+    function depthFirstSearch(sourceNodes, includeSourceNodes, errorOnCycle) {
         if (includeSourceNodes === void 0) { includeSourceNodes = true; }
+        if (errorOnCycle === void 0) { errorOnCycle = false; }
         if (!sourceNodes) {
             sourceNodes = nodes();
         }
         if (typeof includeSourceNodes !== "boolean") {
             includeSourceNodes = true;
         }
         var visited = {};
+        var visiting = {};
         var nodeList = [];
         function DFSVisit(node) {
+            if (visiting[node] && errorOnCycle) {
+                throw new CycleError("Cycle found");
+            }
             if (!visited[node]) {
                 visited[node] = true;
+                visiting[node] = true; // temporary flag while visiting
                 adjacent(node).forEach(DFSVisit);
+                visiting[node] = false;
                 nodeList.push(node);
             }
         }
@@ -163,6 +193,22 @@ function Graph(serialized) {
         }
         return nodeList;
     }
+    // Returns true if the graph has one or more cycles and false otherwise
+    function hasCycle() {
+        try {
+            depthFirstSearch(undefined, true, true);
+            // No error thrown -> no cycles
+            return false;
+        }
+        catch (error) {
+            if (error instanceof CycleError) {
+                return true;
+            }
+            else {
+                throw error;
+            }
+        }
+    }
     // Least Common Ancestors
     // Inspired by https://github.com/relaxedws/lca/blob/master/src/LowestCommonAncestor.php code
     // but uses depth search instead of breadth. Also uses some optimizations
@@ -210,7 +256,7 @@ function Graph(serialized) {
     // Cormen et al. "Introduction to Algorithms" 3rd Ed. p. 613
     function topologicalSort(sourceNodes, includeSourceNodes) {
         if (includeSourceNodes === void 0) { includeSourceNodes = true; }
-        return depthFirstSearch(sourceNodes, includeSourceNodes).reverse();
+        return depthFirstSearch(sourceNodes, includeSourceNodes, true).reverse();
     }
     // Dijkstra's Shortest Path Algorithm.
     // Cormen et al. "Introduction to Algorithms" 3rd Ed. p. 658

index.ts

@@ -7,6 +7,13 @@ interface Serialized {
     links: { source: NodeId; target: NodeId; weight: EdgeWeight }[];
 }
 
+class CycleError extends Error {
+    constructor(message: string) {
+        super(message);
+        Object.setPrototypeOf(this, CycleError.prototype);
+    }
+}
+
 // A graph data structure with depth-first search and topological sort.
 function Graph(serialized?: Serialized) {
     // Returned graph instance
@@ -22,6 +29,7 @@ function Graph(serialized?: Serialized) {
         indegree,
         outdegree,
         depthFirstSearch,
+        hasCycle,
         lowestCommonAncestors,
         topologicalSort,
         shortestPath,
@@ -163,7 +171,8 @@ function Graph(serialized?: Serialized) {
     // are used as source nodes.
     function depthFirstSearch(
         sourceNodes?: NodeId[],
-        includeSourceNodes: boolean = true
+        includeSourceNodes: boolean = true,
+        errorOnCycle: boolean = false,
     ) {
         if (!sourceNodes) {
             sourceNodes = nodes();
@@ -174,12 +183,18 @@ function Graph(serialized?: Serialized) {
         }
 
         const visited: Record<NodeId, boolean> = {};
+        const visiting: Record<NodeId, boolean> = {};
         const nodeList: NodeId[] = [];
 
         function DFSVisit(node: NodeId) {
+            if (visiting[node] && errorOnCycle) {
+                throw new CycleError("Cycle found");
+            }
             if (!visited[node]) {
                 visited[node] = true;
+                visiting[node] = true;  // temporary flag while visiting
                 adjacent(node).forEach(DFSVisit);
+                visiting[node] = false;
                 nodeList.push(node);
             }
         }
@@ -198,6 +213,23 @@ function Graph(serialized?: Serialized) {
         return nodeList;
     }
 
+    // Returns true if the graph has one or more cycles and false otherwise
+    function hasCycle(): boolean {
+        try {
+            depthFirstSearch(undefined, true, true);
+            // No error thrown -> no cycles
+            return false;
+        }
+        catch (error) {
+            if (error instanceof CycleError) {
+                return true;
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+
     // Least Common Ancestors
     // Inspired by https://github.com/relaxedws/lca/blob/master/src/LowestCommonAncestor.php code
     // but uses depth search instead of breadth. Also uses some optimizations
@@ -253,7 +285,7 @@ function Graph(serialized?: Serialized) {
         sourceNodes: NodeId[],
         includeSourceNodes: boolean = true
     ) {
-        return depthFirstSearch(sourceNodes, includeSourceNodes).reverse();
+        return depthFirstSearch(sourceNodes, includeSourceNodes, true).reverse();
     }
 
     // Dijkstra's Shortest Path Algorithm.

test.js

@@ -148,6 +148,34 @@ describe("Graph", function() {
 
   describe("Algorithms", function() {
 
+    it("Should detect cycle.", function() {
+      var graph = Graph();
+      graph.addEdge("a", "b");
+      graph.addEdge("b", "a");
+      assert(graph.hasCycle());
+    });
+
+    it("Should detect cycle (long).", function() {
+      var graph = Graph();
+      graph.addEdge("a", "b");
+      graph.addEdge("b", "c");
+      graph.addEdge("c", "d");
+      graph.addEdge("d", "a");
+      assert(graph.hasCycle());
+    });
+
+    it("Should detect cycle (loop).", function() {
+      var graph = Graph();
+      graph.addEdge("a", "a");
+      assert(graph.hasCycle());
+    });
+
+    it("Should not detect cycle.", function() {
+      var graph = Graph();
+      graph.addEdge("a", "b");
+      assert(!graph.hasCycle());
+    });
+
     // This example is from Cormen et al. "Introduction to Algorithms" page 550
     it("Should compute topological sort.", function (){
 
@@ -246,6 +274,13 @@ describe("Graph", function() {
       output(graph, "cycles");
     });
 
+    it("Should error on non-DAG topological sort", function() {
+      var graph = Graph();
+      graph.addEdge("a", "b");
+      graph.addEdge("b", "a");
+      assert.throws(graph.topologicalSort);
+    });
+
     it("Should compute lowest common ancestors.", function (){
       var graph = Graph()