occam-directed-graphs 3.0.36 → 3.0.41

package/README.md

@@ -1,6 +1,6 @@
 # Occam Directed Graphs
 
-Directed graphs comprised of directed acyclic graphs together with cycles for [Occam](https://github.com/djalbat/occam).
+[Occam](https://github.com/djalbat/occam)'s directed graphs.
 
 ### Contents
 
@@ -8,12 +8,13 @@ Directed graphs comprised of directed acyclic graphs together with cycles for [O
 - [Installation](#installation)
 - [Usage](#usage)
 - [Building](#building)
+- [Running the tests](#running-the-tests)
 - [References](#references)
 - [Contact](#contact)
 
 ## Introduction
 
-The reason for not simply implementing a directed graph trivially is to keep track of cycles and recover them quickly. Given the name of any vertex, the implementation will report whether or not it is part of a cycle. If it is, you can retrieve a cycle of which it is part, but bear in mind that a vertex may be the part of more than one cycle, any one of which can be returned.
+This implementation extends an incremental algorithm for directed graphs, one that returns a topological ordering for the graph. If one or more cyclic edges are added then the extended algorithm handles it gracefully rather than throwing an error. In these cases a cycle can be returned rather than a topological ordering. If all cyclic edges are removed thereafter then the algorithm recovers and a topological ordering can be returned again. 
 
 ## Installation
 
@@ -31,53 +32,47 @@ You can also clone the repository with [Git](https://git-scm.com/)...
 
 ## Usage
     
-An empty directed graph can be created by calling the `fromNothing()` factory method, after which vertices and edges can be added incrementally:
+An empty directed graph can be created by calling the `fromNothing()` factory method:
 
 ```
 import { DirectedGraph } from "occam-directed-graphs";
 
-const directedGraph = DirectedGraph.fromNothing(),
-      vertexName = "i",
-      sourceVertexName = "j",
-      targetVertexName = "k";
+const directedGraph = DirectedGraph.fromNothing();
+```
 
-directedGraph.addVertexByVertexName(vertexName);
+After instantiation, vertices and edges can be added incrementally:
 
-directedGraph.addEdgeByVertexNames(sourceVertexName, targetVertexName);
 ```
+import { Edge } from "occam-directed-graphs";
 
-Note that there is no need to add vertices explicitly, they will be added whenever necessary when edges that reference them are added.
+const vertexName = "i";
 
-Alternatively, a directed graph can be constructed with the `fromVertexLiterals()` factory method as follows:
+directedGraph.addVertexByVertexName(vertexName);
+
+const sourceVertexName = "j",
+      targetVertexName = "k",
+      edge = Edge.fromSourceVertexNameAndTargetVertexName(sourceVertexName, targetVertexName);
 
+directedGraph.addEdge(edge);
 ```
-import { DirectedGraph } from "occam-directed-graphs";
 
-const graph = Graph.fromVertexLiterals([
+Note that there is no need to add vertices explicitly, they will be added whenever necessary when edges that reference them are added.
 
-  ["a", ["b"]],
-  ["b", ["c"]],
-  ["d", ["c"]],
-  ["e", []],
-  ["f", ["g"]],
-  ["h", ["g"]]
+You can also remove vertices and edges. Removing a vertex could result in removing edges. When you remove an edge, you can additionally specify that the any stranded vertices that result are also removed:
 
-]);
 ```
+import { Edge } from "occam-directed-graphs";
 
-Note that the array of names that is the second element of each literal gives the *ancestors* of the vertex and not its descendants.
+const vertexName = "i";
 
-You can also remove vertices and edges from the graph. Removing a vertex may of course result in removing edges. When you remove an edge, you can additionally specify that the any stranded vertices that result are also removed:
+directedGraph.removeVertexByName(vertexName);
 
-```
-const vertexName = "i",
-      sourceVertexName = "j",
+const sourceVertexName = "j",
       targetVertexName = "k",
-      removeStrandedVertices = true;
-
-directedGraph.removeVertexByName(vertexName);
+      removeStrandedVertices = true,
+      edge = Edge.fromSourceVertexNameAndTargetVertexName(sourceVertexName, targetVertexName);
 
-directedGraph.removeEdgeByVertexNames(sourceVertexName, targetVertexName, removeStrandedVertices);
+directedGraph.removeEdge(edge, removeStrandedVertices);
 ```
 
 The default is to leave stranded vertices in place.
@@ -85,33 +80,17 @@ The default is to leave stranded vertices in place.
 You can detect and recover cycles thus:
 
 ```
-const vertexName = "i",
-      cyclePresent = directedGraph.isCyclePresentByVertexName(vertexName);
+const cyclePresent = directedGraph.isCyclePresent();
 
 if (cyclePresent) {
-  const cycle = directedGraph.getFirstCycleByVertexName(vertexName),
-        cycleVertexNames = cycle.getVertexNames();
+  const firstCycle = directedGraph.getFirstCycle(),
+        firstCycleVertexNames = firstCycle.getVertexNames();
 
   ...
 }
 ```
-As already pointed out in the introduction, if a vertex is part of more than one cycle, any of of them can be given.
-
 You can get a topologically ordered list of vertices at any time.
-Bear in mind that this will gotten from the underlying directed acyclic graph, however, and therefore may not be useful if there are cycles present.
-A method is also provided to ascertain whether cycles are generally present and it is left up to you to decide whether the topologically ordered list of vertices is useful in the event that they are:
-
-```
-const cyclesPresent = directedGraph.areCyclesPresent();
-
-if (cyclesPresent) {
-  ///
-} else {
-  const orderedVertexNames = directedGraph.getOrderedVertexNames();
-
-  ...
-}
-```
+Bear in mind that this is useless information when cycles are present.
 
 ## Building
 
@@ -120,6 +99,12 @@ Automation is done with [npm scripts](https://docs.npmjs.com/misc/scripts), have
     npm run build-debug
     npm run watch-debug
 
+## Running the tests
+
+Assuming that the packages are installed:
+
+    npm test
+
 ## References
 
 This implementation is based on the Pearce-Kelly algorithm:

package/lib/cycle.js

@@ -8,8 +8,15 @@ Object.defineProperty(exports, "default", {
         return Cycle;
     }
 });
-var _necessary = require("necessary");
 var _vertex = require("./utilities/vertex");
+function _array_like_to_array(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_without_holes(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array(arr);
+}
 function _class_call_check(instance, Constructor) {
     if (!(instance instanceof Constructor)) {
         throw new TypeError("Cannot call a class as a function");
@@ -29,7 +36,23 @@ function _create_class(Constructor, protoProps, staticProps) {
     if (staticProps) _defineProperties(Constructor, staticProps);
     return Constructor;
 }
-var first = _necessary.arrayUtilities.first;
+function _iterable_to_array(iter) {
+    if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
+}
+function _non_iterable_spread() {
+    throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _to_consumable_array(arr) {
+    return _array_without_holes(arr) || _iterable_to_array(arr) || _unsupported_iterable_to_array(arr) || _non_iterable_spread();
+}
+function _unsupported_iterable_to_array(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
+}
 var Cycle = /*#__PURE__*/ function() {
     function Cycle(vertexNames) {
         _class_call_check(this, Cycle);
@@ -44,17 +67,11 @@ var Cycle = /*#__PURE__*/ function() {
         }
     ], [
         {
-            key: "fromVertexNamePartialCycleAndSuccessorVertices",
-            value: function fromVertexNamePartialCycleAndSuccessorVertices(vertexName, partialCycle, successorVertices) {
-                successorVertices = successorVertices.slice(); ///
-                var successorVerticesLength = successorVertices.length;
-                if (successorVerticesLength > 0) {
-                    var firstSuccessorVertex = first(successorVertices), firstSuccessorVertexName = firstSuccessorVertex.getName(), cyclicEdgeTargetVertexName = partialCycle.getTargetVertexName();
-                    if (firstSuccessorVertexName === cyclicEdgeTargetVertexName) {
-                        successorVertices.shift();
-                    }
-                }
-                var cyclicEdgeSourceVertexName = partialCycle.getCyclicEdgeSourceVertexName(), cyclicEdgeTargetVertexName1 = partialCycle.getCyclicEdgeTargetVertexName(), predecessorVertexNames = partialCycle.getPredecessorVertexNames(), successorVertexNames = (0, _vertex.vertexNamesFromVertices)(successorVertices), vertexNames = vertexName === cyclicEdgeTargetVertexName1 ? [].concat(cyclicEdgeTargetVertexName1).concat(predecessorVertexNames).concat(cyclicEdgeSourceVertexName) : [].concat(predecessorVertexNames).concat(cyclicEdgeSourceVertexName).concat(cyclicEdgeTargetVertexName1).concat(successorVertexNames), cycle = new Cycle(vertexNames);
+            key: "fromSourceVertexAndPredecessorVertexes",
+            value: function fromSourceVertexAndPredecessorVertexes(sourceVertex, predecessorVertexes) {
+                var vertexes = _to_consumable_array(predecessorVertexes).concat([
+                    sourceVertex
+                ]), vertexNames = (0, _vertex.vertexNamesFromVertexes)(vertexes), cycle = new Cycle(vertexNames);
                 return cycle;
             }
         }
@@ -62,4 +79,4 @@ var Cycle = /*#__PURE__*/ function() {
     return Cycle;
 }();
 
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi4uL3NyYy9jeWNsZS5qcyIsIjw8anN4LWNvbmZpZy1wcmFnbWEuanM+PiJdLCJzb3VyY2VzQ29udGVudCI6WyJcInVzZSBzdHJpY3RcIjtcblxuaW1wb3J0IHsgYXJyYXlVdGlsaXRpZXMgfSBmcm9tIFwibmVjZXNzYXJ5XCI7XG5cbmltcG9ydCB7IHZlcnRleE5hbWVzRnJvbVZlcnRpY2VzIH0gZnJvbSBcIi4vdXRpbGl0aWVzL3ZlcnRleFwiO1xuXG5jb25zdCB7IGZpcnN0IH0gPSBhcnJheVV0aWxpdGllcztcblxuZXhwb3J0IGRlZmF1bHQgY2xhc3MgQ3ljbGUge1xuICBjb25zdHJ1Y3Rvcih2ZXJ0ZXhOYW1lcykge1xuICAgIHRoaXMudmVydGV4TmFtZXMgPSB2ZXJ0ZXhOYW1lcztcbiAgfVxuXG4gIGdldFZlcnRleE5hbWVzKCkge1xuICAgIHJldHVybiB0aGlzLnZlcnRleE5hbWVzO1xuICB9XG5cbiAgc3RhdGljIGZyb21WZXJ0ZXhOYW1lUGFydGlhbEN5Y2xlQW5kU3VjY2Vzc29yVmVydGljZXModmVydGV4TmFtZSwgcGFydGlhbEN5Y2xlLCBzdWNjZXNzb3JWZXJ0aWNlcykge1xuICAgIHN1Y2Nlc3NvclZlcnRpY2VzID0gc3VjY2Vzc29yVmVydGljZXMuc2xpY2UoKTsgIC8vL1xuICAgIFxuICAgIGNvbnN0IHN1Y2Nlc3NvclZlcnRpY2VzTGVuZ3RoID0gc3VjY2Vzc29yVmVydGljZXMubGVuZ3RoO1xuICAgIFxuICAgIGlmIChzdWNjZXNzb3JWZXJ0aWNlc0xlbmd0aCA+IDApIHtcbiAgICAgIGNvbnN0IGZpcnN0U3VjY2Vzc29yVmVydGV4ID0gZmlyc3Qoc3VjY2Vzc29yVmVydGljZXMpLFxuICAgICAgICAgICAgZmlyc3RTdWNjZXNzb3JWZXJ0ZXhOYW1lID0gZmlyc3RTdWNjZXNzb3JWZXJ0ZXguZ2V0TmFtZSgpLFxuICAgICAgICAgICAgY3ljbGljRWRnZVRhcmdldFZlcnRleE5hbWUgPSBwYXJ0aWFsQ3ljbGUuZ2V0VGFyZ2V0VmVydGV4TmFtZSgpO1xuICAgICAgXG4gICAgICBpZiAoZmlyc3RTdWNjZXNzb3JWZXJ0ZXhOYW1lID09PSBjeWNsaWNFZGdlVGFyZ2V0VmVydGV4TmFtZSkge1xuICAgICAgICBzdWNjZXNzb3JWZXJ0aWNlcy5zaGlmdCgpO1xuICAgICAgfVxuICAgIH1cblxuICAgIGNvbnN0IGN5Y2xpY0VkZ2VTb3VyY2VWZXJ0ZXhOYW1lID0gcGFydGlhbEN5Y2xlLmdldEN5Y2xpY0VkZ2VTb3VyY2VWZXJ0ZXhOYW1lKCksXG4gICAgICAgICAgY3ljbGljRWRnZVRhcmdldFZlcnRleE5hbWUgPSBwYXJ0aWFsQ3ljbGUuZ2V0Q3ljbGljRWRnZVRhcmdldFZlcnRleE5hbWUoKSxcbiAgICAgICAgICBwcmVkZWNlc3NvclZlcnRleE5hbWVzID0gcGFydGlhbEN5Y2xlLmdldFByZWRlY2Vzc29yVmVydGV4TmFtZXMoKSxcbiAgICAgICAgICBzdWNjZXNzb3JWZXJ0ZXhOYW1lcyA9IHZlcnRleE5hbWVzRnJvbVZlcnRpY2VzKHN1Y2Nlc3NvclZlcnRpY2VzKSxcbiAgICAgICAgICB2ZXJ0ZXhOYW1lcyA9ICh2ZXJ0ZXhOYW1lID09PSBjeWNsaWNFZGdlVGFyZ2V0VmVydGV4TmFtZSkgP1xuICAgICAgICAgICAgICAgICAgICAgICAgICBbXS5jb25jYXQoY3ljbGljRWRnZVRhcmdldFZlcnRleE5hbWUpLmNvbmNhdChwcmVkZWNlc3NvclZlcnRleE5hbWVzKS5jb25jYXQoY3ljbGljRWRnZVNvdXJjZVZlcnRleE5hbWUpIDpcbiAgICAgICAgICAgICAgICAgICAgICAgICAgICBbXS5jb25jYXQocHJlZGVjZXNzb3JWZXJ0ZXhOYW1lcykuY29uY2F0KGN5Y2xpY0VkZ2VTb3VyY2VWZXJ0ZXhOYW1lKS5jb25jYXQoY3ljbGljRWRnZVRhcmdldFZlcnRleE5hbWUpLmNvbmNhdChzdWNjZXNzb3JWZXJ0ZXhOYW1lcyksXG4gICAgICAgICAgY3ljbGUgPSBuZXcgQ3ljbGUodmVydGV4TmFtZXMpO1xuICAgIFxuICAgIHJldHVybiBjeWNsZTtcbiAgfVxufVxuIiwiUmVhY3QuY3JlYXRlRWxlbWVudCJdLCJuYW1lcyI6WyJDeWNsZSIsImZpcnN0IiwiYXJyYXlVdGlsaXRpZXMiLCJ2ZXJ0ZXhOYW1lcyIsImdldFZlcnRleE5hbWVzIiwiZnJvbVZlcnRleE5hbWVQYXJ0aWFsQ3ljbGVBbmRTdWNjZXNzb3JWZXJ0aWNlcyIsInZlcnRleE5hbWUiLCJwYXJ0aWFsQ3ljbGUiLCJzdWNjZXNzb3JWZXJ0aWNlcyIsInNsaWNlIiwic3VjY2Vzc29yVmVydGljZXNMZW5ndGgiLCJsZW5ndGgiLCJmaXJzdFN1Y2Nlc3NvclZlcnRleCIsImZpcnN0U3VjY2Vzc29yVmVydGV4TmFtZSIsImdldE5hbWUiLCJjeWNsaWNFZGdlVGFyZ2V0VmVydGV4TmFtZSIsImdldFRhcmdldFZlcnRleE5hbWUiLCJzaGlmdCIsImN5Y2xpY0VkZ2VTb3VyY2VWZXJ0ZXhOYW1lIiwiZ2V0Q3ljbGljRWRnZVNvdXJjZVZlcnRleE5hbWUiLCJnZXRDeWNsaWNFZGdlVGFyZ2V0VmVydGV4TmFtZSIsInByZWRlY2Vzc29yVmVydGV4TmFtZXMiLCJnZXRQcmVkZWNlc3NvclZlcnRleE5hbWVzIiwic3VjY2Vzc29yVmVydGV4TmFtZXMiLCJ2ZXJ0ZXhOYW1lc0Zyb21WZXJ0aWNlcyIsImNvbmNhdCIsImN5Y2xlIl0sIm1hcHBpbmdzIjoiQUFBQTs7Ozs7OztlQVFxQkE7Ozt5QkFOVTtzQkFFUzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7QUFFeEMsSUFBTSxBQUFFQyxRQUFVQywwQkFBVkQ7QUFFTyxJQUFBLEFBQU1ELHNCQUFOO2FBQU1BLE1BQ1BHLFdBQVc7Z0NBREpIO1FBRWpCLElBQUksQ0FBQ0csY0FBY0E7O2tCQUZGSDs7WUFLbkJJLEtBQUFBO21CQUFBQSxTQUFBQTtnQkFDRSxPQUFPLElBQUksQ0FBQ0Q7WUFDZDs7OztZQUVPRSxLQUFBQTttQkFBUCxTQUFPQSwrQ0FBK0NDLFVBQVUsRUFBRUMsWUFBWSxFQUFFQyxpQkFBaUI7Z0JBQy9GQSxvQkFBb0JBLGtCQUFrQkMsU0FBVSxHQUFHO2dCQUVuRCxJQUFNQywwQkFBMEJGLGtCQUFrQkc7Z0JBRWxELElBQUlELDBCQUEwQixHQUFHO29CQUMvQixJQUFNRSx1QkFBdUJYLE1BQU1PLG9CQUM3QkssMkJBQTJCRCxxQkFBcUJFLFdBQ2hEQyw2QkFBNkJSLGFBQWFTO29CQUVoRCxJQUFJSCw2QkFBNkJFLDRCQUE0Qjt3QkFDM0RQLGtCQUFrQlM7b0JBQ3BCO2dCQUNGO2dCQUVBLElBQU1DLDZCQUE2QlgsYUFBYVksaUNBQzFDSiw4QkFBNkJSLGFBQWFhLGlDQUMxQ0MseUJBQXlCZCxhQUFhZSw2QkFDdENDLHVCQUF1QkMsSUFBQUEsaUNBQXdCaEIsb0JBQy9DTCxjQUFjLEFBQUNHLGVBQWVTLDhCQUNkLEVBQUUsQ0FBQ1UsT0FBT1YsNkJBQTRCVSxPQUFPSix3QkFBd0JJLE9BQU9QLDhCQUMxRSxFQUFFLENBQUNPLE9BQU9KLHdCQUF3QkksT0FBT1AsNEJBQTRCTyxPQUFPViw2QkFBNEJVLE9BQU9GLHVCQUNqSUcsUUFBUSxJQS9CRzFCLE1BK0JPRztnQkFFeEIsT0FBT3VCO1lBQ1Q7OztXQWxDbUIxQiJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi4uL3NyYy9jeWNsZS5qcyIsIjw8anN4LWNvbmZpZy1wcmFnbWEuanM+PiJdLCJzb3VyY2VzQ29udGVudCI6WyJcInVzZSBzdHJpY3RcIjtcblxuaW1wb3J0IHsgdmVydGV4TmFtZXNGcm9tVmVydGV4ZXMgfSBmcm9tIFwiLi91dGlsaXRpZXMvdmVydGV4XCI7XG5cbmV4cG9ydCBkZWZhdWx0IGNsYXNzIEN5Y2xlIHtcbiAgY29uc3RydWN0b3IodmVydGV4TmFtZXMpIHtcbiAgICB0aGlzLnZlcnRleE5hbWVzID0gdmVydGV4TmFtZXM7XG4gIH1cblxuICBnZXRWZXJ0ZXhOYW1lcygpIHtcbiAgICByZXR1cm4gdGhpcy52ZXJ0ZXhOYW1lcztcbiAgfVxuXG4gIHN0YXRpYyBmcm9tU291cmNlVmVydGV4QW5kUHJlZGVjZXNzb3JWZXJ0ZXhlcyhzb3VyY2VWZXJ0ZXgsIHByZWRlY2Vzc29yVmVydGV4ZXMpIHtcbiAgICBjb25zdCB2ZXJ0ZXhlcyA9IFtcbiAgICAgICAgICAgIC4uLnByZWRlY2Vzc29yVmVydGV4ZXMsXG4gICAgICAgICAgICBzb3VyY2VWZXJ0ZXhcbiAgICAgICAgICBdLFxuICAgICAgICAgIHZlcnRleE5hbWVzID0gdmVydGV4TmFtZXNGcm9tVmVydGV4ZXModmVydGV4ZXMpLFxuICAgICAgICAgIGN5Y2xlID0gbmV3IEN5Y2xlKHZlcnRleE5hbWVzKTtcblxuICAgIHJldHVybiBjeWNsZTtcbiAgfVxufVxuIiwiUmVhY3QuY3JlYXRlRWxlbWVudCJdLCJuYW1lcyI6WyJDeWNsZSIsInZlcnRleE5hbWVzIiwiZ2V0VmVydGV4TmFtZXMiLCJmcm9tU291cmNlVmVydGV4QW5kUHJlZGVjZXNzb3JWZXJ0ZXhlcyIsInNvdXJjZVZlcnRleCIsInByZWRlY2Vzc29yVmVydGV4ZXMiLCJ2ZXJ0ZXhlcyIsInZlcnRleE5hbWVzRnJvbVZlcnRleGVzIiwiY3ljbGUiXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7O2VBSXFCQTs7O3NCQUZtQjs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0FBRXpCLElBQUEsQUFBTUEsc0JBQU47YUFBTUEsTUFDUEMsV0FBVztnQ0FESkQ7UUFFakIsSUFBSSxDQUFDQyxjQUFjQTs7a0JBRkZEOztZQUtuQkUsS0FBQUE7bUJBQUFBLFNBQUFBO2dCQUNFLE9BQU8sSUFBSSxDQUFDRDtZQUNkOzs7O1lBRU9FLEtBQUFBO21CQUFQLFNBQU9BLHVDQUF1Q0MsWUFBWSxFQUFFQyxtQkFBbUI7Z0JBQzdFLElBQU1DLFdBQVcsQUFDVCxxQkFBR0QsNEJBRE07b0JBRVREO2lCQUNELEdBQ0RILGNBQWNNLElBQUFBLGlDQUF3QkQsV0FDdENFLFFBQVEsSUFmR1IsTUFlT0M7Z0JBRXhCLE9BQU9PO1lBQ1Q7OztXQWxCbUJSIn0=