ts-retry

A little retry tool to execute a function until the function is successful. Can also bind a timeout to a function. This lib is usable in typescript, in javascript, in node, in SPA tools (rest, Vue, Svelte...) and browser (available in ESM and common js format).

---

Breaking change: To migrate to 3.x: retryAsyncDecorator and retryAsync ahs been move in utils/decorators. These impact only those that import those functions directly from decorator.ts file Other 3.X items are new and implies no breaking change.

For those who are using 1.x in typescript, you may have to add a type to RetryOptions if you want to use the new untilfunction. This type is the called function returns type.

---

How to

• to retry something:

  1const result = await retry(
  2  () => {
  3    /* do something */
  4  },
  5  { delay: 100, maxTry: 5 }
  6);

• to retry something async :

  1const result = await retryAsync(
  2  async () => {
  3    /* do something */
  4  },
  5  { delay: 100, maxTry: 5 }
  6);

• to retry until the answer is 42 :

  1try {
  2  await retryAsync(
  3    async () => {
  4      /* do something */
  5    },
  6    {
  7      delay: 100,
  8      maxTry: 5,
  9      until: (lastResult) => lastResult === 42,
  10    }
  11  );
  12} catch (err) {
  13  if (isTooManyTries(err)) {
  14    // Did not get 42 after 'maxTry' calls
  15  } else {
  16    // something else goes wrong
  17  }
  18}

• Need to call a function at multiple locations with same retryOptions ? Use decorators:

  1const fn = (param1: string, param2:number) => /* do something */;
  2const decoratedFn = retryDecorator(
  3  fn,
  4  { delay:100, maxTry:5 }
  5);
  6const title1 = await decoratedFn("value1", 1);
  7const title2 = await decoratedFn("valueXXX", 2);
  8
  9const fn = async (name: string): Promise<any> => { /* something async */ };
  10const decoratedFn = retryAsyncDecorator(
  11  fn,
  12  { delay:100, maxTry:5 }
  13);
  14const result1 = await decoratedFn("Smith");
  15const result2 = await decoratedFn("Doe");

• to wait:

  1await wait(10000); // Wait for 10 seconds

• to set a timeout:

  1try {
  2  const result = await waitUntil(
  3    ()=> {/* do something */},
  4    10000
  5  );
  6} catch (err) {
  7  if (isTimeoutError(error)) { {
  8    // fn does not complete after 10 seconds
  9  } else {
  10    // fn throws an exception
  11  }
  12}

• to set a timeout on something async:

  1try {
  2  const result = await waitUntilAsync(async () => {
  3    /* do something */
  4  }, 10000);
  5} catch (err) {
  6  if (isTimeoutError(error)) {
  7    // fn does not complete after 10 seconds
  8  } else {
  9    // fn throws an exception
  10  }
  11}

• Need to call a function at multiple locations with same retryOptions ? Use decorators:

  1  const fn = (title: string, count:number) => /* a long task */;
  2  const decoratedFn = waitUntilDecorator(
  3    fn,
  4    { delay:100, maxTry:5 }
  5  );
  6  const title1 = await decoratedFn("Intro", 1);
  7  const title2 = await decoratedFn("A chapter", 2);

  1const fn = async (name: string): Promise<any> => {
  2  /* a long task */
  3};
  4const decoratedFn = waitUntilAsyncDecorator(fn, { delay: 100, maxTry: 5 });
  5const result1 = await decoratedFn("John");
  6const result2 = await decoratedFn("Doe");

---

Utils

retry comes with handy utilities function for common use case:

• to retry until a function returns something defined (aka not null neither not undefined):

1  // in all cases results is a string and cannot be null or undefined
2  const result = await retryUntilDefined( (): string|undefined => { ... } ) );
3
4  const result = await retryUntilAsyncDefined( (): Promise<string|null> => { ... } );
5
6  const decorated = retryUntilDefinedDecorator( (p1: string): string|undefined => { ... } );
7  const result = await decorated('hello world');
8
9  const decorated = retryAsyncUntilDefinedDecorator( (p1: string): Promise<string|undefined> => { ... } );
10  const result = await decorated('hello world');

• to retry until a function returns something truthy:

1  // in all cases results is a string and cannot be null or undefined
2  const result = await retryUntilTruthy( (): boolean|undefined => { ... } ) );
3
4  const result = await retryAsyncUntilTruthy( (): Promise<number|null> => { ... } );
5
6  const decorated = retryUntilTruthyDecorator( (p1: string): boolean|undefined => { ... } );
7  const result = await decorated('hello world');
8
9  const decorated = retryAsyncUntilTruthyDecorator( (p1: string): Promise<boolean|null> => { ... } );
10  const result = await decorated('hello world');

• to retry until fetch is successfully:

1  const result = await retryAsyncUntilResponse( () => fetch(...) );
2
3  const decorated = retryAsyncUntilResponseDecorator( (param) => fetch(...) );
4  const result = await decorated('q=1');

