Implement async's retry. Added some different features.

Followed async's api. Added ability to retry forever. Also allows the
`fn` parameter to be synchronous or Promise based. async's version could
only be callback based.

Author: calvinwiebe

src/index.js

@@ -190,3 +190,57 @@ exports.doWhilst = (fn, test) => {
     };
     return exports.whilst(doTest, fn);
 };
+
+exports.FOREVER = -1;
+
+/*
+ * keep calling `fn` until it returns a non-error value, doesn't throw, or returns a Promise that resolves. `fn` will be
+ * attempted `times` many times before rejecting. If `times` is given as `exports.FOREVER`, then `retry` will attempt to
+ * resolve forever (useful if you are just waiting for something to finish).
+ * @param {Object|Number} options hash to provide `times` and `interval`. Defaults (times=5, interval=0). If this value
+ *                        is a number, only `times` will be set.
+ * @param {Function}      fn the task/check to be performed. Can either return a synchronous value, throw an error, or
+ *                        return a promise
+ * @returns {Promise}
+ */
+exports.retry = (options, fn) => {
+    let times = 5;
+    let interval = 0;
+    let attempts = [];
+    let infinite = false;
+
+    if ('number' === typeof(options)) {
+        times = options;
+    }
+    else if ('object' === typeof(options)) {
+        if (options.times) times = parseInt(options.times, 10);
+        if (options.interval) interval = parseInt(options.interval, 10);
+    }
+    else {
+        throw new Error('Unsupported argument type for \'times\': ' + typeof(options));
+    }
+
+    if (times === exports.FOREVER) infinite = true;
+
+    return new Promise((resolve, reject) => {
+        let doIt = () => {
+            Promise.resolve()
+            .then(() => {
+                return fn(attempts[attempts.length - 1]);
+            })
+            .then((results) => {
+                if (results instanceof Error) throw results;
+                else resolve(results);
+            })
+            .catch((err) => {
+                attempts.push(err);
+                if (!infinite && attempts.length === times) {
+                    reject(attempts);
+                } else {
+                    setTimeout(doIt, interval);
+                }
+            });
+        };
+        doIt();
+    });
+};

test/retry.js

@@ -0,0 +1,69 @@
+"use strict"
+
+let chai = require('chai');
+chai.use(require('chai-as-promised'));
+let expect = chai.expect;
+let promiseTools = require('../src');
+
+let callCount = 0;
+let getTest = (times) => {
+    return () => {
+        callCount++;
+        if (callCount === times) return callCount;
+        else throw new Error('not done yet');
+    }
+}
+
+describe('retry', () => {
+    beforeEach(() => {
+        callCount = 0;
+    });
+
+    it('should retry infinitely and resolve', () => {
+        let retry = promiseTools.retry(-1, getTest(3));
+        return expect(retry).to.eventually.equal(3);
+    });
+
+    it('should reject', (done) => {
+        let retry = promiseTools.retry(3, getTest(4));
+        retry.catch((attempts) => {
+            try {
+                expect(attempts.length).to.eq(3);
+                done();
+            } catch (err) {
+                done(err);
+            }
+        })
+    });
+
+    [
+        {options: {times: 5, interval: 10}, msg: 'times and interval'},
+        {options: {times: 5}, msg: 'just times'},
+        {options: {}, msg: 'neither times nor interval'}
+    ].forEach((args) => {
+        it(`should accept first argument as an options hash with ${args.msg}`, () => {
+            let retry = promiseTools.retry(args.options, getTest(5));
+            return expect(retry).to.eventually.equal(5);
+        });
+    });
+
+    it('should return an error with invalid options argument', () => {
+        let p = Promise.resolve().then(() => {
+            // had to do this for some reason. Otherwise `chai-as-promised` always passed erroneously.
+            try {
+                return promiseTools.retry(undefined, getTest(1));
+            } catch (err) {
+                throw err;
+            }
+        });
+        expect(p).to.eventually.be.rejectedWith('Unsupported argument type for \'times\': undefined');
+    });
+
+    it('should reject when an Error value is resolved', () => {
+        let retry = promiseTools.retry(1, () => {
+            return new Error('boom');
+        });
+        return expect(retry).to.eventually.be.rejectedWith('boom');
+    });
+
+});