Add whilst, doWhilst.

Author: Jason Walton

README.md

@@ -41,6 +41,7 @@ Then somewhere in your node.js application:
 * [`parallel`](#parallel), `parallelLimit`
 * [`series`](#series)
 * [`timeout`](#timeout)
+* [`whilst`](#whilst), `doWhilst`
 
 
 # Utilities
@@ -119,7 +120,6 @@ Example:
     });
 
 
-
 <a name="timeout"/>
 ### timeout(promise, ms)
 
@@ -136,3 +136,28 @@ Example:
     // Will reject if `doSomething` takes longer than 500 milliseconds.
     promiseTools.timeout(doSomething(), 500)
     .then(...)
+
+<a name="whilst"/>
+### whilst(fn, test), doWhilst(test, fn)
+
+While the synchronous function `test()` returns true, `whilst` will continuously execute `fn()`.  `fn()` should return
+a Promise.  `whilst` will resolve to the same value as the final call to `fn()`.  If `fn()` or `test()` throw an error,
+then `whilst()` will reject immediately.
+
+`doWhilst()` is similar to `whilst()`, but `whilst()` might execute `fn()` zero times if `test()` returns false on the
+first run, where `doWhilst()` is guaranteed to call `fn()` at least once.  Note that the parameters are reversed
+between `whilst()` and `doWhilst()`.
+
+Example:
+
+    var count = 0;
+    promiseTools.whilst(
+        function() {
+            count++;
+            return Promise.resolve(count);
+        },
+        function() {return count > 10;}
+    )
+    .then(function(result) {
+       // result will be 10 here.
+    });

src/index.js

@@ -146,3 +146,47 @@ exports.timeout = (p, ms) =>
             }
         );
     });
+
+/*
+ * Continually call `fn()` while `test()` returns true.
+ *
+ * `fn()` should return a Promise.  `test()` is a synchronous function which returns true of false.
+ *
+ * `whilst` will resolve to the last value that `fn()` resolved to, or will reject immediately with an error if
+ * `fn()` rejects or if `fn()` or `test()` throw.
+ */
+exports.whilst = (test, fn) =>
+    new Promise((resolve, reject) => {
+        let lastResult = null;
+        let doIt = () => {
+            try {
+                if(test()) {
+                    Promise.resolve()
+                    .then(fn)
+                    .then(
+                        (result) => {
+                            lastResult = result;
+                            setTimeout(doIt, 0);
+                        },
+                        reject
+                    );
+                } else {
+                    resolve(lastResult);
+                }
+            } catch (err) {
+                reject(err);
+            }
+        };
+
+        doIt();
+    });
+
+exports.doWhilst = (fn, test) => {
+    let first = true;
+    let doTest = () => {
+        let answer = first || test();
+        first = false;
+        return answer;
+    };
+    return exports.whilst(doTest, fn);
+};

test/whilst.js

@@ -0,0 +1,111 @@
+"use strict"
+
+let chai = require('chai');
+chai.use(require('chai-as-promised'));
+let expect = chai.expect;
+let promiseTools = require('../src');
+
+describe('whilst', () => {
+
+    it('should execute a function over and over until the test returns true', () => {
+        let count = 0;
+        return expect(
+            promiseTools.whilst(
+                () => count < 10,
+                () => {
+                    count++;
+                    return Promise.resolve(count);
+                }
+            )
+        ).to.eventually.equal(10)
+        .then( () => expect(count).to.equal(10) );
+    });
+
+    it('should work, even if fn does not return a promise', () => {
+        let count = 0;
+        return expect(
+            promiseTools.whilst(
+                () => count < 10,
+                () => {
+                    count++;
+                    return count;
+                }
+            )
+        ).to.eventually.equal(10)
+    });
+
+    it('should return `null` if `test` returns false immediately', () => {
+        let fnCalled = false;
+        return expect(
+            promiseTools.whilst(
+                () => false,
+                () => {fnCalled = true;}
+            )
+        ).to.eventually.equal(null)
+        .then(() => expect(fnCalled).to.be.false)
+    });
+
+    it('should reject if fn rejects', () => {
+        let count = 0;
+        return expect(
+            promiseTools.whilst(
+                () => count < 10,
+                () => Promise.reject(new Error('foo'))
+            )
+        ).to.be.rejectedWith('foo');
+    });
+
+    it('should reject if fn throws', () => {
+        let count = 0;
+        return expect(
+            promiseTools.whilst(
+                () => count < 10,
+                () => {
+                    throw new Error('foo');
+                }
+            )
+        ).to.be.rejectedWith('foo');
+    });
+
+    it('should reject if test throws', () => {
+        return expect(
+            promiseTools.whilst(
+                () => {throw new Error('foo');},
+                () => {}
+            )
+        ).to.be.rejectedWith('foo');
+    });
+
+});
+
+describe('doWhilst', () => {
+
+    it('should execute a function over and over until the test returns true', () => {
+        let count = 0;
+        return expect(
+            promiseTools.doWhilst(
+                () => {
+                    count++;
+                    return Promise.resolve(count);
+                },
+                () => count < 10
+            )
+        ).to.eventually.equal(10)
+        .then( () => expect(count).to.equal(10) );
+    });
+
+    it('should call fn once, even if test returns false immediately', () => {
+        let fnCount = 0;
+        return expect(
+            promiseTools.doWhilst(
+                () => {
+                    fnCount++;
+                    return "hello";
+                },
+                () => false
+            )
+        ).to.eventually.equal("hello")
+        .then( () => expect(fnCount).to.equal(1) );
+    });
+
+});