---

API

Retry family

• retry(fn, retryOptions?): call repeatedly fn until fn does not throw an exception. Stop after retryOptions.maxTry count. Between each call wait retryOptions.delay milliseconds. if stop to call fn after retryOptions.maxTry, throws fn exception, otherwise returns fn return value.
• retryAsync(fn, retryOptions?): same as retry, except fn is an asynchronous function.
• retryOptions:
  • maxTry: [optional] maximum calls to fn.
  • delay: [optional] delay between each call (in milliseconds). Could be either a number or a function (when delay time dependent from number of retrys, of previous result...), see below for explanation about delay
  • until: [optional] (lastResult) => boolean: return false if last fn results is not the expected one: continue to call fn until until returns true. A TooManyTries is thrown after maxTry calls to fn;
  • onError: [optional](err: Error, currentTry: number) => void: called on each error except the last one. Includes the current try for logging. To catch/log the last error use onMaxRetryFunc
• onMaxRetryFunc: [optional](err: Error) => void: called on the final error at the maxTry limit only
• onSuccess: [optional](currentTry: number) => void: called on success. Includes the current try for logging When an option value is not provided, the default one is applied. The default options are:

1  delay: 250,
2  maxTry: 4 * 60,

• setDefaultRetryOptions<T>(retryOptions: RetryOptions<T>): change the default retryOptions.
• getDefaultRetryOptions<T>(): returns the current default retry options.
• retryAsyncDecorator<T>(fn: T, retryOptions?: RetryOptions<T>) and retryDecorator<T>(fn: T, retryOptions?: RetryOptions<T>): decorators that return a function with same signature than the given function. On decorated call, fn is called repeteadly it does not throw an exception or until retryOptions.maxTry.
• TooManyTries: an error thrown by retry functions when until returns false after maxTry calls. It comes with a type guard and includes the last failed result:

1if (isTooManyTries(error)) {
2  // retry failed
3  console.error(`last error is ${error.getLastResult()}`)
4}

When delay can vary

When delay option is a function, it is called before each retry: this allow to have a delay that can change between retires (ex: delay can increase exponentially). The function receives the following parameters:

1(parameter: {
2  currentTry: number,
3  maxTry: number,
4  lastDelay?: number
5  lastResult?: RETURN_TYPE
6}) => number;

where:

• currentTry: the number of call to fn (first is 1, not 0).
• maxTry: maximum calls to fn.
• lastDelay: the previous delay, undefined when no delay has been computed yet.
• lastResult: the last result, undefined is last call to fn failed

Until family

retry comes with handy utilities function for common use case:

UntilDefined : To retry until we get a value which is neither null nor undefined.

For calling sync function:

1retryUntilDefined<RETURN_TYPE>(
2  fn: () => RETURN_TYPE | undefined | null,
3  retryOptions?: RetryUtilsOptions,
4): Promise<RETURN_TYPE>

1retryUntilDefinedDecorator<PARAMETERS_TYPE, RETURN_TYPE>(
2  fn: (...args: PARAMETERS_TYPE) => RETURN_TYPE | undefined | null,
3  retryOptions?: RetryUtilsOptions,
4): (...args: PARAMETERS_TYPE) => Promise<RETURN_TYPE>

For calling async function:

1retryAsyncUntilDefined<RETURN_TYPE>(
2  fn: () => Promise<RETURN_TYPE | undefined | null>,
3  options?: RetryUtilsOptions,
4): Promise<RETURN_TYPE>

1retryAsyncUntilDefinedDecorator<PARAMETERS_TYPE, RETURN_TYPE>(
2  fn: (...args: PARAMETERS_TYPE) => Promise<RETURN_TYPE | undefined | null>,
3  retryOptions?: RetryUtilsOptions,
4): (...args: PARAMETERS_TYPE) => Promise<RETURN_TYPE>

UntilTruthy : To retry until we get a value which javascript consider as truthy.

For calling sync function:

1retryUntilTruthy<PARAMETERS_TYPE, RETURN_TYPE>(
2  fn: (...args: PARAMETERS_TYPE) => RETURN_TYPE,
3  retryOptions?: RetryUtilsOptions,
4): Promise<RETURN_TYPE>

1retryUntilTruthyDecorator<PARAMETERS_TYPE,  RETURN_TYPE>(
2  fn: (...args: PARAMETERS_TYPE) => RETURN_TYPE,
3  retryOptions?: RetryUtilsOptions,
4): (...args: PARAMETERS_TYPE) => Promise<RETURN_TYPE>

For calling async function:

1retryAsyncUntilTruthy<PARAMETERS_TYPE, RETURN_TYPE>(
2  fn: (...args: PARAMETERS_TYPE) => Promise<RETURN_TYPE>,
3  retryOptions?: RetryUtilsOptions,
4): Promise<RETURN_TYPE>

