feat(util): add sleep, getFnName and retry utility functions and improve error handling

Ovidiu Barabula · Ovidiu Barabula · commit 31826d83cbbf · 2018-03-23T12:07:24.000+02:00
diff --git a/src/util/utility-functions.spec.ts b/src/util/utility-functions.spec.ts
@@ -1,9 +1,14 @@
+import * as chai from 'chai';
+import * as chaiAsPromised from 'chai-as-promised';
+chai.use(chaiAsPromised);
+
 import { assert, expect } from 'chai';
 import 'mocha';
-import { ERRORS, hasNested, limitFn, range } from './utility-functions';
+import { stdout } from 'test-console';
+import { ERRORS, getFnName, hasNested, limitFn, range, retry, sleep } from './utility-functions';
 
 describe('Utility Functions', () => {
-  describe('hasNested', () => {
+  describe('hasNested()', () => {
     it('returns true if object has key', () => {
       const object = {
         key: 'value',
@@ -48,10 +53,25 @@ describe('Utility Functions', () => {
     it('returns false if passed empty path string', () => {
       expect(hasNested({}, '')).to.be.false;
     });
+
+
+    it('throws if first parameter is not an object', () => {
+      assert.throws(() => hasNested(undefined, 'key'), ERRORS.HAS_NESTED_NOT_AN_OBJECT);
+    });
+
+
+    it('throws if first parameter is an array', () => {
+      assert.throws(() => hasNested(['value'], 'key'), ERRORS.HAS_NESTED_NOT_AN_OBJECT);
+    });
+
+
+    it('throws if second parameter is not a string or an array', () => {
+      assert.throws(() => hasNested({}, undefined), ERRORS.HAS_NESTED_NOT_A_STRING);
+    });
   });
 
 
-  describe('limitFn', () => {
+  describe('limitFn()', () => {
     it('returns a function', () => {
       const fn = () => true;
       expect(limitFn(fn)).to.be.a('function');
@@ -102,7 +122,7 @@ describe('Utility Functions', () => {
   });
 
 
-  describe('range', () => {
+  describe('range()', () => {
     it('creates an array from 1 to 5', () => {
       const subject = range(1, 5);
       expect(subject).to.be.an('array');
@@ -149,4 +169,154 @@ describe('Utility Functions', () => {
       assert.throws(() => range(2, 2), ERRORS.RANGE_LIMITS_EQUAL);
     });
   });
+
+
+  describe('getFnName()', () => {
+    it('returns function name', () => {
+      const myFunction = () => true;
+      expect(getFnName(myFunction)).to.equal('function \'myFunction\'');
+    });
+
+
+    it('returns anonymous function name', () => {
+      expect(getFnName(() => true)).to.equal('\'anonymous\' function');
+    });
+  });
+
+
+  describe('sleep()', () => {
+    it('resolves after a 1000ms (default)', async () => {
+      const startTime = Date.now();
+      await sleep();
+      expect((Date.now() - startTime)).to.be.gte(1000 * 0.9);
+    }).timeout(5000);
+
+
+    it('resolves after a 500ms', async () => {
+      const startTime = Date.now();
+      await sleep(500);
+      expect((Date.now() - startTime)).to.be.gte(500 * 0.9);
+    }).timeout(5000);
+
+
+    it('resolves after a 250ms', async () => {
+      const startTime = Date.now();
+      await sleep(250);
+      expect((Date.now() - startTime)).to.be.gte(250 * 0.9);
+    }).timeout(5000);
+  });
+
+
+  describe('retry()', () => {
+    // Helper function to create error prone functions
+    function badFn(fnName: string = 'errorProneFn', workOn?: number, errorNumber: number = 1) {
+      const innerFn = function () {
+        if (workOn && workOn === errorNumber - 1) {
+          return true;
+        }
+        throw new Error(String(errorNumber++));
+      };
+
+      const api = { [fnName]: innerFn };
+      Object.defineProperty(api[fnName], 'name', { value: fnName });
+      return api;
+    }
+
+    it('calls passed in function', async () => {
+      let wasCalled = false;
+      await retry(() => wasCalled = true);
+      expect(wasCalled).to.be.true;
+    });
+
+
+    it('returns the function\'s return value', () => {
+      const returnValue = 'It returns correctly!';
+      const fn = () => returnValue;
+      return expect(retry(fn)).to.eventually.be.equal(returnValue);
+    });
+
+
+    it('works with an empty options object', () => {
+      return expect(retry(() => true, {})).to.be.eventually.true;
+    });
+
+
+    it('ignores bad options', () => {
+      return expect(retry(() => true, { badOption: true })).to.be.eventually.true;
+    });
+
+
+    it('retries 3 times (by default) and returns the last error', () => {
+      const { alwaysErrors } = badFn('alwaysErrors');
+      return expect(retry(alwaysErrors, { delay: 100 })).to.be.rejectedWith(/3/);
+    }).timeout(5000);
+
+
+    it('retries a custom number of times before it returns the error', () => {
+      const { errorProneFn } = badFn(undefined, 2);
+      return expect(retry(errorProneFn, { delay: 100, retries: 2 })).to.be.rejectedWith(/2/);
+    }).timeout(5000);
+
+
+    it('retries 1 time and returns function\'s return value', () => {
+      const { fnErrorsOnce } = badFn('fnErrorsOnce', 1);
+      return expect(retry(fnErrorsOnce)).to.be.fulfilled;
+    }).timeout(5000);
+
+    it('throws the error of a rejected promise', () => {
+      const rejectPromiseFn = () => Promise.reject(new Error('Intentionally rejected promise'));
+      return expect(retry(rejectPromiseFn, { delay: 100 }))
+        .to.be.rejectedWith(RegExp('Intentionally rejected promise'));
+    }).timeout(5000);
+
+
+    it('throws if first parameter <fn> is not a function', () => {
+      return expect(retry(undefined)).to.be.rejectedWith(ERRORS.RETRY_NEEDS_A_FUNCTION);
+    });
+
+
+    it('throws if second parameter <options> is not an object', () => {
+      return expect(retry(() => true, 1)).to.be.rejectedWith(ERRORS.RETRY_NEEDS_OPTIONS_TO_BE_OBJECT);
+    });
+
+
+    it('throws if option <delay> is 0', () => {
+      return expect(retry(() => true, { delay: 0 })).to.be.rejectedWith(ERRORS.RETRY_DELAY_CANNOT_BE_ZERO);
+    });
+
+
+    it('throws if option <retries> is 0', () => {
+      return expect(retry(() => true, { retries: 0 })).to.be.rejectedWith(ERRORS.RETRY_RETRIES_CANNOT_BE_ZERO);
+    });
+
+
+    describe('retry() logging', () => {
+      let inspect: any;
+
+      beforeEach(() => inspect = stdout.inspect());
+      afterEach(() => {
+        inspect.restore();
+
+        // Console out the output from the console.log stub
+        for (const output of inspect.output) {
+          // Clean up by removing new line characters
+          console.log(output.replace('\n', ''));
+        }
+      });
+
+
+      it('accepts custom logger namespace', async () => {
+        const { alwaysErrorsFn } = badFn('alwaysErrorsFn');
+        await retry(alwaysErrorsFn, { logNamespace: 'customNamespace', retries: 1 }).catch(ignore => undefined);
+        expect(inspect.output.join(' ')).to.have.string('customNamespace');
+      }).timeout(5000);
+
+
+      it('accepts custom logger channel', async () => {
+        const { alwaysErrorsFn } = badFn('alwaysErrorsFn');
+        await retry(alwaysErrorsFn, { logChannel: 'customChannel', retries: 1 }).catch(ignore => undefined);
+        expect(inspect.output.join(' ')).to.have.string('customChannel');
+      }).timeout(5000);
+    });
+  });
 });
diff --git a/src/util/utility-functions.ts b/src/util/utility-functions.ts
@@ -5,6 +5,8 @@
  * @since 0.1.0
  */
 
+import Logger, { ILogger } from './logger';
+
 export interface NestedObject {
   [key: string]: any;
 }
@@ -13,11 +15,24 @@ export type AnyFunction = (...args: any[]) => any;
 
 
 export const ERRORS = {
-  LIMIT_NOT_A_NUMBER: 'Limit argument must be a number',
-  NOT_A_FUNCTION: 'Passed argument is not a function',
-  RANGE_LIMITS_EQUAL: 'Range limits cannot be equal',
-  RANGE_NEEDS_NUMBERS: 'Range limit arguments must be numbers',
-  RANGE_NEEDS_TWO_PARAMS: 'Range requires two number parameters',
+  // hasNested()
+  HAS_NESTED_NOT_AN_OBJECT: 'hasNested() requires first argument <object> to be of type \'object\'',
+  HAS_NESTED_NOT_A_STRING: 'hasNested() requires second argument <path> to be of type \'string\' or \'array\' of strings',
+
+  // limitFn()
+  LIMIT_NOT_A_NUMBER: 'limitFn() requires second argument to be of type \'number\'',
+  NOT_A_FUNCTION: 'limitFn() requires first argument to be of type \'function\'',
+
+  // range()
+  RANGE_LIMITS_EQUAL: 'range() limits cannot be equal',
+  RANGE_NEEDS_NUMBERS: 'range() requires both arguments to be of type \'number\'',
+  RANGE_NEEDS_TWO_PARAMS: 'range() requires two arguments of type \'number\'',
+
+  // retry()
+  RETRY_DELAY_CANNOT_BE_ZERO: 'retry() option <delay> cannot be 0ms',
+  RETRY_NEEDS_A_FUNCTION: 'retry() requires first argument <fn> to be of type \'function\'',
+  RETRY_NEEDS_OPTIONS_TO_BE_OBJECT: 'retry() requires second argument <options> to be of type \'object\'',
+  RETRY_RETRIES_CANNOT_BE_ZERO: 'retry() option <retries> cannot be 0',
 };
 
 
@@ -27,6 +42,15 @@ export const ERRORS = {
  * @param path Dot notation path, regular key string or array of keys
  */
 export function hasNested(object: NestedObject, path: string | string[]): boolean {
+  // Arguments validation
+  if (typeof object !== 'object' || Array.isArray(object)) {
+    throw new Error(ERRORS.HAS_NESTED_NOT_AN_OBJECT);
+  }
+
+  if (typeof path !== 'string' && !Array.isArray(path)) {
+    throw new Error(ERRORS.HAS_NESTED_NOT_A_STRING);
+  }
+
   // If path is dot notation (e.g. 'object.child.subchild')
   if (typeof path === 'string' && path.includes('.')) {
     path = path.split('.');
@@ -105,3 +129,120 @@ export function range(from: number, to: number): number[] {
   // This keeps the above loop the same in both cases
   return direction > 0 ? array : array.reverse();
 }
+
+
+/**
+ * Resolves a promise after a custom amount of time
+ * @param ms Number of miliseconds to sleep
+ */
+export function sleep(ms: number = 1000): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+
+/**
+ * Get function name
+ */
+export function getFnName(fn: AnyFunction): string {
+  return fn.name
+    ? `function '${fn.name}'`
+    : '\'anonymous\' function';
+}
+
+
+/**
+ * Takes a function and calls it, when and if it fails,
+ * it retries until it reaches max number of retries
+ * @param fn Function to be called
+ * @param options Options object
+ * @return Function's return value or last error
+ */
+export async function retry(
+  fn: AnyFunction,
+  options: {
+    // Delay in miliseconds until retry
+    delay?: number,
+    // Maximum number of retries
+    retries?: number,
+    // Custom log channel
+    logChannel?: string,
+    // Custom log namespace
+    logNamespace?: string,
+  } = {},
+): Promise<any> {
+  // Arguments validation
+  if (typeof fn !== 'function') {
+    throw new Error(ERRORS.RETRY_NEEDS_A_FUNCTION);
+  }
+
+  if (typeof options !== 'object') {
+    throw new Error(ERRORS.RETRY_NEEDS_OPTIONS_TO_BE_OBJECT);
+  }
+
+  // Get options with defaults
+  const {
+    delay = 1000,
+    retries = 3,
+    logChannel = 'retry()',
+    logNamespace = 'frontvue',
+  } = options;
+
+  // Options validation
+  if (delay === 0) {
+    throw new Error(ERRORS.RETRY_DELAY_CANNOT_BE_ZERO);
+  } else if (retries === 0) {
+    throw new Error(ERRORS.RETRY_RETRIES_CANNOT_BE_ZERO);
+  }
+
+  // Internal retry counter
+  let count: number = 0;
+  // Array to store the errors
+  const errors: Error[] = [];
+  // Logger instance
+  const logger: ILogger = Logger(logNamespace)(logChannel);
+
+
+  /**
+   * Handle error and retry
+   * @param error Caught error
+   */
+  function errorHandler(error: Error) {
+    count++;
+
+    // If this is the first retry notify the user
+    if (count === 1) {
+      logger.warn(`${getFnName(fn)} failed. Retrying...`);
+    }
+
+    // Output a nice console log for each retry
+    let logMessage = `Retrying ${getFnName(fn)} (retries left: ${retries - count})`;
+    logMessage += count === retries ? ' Aborting...' : '';
+    logger.debug(logMessage);
+
+    // Storing the error
+    errors.push(error);
+  }
+
+  // Returning a function for async functionality
+  return new Promise(async (resolve, reject) => {
+    // Stay within the maximum number of retries
+    while (count < retries) {
+      try {
+        // Happy path: resolve promise with the function's return value
+        // Here we're also converting the return value to a promise
+        // just in case it's not an async function
+        // We're also catching any errors and re-throwing them to be catched by the errorHandler
+        return resolve(
+          await Promise.resolve(fn()).catch(error => { throw error; }),
+        );
+      } catch (error) {
+        errorHandler(error);
+      }
+      // Wait a bit until we try to call again
+      await sleep(delay);
+    }
+
+    // Finally, nothing seems to work, reject the promise with the last error
+    return reject(errors[errors.length - 1]);
+  });
+}
