[Ordering] add bias constraints to graph opts

Add ability to pass in a list of graph constraints (list of high node vs
low node relationships) to influence the ordering of the graph. Useful
for picking which way edges go and for making a layout more 'stable'
(the onesignal use case is making all branch edges of the same type go
the same way).

This is essentially this commit by izhan
izhan@4b40097
in this PR dagrejs#302
with a couple changes - high/low over left/right plus some type
overrides (alternatively could fork definitelytyped and put the changes
there)

index.d.ts

@@ -0,0 +1,15 @@
+import "dagre";
+
+declare module "dagre" {
+  interface Constraint {
+    high: string;
+    low: string;
+  }
+
+  interface Options {
+    constraints?: Constraint[];
+  }
+
+  function layout(g: graphlib.Graph, opts: Options): void;
+}
+

lib/layout.js

@@ -17,17 +17,18 @@ var Graph = require("./graphlib").Graph;
 
 module.exports = layout;
 
-function layout(g, opts) {
+function layout(g, inputOpts) {
+  var opts = inputOpts || {};
   var time = opts && opts.debugTiming ? util.time : util.notime;
   time("layout", function() {
     var layoutGraph = 
       time("  buildLayoutGraph", function() { return buildLayoutGraph(g); });
-    time("  runLayout",        function() { runLayout(layoutGraph, time); });
+    time("  runLayout",        function() { runLayout(layoutGraph, time, opts); });
     time("  updateInputGraph", function() { updateInputGraph(g, layoutGraph); });
   });
 }
 
-function runLayout(g, time) {
+function runLayout(g, time, opts) {
   time("    makeSpaceForEdgeLabels", function() { makeSpaceForEdgeLabels(g); });
   time("    removeSelfEdges",        function() { removeSelfEdges(g); });
   time("    acyclic",                function() { acyclic.run(g); });
@@ -42,7 +43,7 @@ function runLayout(g, time) {
   time("    normalize.run",          function() { normalize.run(g); });
   time("    parentDummyChains",      function() { parentDummyChains(g); });
   time("    addBorderSegments",      function() { addBorderSegments(g); });
-  time("    order",                  function() { order(g); });
+  time("    order",                  function() { order(g, opts); });
   time("    insertSelfEdges",        function() { insertSelfEdges(g); });
   time("    adjustCoordinateSystem", function() { coordinateSystem.adjust(g); });
   time("    position",               function() { position(g); });

lib/order/index.js

@@ -26,7 +26,7 @@ module.exports = order;
  *    1. Graph nodes will have an "order" attribute based on the results of the
  *       algorithm.
  */
-function order(g) {
+function order(g, opts) {
   var maxRank = util.maxRank(g),
     downLayerGraphs = buildLayerGraphs(g, _.range(1, maxRank + 1), "inEdges"),
     upLayerGraphs = buildLayerGraphs(g, _.range(maxRank - 1, -1, -1), "outEdges");
@@ -37,15 +37,18 @@ function order(g) {
   var bestCC = Number.POSITIVE_INFINITY,
     best;
 
+  var constraints = opts.constraints || [];
   for (var i = 0, lastBest = 0; lastBest < 4; ++i, ++lastBest) {
-    sweepLayerGraphs(i % 2 ? downLayerGraphs : upLayerGraphs, i % 4 >= 2);
+    sweepLayerGraphs(i % 2 ? downLayerGraphs : upLayerGraphs, i % 4 >= 2, constraints);
 
     layering = util.buildLayerMatrix(g);
     var cc = crossCount(g, layering);
     if (cc < bestCC) {
       lastBest = 0;
       best = _.cloneDeep(layering);
       bestCC = cc;
+    } else if (cc === bestCC) {
+      best = _.cloneDeep(layering);
     }
   }
 
@@ -58,8 +61,13 @@ function buildLayerGraphs(g, ranks, relationship) {
   });
 }
 
-function sweepLayerGraphs(layerGraphs, biasRight) {
+function sweepLayerGraphs(layerGraphs, biasRight, constraints) {
   var cg = new Graph();
+
+  _.forEach(constraints, function(constraint) {
+    cg.setEdge(constraint.high, constaint.low);
+  });
+
   _.forEach(layerGraphs, function(lg) {
     var root = lg.graph().root;
     var sorted = sortSubgraph(lg, root, cg, biasRight);

test/order/order-test.js

@@ -20,7 +20,7 @@ describe("order", function() {
     g.setPath(["a", "b", "c"]);
     g.setEdge("b", "d");
     g.setPath(["a", "e", "f"]);
-    order(g);
+    order(g, {});
     var layering = util.buildLayerMatrix(g);
     expect(crossCount(g, layering)).to.equal(0);
   });
@@ -30,7 +30,7 @@ describe("order", function() {
     _.forEach(["a", "d"], function(v) { g.setNode(v, { rank: 1 }); });
     _.forEach(["b", "f", "e"], function(v) { g.setNode(v, { rank: 2 }); });
     _.forEach(["c", "g"], function(v) { g.setNode(v, { rank: 3 }); });
-    order(g);
+    order(g, {});
     var layering = util.buildLayerMatrix(g);
     expect(crossCount(g, layering)).to.equal(0);
   });
@@ -40,7 +40,7 @@ describe("order", function() {
     _.forEach(["b", "e", "g"], function(v) { g.setNode(v, { rank: 2 }); });
     _.forEach(["c", "f", "h"], function(v) { g.setNode(v, { rank: 3 }); });
     g.setNode("d", { rank: 4 });
-    order(g);
+    order(g, {});
     var layering = util.buildLayerMatrix(g);
     expect(crossCount(g, layering)).to.be.lte(1);
   });