1retryAsyncUntilTruthyDecorator<PARAMETERS_TYPE, RETURN_TYPE>(
2  fn: (...args: PARAMETERS_TYPE) => Promise<RETURN_TYPE>,
3  retryOptions?: RetryUtilsOptions,
4): (...args: PARAMETERS_TYPE) => Promise<RETURN_TYPE>

UntilResponse : To retry until fetch is sucessfull.

1retryAsyncUntilResponse<PARAMETERS_TYPE, RETURN_TYPE extends { ok: boolean }>(
2  fn: () => Promise<RETURN_TYPE>,
3  retryOptions?: RetryUtilsOptions,
4): Promise<RETURN_TYPE>

1retryAsyncUntilResponseDecorator<PARAMETERS_TYPE, RETURN_TYPE extends { ok: boolean }>(
2  fn: (...args: PARAMETERS_TYPE) => Promise<RETURN_TYPE>,
3  retryOptions?: RetryUtilsOptions,
4): (...args: PARAMETERS_TYPE) => Promise<RETURN_TYPE>

RetryUtilsOptions type is the same than RetryUtilsOptions but without until option.

Delay family

createExponetialDelay Returns a delay function that provide exponetial delais

1const delay = createExponetialDelay(20);
2const result = await retryAsync(
3  async () => {
4    /* do something */
5  },
6  { delay, maxTry: 5 }
7);

delay between each try will return 20, 400, 8000, 160000, 3200000

createMutiplicableDelay Returns a delay function that provide multiplicated delais:

1createMutiplicableDelay<RETURN_TYPE>(initialDelay: number, multiplicator: number)

First delay retunrs initialDelay, second initialDelaymultiplicator, third multiplicator initialDelay(multiplicator*2) and so on

1const delay = createMutiplicableDelay(20);
2const result = await retryAsync(
3  async () => {
4    /* do something */
5  },
6  { delay, maxTry: 5 }
7);

delay will be 20, 60, 120, 180, 240

createRandomDelay Returns a delay function that provide radom delais between given min and max (included):

1createRandomDelay<RETURN_TYPE>(min: number, max: number)

Each time the created delay is called, a value between min and max (both included) is generated

1const delay = createRandomDelay(500, 10000);
2const result = await retryAsync(
3  async () => {
4    /* do something */
5  },
6  { delay, maxTry: 5 }
7);

delay betewwen each try will be a random value between 500 and 1000 ms.

Wait family

• wait(duration?): Do nothing during "duration" milliseconds
• waitUntil(fn, duration?, error?): waitUntil call asynchronously fn once. If fn complete within the duration (express in milliseconds), waitUntil returns the fn result. Otherwise, it throws the given error (if any) or a TimeoutError exception.
• waitUntilAsync(fn, duration?, error?): same as waitUntil, except fn is an asynchronous function.
• TimeoutError: an error thrown by waitUntil and waitUntilAsync. It comes with a isTimeoutError type guard:

1if (isTimeoutError(error)) {
2  // fn does not complete within 10 seconds
3}

In case of timeout fn is still executing. It is advised to add a mean to abort it.

• When duration is not provided, the default one is applied. The default is 60000ms.
• setDefaultDuration(duration: number): change the default duration.
• getDefaultDuration(): returns the current default duration.
• waitUntilAsyncDecorator(fn: T, duration?: number, error?: Error) and waitUntilDecorator(fn: T, duration?: number, error?: Error): decorators that return a function with same signature than the given function. On decorated call, fn is called bounded to the duration.

Custom reaction when max retry is achieved

Sometimes, you need to perform some actions when max retry has achieved and the error is still there. For this onMaxRetryFunc?: (err: Error) => void; optional function was added to RetryOptions. For example, you would like to store results of the error into the file in order to process it later. Here's how you can do it :

1export const runWithRetry = <T>(
2  message: string,
3  serviceUnderTest: ServiceUnderTest,
4  fn: () => T | Promise<T>,
5  delay = 1000,
6  maxTry = 10
7) => {
8  const saveErrorReport = (err) => {
9    const errorDetails = {
10      serviceName: serviceUnderTest.connectorName,
11      error: err.message as string,
12      description: `Failed to ${message} because of ${err.message as string}`,
13      errorName: err.name as string,
14      stack: err.stack as string,
15    };
16    const path = resolve(
17      __dirname,
18      `../../../failed-service-report/${serviceUnderTest.connectorName}.json`
19    );
20    writeFile(path, Buffer.from(JSON.stringify(errorDetails)));
21  };
22  return retryAsync(
23    async () => {
24      logger.info(`${serviceUnderTest.description}: ${message}`);
25      return fn();
26    },
27    {
28      delay,
29      maxTry,
30      onMaxRetryFunc: saveErrorReport,
31    }
32  );
33};

Compatibility

This lib works with Deno (to import it,use the url https://raw.githubusercontent.com/franckLdx/ts-retry/<version>/src/index.ts). However, it's more convenient to use the specific port of this lib to Deno: see https://deno.land/x/retry