Merge pull request benbria#1 from benbria/retry

Add retry()

Author: jwalton

README.md

@@ -42,6 +42,7 @@ Then somewhere in your node.js application:
 * [`series`](#series)
 * [`timeout`](#timeout)
 * [`whilst`](#whilst), `doWhilst`
+* [`retry`](#retry)
 
 
 # Utilities
@@ -161,3 +162,37 @@ Example:
     .then(function(result) {
        // result will be 10 here.
     });
+
+<a name="retry"/>
+### retry(options, fn)
+
+Will continuously call `fn` until it returns a synchronous value, doesn't throw, or returns a Promise that resolves. It will be retried `options.times`. You can pass `{times: Infinity}` to retry indefinitely. The `fn` will be passed the `lastAttempt` object which is the Error object of the last attempt.
+
+Options: `times` (Default=5) and `interval` (Default=0). `interval` is the time between retries in milliseconds. If the `options` argument is passed as just a number, only `times` will be set.
+
+Examples:
+
+    var count = 0;
+    promiseTools.retry({times: 4, interval: 5}, function(lastAttempt) {
+        count++;
+        if (count === 2) Promise.resolve(true);
+        else Promise.reject(new Error('boom'));
+    })
+    .then(function(result) {
+       // result will be `true` here.
+    });
+
+    ---------------------------------------------
+
+    var count = 0;
+    promiseTools.retry(1, function(lastAttempt) {
+        count++;
+        if (count === 2) Promise.resolve(true);
+        else Promise.reject(new Error('boom'));
+    })
+    .then(function(result) {
+       // will not resolve.
+    })
+    .catch(function(err) {
+        // err.message should be `boom` here.
+    });

src/index.js

@@ -190,3 +190,51 @@ exports.doWhilst = (fn, test) => {
     };
     return exports.whilst(doTest, fn);
 };
+
+/*
+ * 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 = 0;
+    let lastAttempt = null;
+
+    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));
+    }
+
+    return new Promise((resolve, reject) => {
+        let doIt = () => {
+            Promise.resolve()
+            .then(() => {
+                return fn(lastAttempt);
+            })
+            .then(resolve)
+            .catch((err) => {
+                attempts++;
+                lastAttempt = err;
+                if (times !== Infinity && attempts === times) {
+                    reject(lastAttempt);
+                } else {
+                    setTimeout(doIt, interval);
+                }
+            });
+        };
+        doIt();
+    });
+};

test/retry.js

@@ -0,0 +1,61 @@
+"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(Infinity, getTest(3));
+        return expect(retry).to.eventually.equal(3);
+    });
+
+    it('should reject', (done) => {
+        let retry = promiseTools.retry(3, getTest(4));
+        retry.catch((lastAttempt) => {
+            try {
+                expect(lastAttempt).to.be.instanceof(Error);
+                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');
+    });
+});