exponential-backoff

When upgrading from version 2 to version 3, note the following breaking change regarding jitter configuration:

• Jitter Configuration: The jitter option now accepts a union string type to simplify configuration. As a result, the JitterTypes enum is no longer available and should be replaced with the corresponding string literals.

Install the package using npm to add exponential backoff retry logic to your project.

npm i exponential-backoff

When upgrading from version 1 to version 2, note the following breaking changes in the backOff<T> function and its options:

• Function Signature: The first argument of backOff<T> is now exclusively the function you want to back off. The retry function has been moved and is now available as a property within the IBackOffOptions object.
• Default Delay: The default value for the delayFirstAttempt option has changed from its previous behavior to false.

The backOff<T> function wraps a promise-returning function and retries it with an exponential delay between attempts. It returns a Promise<T> that resolves with the result of the successful function call or rejects if all retry attempts fail or the retry logic returns false.

import { backOff } from "exponential-backoff";

function getWeather() {
  return fetch("weather-endpoint");
}

async function main() {
  try {
    const response = await backOff(() => getWeather());
    // process response
  } catch (e) {
    // handle error
  }
}

main();

The retry option allows you to implement custom logic after a failure. This is useful for logging errors or deciding whether a specific error type warrants a retry.

• If the function returns true (or a Promise resolving to true), the library will attempt the next retry.
• If the function returns false (or a Promise resolving to false), the execution stops immediately, even if numOfAttempts has not been reached.

const options: BackoffOptions = {
  retry: (error, attemptNumber) => {
    console.error(`Attempt ${attemptNumber} failed:`, error);
    // Only retry if it's a network error
    return error.isNetworkError === true;
  }
};

The backOff function is the primary entrypoint for retrying promise-returning functions. It accepts a request function and an optional options object to customize retry behavior. The function will repeatedly attempt to execute the request until it succeeds, the maximum number of attempts is reached, or the provided retry logic determines that no further retries should occur.

Returns a Promise that resolves to the result of the request function if successful, or throws the error encountered during the final attempt if all retries fail.

import { backOff } from 'exponential-backoff';

const result = await backOff(() => myAsyncFunction(), {
  // options here
});

When calling backOff, you can provide a BackoffOptions object to control how retries are handled. The available options are defined by the BackoffOptions and IBackOffOptions interfaces.

Key behaviors controlled by options include:

• Number of attempts: Limiting how many times the function is executed.
• Retry logic: A custom retry function that receives the error and the current attempt number to decide if a retry should proceed.
• Delay strategy: Determining how long to wait between attempts (managed via the DelayFactory).

import { backOff, BackoffOptions } from 'exponential-backoff';

const options: BackoffOptions = {
  // implementation of BackoffOptions properties
};

await backOff(() => someTask(), options);

The jitter option determines how randomness is applied to the delay to prevent thundering herd problems. Supported values are:

• "none": No jitter is applied.
• "full": Full jitter is applied (a random value between 0 and the current delay).

type JitterType = "none" | "full";