feat: Canceling flows (#1542)

* cancelable foreach

* cancelable waterfall

* cancellable auto

* fix lint

* fix tests

* cancelable whilst/until/during/forever

* fix waterfall test.  It WILL get there

* docs

* auto should not start other tasks once canceled

* simplify waterfall, add test for arrays

* simplify eachOf

* cancelable retry

* cancelable eachOf for arrays

* revert test tweak

11 files changed, 29 insertions, 3 deletions

diff --git a/lib/auto.js b/lib/auto.js
index a6150aa..500620a 100644
--- a/lib/auto.js
+++ b/lib/auto.js
@@ -102,6 +102,7 @@ export default function (tasks, concurrency, callback) {
 
     var results = {};
     var runningTasks = 0;
+    var canceled = false;
     var hasError = false;
 
     var listeners = Object.create(null);
@@ -156,6 +157,7 @@ export default function (tasks, concurrency, callback) {
     }
 
     function processQueue() {
+        if (canceled) return
         if (readyTasks.length === 0 && runningTasks === 0) {
             return callback(null, results);
         }
@@ -189,6 +191,10 @@ export default function (tasks, concurrency, callback) {
 
         var taskCallback = onlyOnce(function(err, result) {
             runningTasks--;
+            if (err === false) {
+                canceled = true
+                return
+            }
             if (arguments.length > 2) {
                 result = slice(arguments, 1);
             }
@@ -200,7 +206,7 @@ export default function (tasks, concurrency, callback) {
                 safeResults[key] = result;
                 hasError = true;
                 listeners = Object.create(null);
-
+                if (canceled) return
                 callback(err, safeResults);
             } else {
                 results[key] = result;
diff --git a/lib/doDuring.js b/lib/doDuring.js
index ac2a04c..5eb2b92 100644
--- a/lib/doDuring.js
+++ b/lib/doDuring.js
@@ -30,6 +30,7 @@ export default function doDuring(fn, test, callback) {
 
     function next(err/*, ...args*/) {
         if (err) return callback(err);
+        if (err === false) return;
         var args = slice(arguments, 1);
         args.push(check);
         _test.apply(this, args);
@@ -37,6 +38,7 @@ export default function doDuring(fn, test, callback) {
 
     function check(err, truth) {
         if (err) return callback(err);
+        if (err === false) return;
         if (!truth) return callback(null);
         _fn(next);
     }
diff --git a/lib/doWhilst.js b/lib/doWhilst.js
index 3c2b865..5245820 100644
--- a/lib/doWhilst.js
+++ b/lib/doWhilst.js
@@ -31,6 +31,7 @@ export default function doWhilst(iteratee, test, callback) {
     var _iteratee = wrapAsync(iteratee);
     var next = function(err/*, ...args*/) {
         if (err) return callback(err);
+        if (err === false) return;
         var args = slice(arguments, 1);
         if (test.apply(this, args)) return _iteratee(next);
         callback.apply(null, [null].concat(args));
diff --git a/lib/during.js b/lib/during.js
index cda9979..02da045 100644
--- a/lib/during.js
+++ b/lib/during.js
@@ -45,11 +45,13 @@ export default function during(test, fn, callback) {
 
     function next(err) {
         if (err) return callback(err);
+        if (err === false) return;
         _test(check);
     }
 
     function check(err, truth) {
         if (err) return callback(err);
+        if (err === false) return;
         if (!truth) return callback(null);
         _fn(next);
     }
diff --git a/lib/eachOf.js b/lib/eachOf.js
index bb9edfa..5dbeb81 100644
--- a/lib/eachOf.js
+++ b/lib/eachOf.js
@@ -12,12 +12,17 @@ function eachOfArrayLike(coll, iteratee, callback) {
     callback = once(callback || noop);
     var index = 0,
         completed = 0,
-        length = coll.length;
+        length = coll.length,
+        canceled = false;
     if (length === 0) {
         callback(null);
     }
 
     function iteratorCallback(err, value) {
+        if (err === false) {
+            canceled = true
+        }
+        if (canceled === true) return
         if (err) {
             callback(err);
         } else if ((++completed === length) || value === breakLoop) {
diff --git a/lib/forever.js b/lib/forever.js
index 3753251..fb69adf 100644
--- a/lib/forever.js
+++ b/lib/forever.js
@@ -38,6 +38,7 @@ export default function forever(fn, errback) {
 
     function next(err) {
         if (err) return done(err);
+        if (err === false) return;
         task(next);
     }
     next();
diff --git a/lib/internal/eachOfLimit.js b/lib/internal/eachOfLimit.js
index 6ce0762..ae153b1 100644
--- a/lib/internal/eachOfLimit.js
+++ b/lib/internal/eachOfLimit.js
@@ -14,15 +14,21 @@ export default function _eachOfLimit(limit) {
         }
         var nextElem = iterator(obj);
         var done = false;
+        var canceled = false;
         var running = 0;
         var looping = false;
 
         function iterateeCallback(err, value) {
+            if (canceled) return
             running -= 1;
             if (err) {
                 done = true;
                 callback(err);
             }
+            else if (err === false) {
+                done = true;
+                canceled = true;
+            }
             else if (value === breakLoop || (done && running <= 0)) {
                 done = true;
                 return callback(null);
diff --git a/lib/retry.js b/lib/retry.js
index 390fd55..ef04406 100644
--- a/lib/retry.js
+++ b/lib/retry.js
@@ -133,6 +133,7 @@ export default function retry(opts, task, callback) {
     var attempt = 1;
     function retryAttempt() {
         _task(function(err) {
+            if (err === false) return
             if (err && attempt++ < options.times &&
                 (typeof options.errorFilter != 'function' ||
                     options.errorFilter(err))) {
diff --git a/lib/tryEach.js b/lib/tryEach.js
index 87fba12..82649b4 100644
--- a/lib/tryEach.js
+++ b/lib/tryEach.js
@@ -52,7 +52,7 @@ export default function tryEach(tasks, callback) {
                 result = res;
             }
             error = err;
-            callback(!err);
+            callback(err ? null : {});
         });
     }, function () {
         callback(error, result);
diff --git a/lib/waterfall.js b/lib/waterfall.js
index 3e71d2c..ceaf59d 100644
--- a/lib/waterfall.js
+++ b/lib/waterfall.js
@@ -75,6 +75,7 @@ export default  function(tasks, callback) {
     }
 
     function next(err/*, ...args*/) {
+        if (err === false) return
         if (err || taskIndex === tasks.length) {
             return callback.apply(null, arguments);
         }
diff --git a/lib/whilst.js b/lib/whilst.js
index da748fa..32c3b52 100644
--- a/lib/whilst.js
+++ b/lib/whilst.js
@@ -44,6 +44,7 @@ export default function whilst(test, iteratee, callback) {
     if (!test()) return callback(null);
     var next = function(err/*, ...args*/) {
         if (err) return callback(err);
+        if (err === false) return;
         if (test()) return _iteratee(next);
         var args = slice(arguments, 1);
         callback.apply(null, [null].concat(args));