retry vs promise-retry vs async-retry vs retry-request vs retry-axios vs backoff
JavaScript Retry Libraries Comparison
1 Year
retrypromise-retryasync-retryretry-requestretry-axiosbackoffSimilar Packages:
What's JavaScript Retry Libraries?

Retry libraries in JavaScript provide mechanisms to automatically retry failed asynchronous operations, such as API calls or database queries, to enhance reliability and resilience in applications. These libraries help manage transient errors by implementing various retry strategies, allowing developers to configure parameters like the number of retries, delay between attempts, and conditions for retrying. This is particularly useful in scenarios where network issues or temporary service outages may occur, ensuring that applications can gracefully handle failures without crashing or requiring manual intervention.

Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
Package
Downloads
Stars
Size
Issues
Publish
License
retry42,035,4431,247-194 years agoMIT
promise-retry15,956,186317-115 years agoMIT
async-retry9,570,5281,873-304 years agoMIT
retry-request8,308,0726821.2 kB32 months agoMIT
retry-axios907,36249436.4 kB34a year agoApache-2.0
backoff716,269337-119 years agoMIT
Feature Comparison: retry vs promise-retry vs async-retry vs retry-request vs retry-axios vs backoff

Retry Strategy

  • retry:

    retry supports both fixed and exponential backoff strategies, giving you the flexibility to define how retries are handled based on your application's needs.

  • promise-retry:

    promise-retry offers a simple retry strategy that can be customized with a delay function, allowing you to control the timing of retries based on the error type or other conditions.

  • async-retry:

    async-retry allows for custom retry strategies, including exponential backoff and fixed delays. You can specify how long to wait between retries and how many attempts to make before failing.

  • retry-request:

    retry-request provides a straightforward retry mechanism for HTTP requests, allowing you to specify the number of retries and the delay between attempts, suitable for simple use cases.

  • retry-axios:

    retry-axios allows you to configure retry strategies directly in your Axios requests, including setting retry limits and delays, making it easy to manage HTTP request failures.

  • backoff:

    backoff provides built-in support for exponential backoff strategies, allowing you to define the initial delay and the factor by which the delay increases with each retry, making it ideal for handling rate limits.

Integration

  • retry:

    retry can be used with both callbacks and promises, making it a versatile choice for applications that may use either approach for asynchronous operations.

  • promise-retry:

    promise-retry is specifically tailored for promises, ensuring seamless integration with promise-based APIs and workflows, making it easy to implement in modern JavaScript applications.

  • async-retry:

    async-retry is designed to work independently and can be integrated into any promise-based workflow, providing flexibility in various environments.

  • retry-request:

    retry-request is built to work with the request library, making it ideal for legacy applications that rely on this library for HTTP requests.

  • retry-axios:

    retry-axios is specifically designed for use with Axios, providing a seamless integration that allows you to add retry logic directly to your HTTP requests without additional setup.

  • backoff:

    backoff is a standalone library that can be used with any asynchronous operation, making it versatile for different use cases beyond just HTTP requests.

Configuration Options

  • retry:

    retry offers flexible configuration options for retry attempts, delays, and error handling, allowing you to tailor the retry logic to fit your needs.

  • promise-retry:

    promise-retry provides straightforward configuration options, allowing you to specify the number of retries and a delay function, making it easy to set up and use.

  • async-retry:

    async-retry offers a wide range of configuration options, including the ability to customize the number of retries, delay between attempts, and conditions for retrying, providing great flexibility.

  • retry-request:

    retry-request provides basic configuration options for retry attempts and delays, making it easy to use without overwhelming complexity.

  • retry-axios:

    retry-axios allows you to configure retry options directly in your Axios instance, including retry limits and conditions, making it convenient for developers familiar with Axios.

  • backoff:

    backoff allows for extensive configuration of backoff strategies, including setting maximum retry limits and customizing the backoff function, making it highly adaptable to specific requirements.

Error Handling

  • retry:

    retry provides basic error handling capabilities, allowing you to specify which errors should be retried, but may require additional logic for more complex scenarios.

  • promise-retry:

    promise-retry allows for custom error handling by enabling you to define conditions under which retries should occur, ensuring that only relevant errors trigger a retry.

  • async-retry:

    async-retry allows you to specify error types that should trigger a retry, giving you control over which errors are retried and which are not, enhancing error handling capabilities.

  • retry-request:

    retry-request allows you to define which HTTP status codes should trigger a retry, providing a straightforward way to handle common HTTP errors.

  • retry-axios:

    retry-axios integrates error handling directly into Axios, allowing you to specify which HTTP status codes should trigger a retry, making it easy to manage API errors.

  • backoff:

    backoff provides mechanisms to handle specific errors and can be configured to retry only on certain error types, making it useful for managing different failure scenarios.

Documentation and Community Support

  • retry:

    retry has decent documentation, but may lack some advanced examples; however, it is widely used, providing a level of community support through forums and GitHub.

  • promise-retry:

    promise-retry has straightforward documentation that covers the basics, making it easy for developers to get started quickly with examples and use cases.

  • async-retry:

    async-retry has comprehensive documentation and a growing community, making it easy to find examples and support for implementation.

  • retry-request:

    retry-request has basic documentation that covers its usage, but as the request library is deprecated, community support may be limited.

  • retry-axios:

    retry-axios has good documentation that integrates with Axios documentation, making it easy for developers familiar with Axios to implement retry logic effectively.

  • backoff:

    backoff is well-documented with clear examples, and it has a supportive community that can assist with common use cases and issues.

How to Choose: retry vs promise-retry vs async-retry vs retry-request vs retry-axios vs backoff
  • retry:

    Use retry if you need a general-purpose retry library that works with both callbacks and promises. It offers a simple API and allows for flexible configuration of retry attempts and delays, suitable for various asynchronous operations.

  • promise-retry:

    Opt for promise-retry if you want a straightforward solution specifically designed for promises. It provides built-in support for retrying failed promises with customizable retry conditions and delays, making it easy to integrate into promise-based workflows.

  • async-retry:

    Choose async-retry if you need a simple and flexible retry mechanism that supports both promises and async/await syntax. It allows for custom backoff strategies and is lightweight, making it suitable for most use cases.

  • retry-request:

    Select retry-request if you are working with the request library and need a retry mechanism for HTTP requests. It provides a straightforward way to add retry capabilities to your request calls, making it suitable for legacy applications that still use the request library.

  • retry-axios:

    Choose retry-axios if you are using Axios for HTTP requests and want to add retry functionality seamlessly. It integrates directly with Axios, allowing you to specify retry logic directly in your Axios configuration, making it ideal for RESTful API interactions.

  • backoff:

    Select backoff if you require advanced exponential backoff strategies with customizable delay and maximum retry limits. It is particularly useful for handling rate-limited APIs or services that enforce throttling.

README for retry

Build Status codecov

retry

Abstraction for exponential and custom retry strategies for failed operations.

Installation

npm install retry

Current Status

This module has been tested and is ready to be used.

Tutorial

The example below will retry a potentially failing dns.resolve operation 10 times using an exponential backoff strategy. With the default settings, this means the last attempt is made after 17 minutes and 3 seconds.

var dns = require('dns');
var retry = require('retry');

function faultTolerantResolve(address, cb) {
  var operation = retry.operation();

  operation.attempt(function(currentAttempt) {
    dns.resolve(address, function(err, addresses) {
      if (operation.retry(err)) {
        return;
      }

      cb(err ? operation.mainError() : null, addresses);
    });
  });
}

faultTolerantResolve('nodejs.org', function(err, addresses) {
  console.log(err, addresses);
});

Of course you can also configure the factors that go into the exponential backoff. See the API documentation below for all available settings. currentAttempt is an int representing the number of attempts so far.

var operation = retry.operation({
  retries: 5,
  factor: 3,
  minTimeout: 1 * 1000,
  maxTimeout: 60 * 1000,
  randomize: true,
});

API

retry.operation([options])

Creates a new RetryOperation object. options is the same as retry.timeouts()'s options, with three additions:

  • forever: Whether to retry forever, defaults to false.
  • unref: Whether to unref the setTimeout's, defaults to false.
  • maxRetryTime: The maximum time (in milliseconds) that the retried operation is allowed to run. Default is Infinity.

retry.timeouts([options])

Returns an array of timeouts. All time options and return values are in milliseconds. If options is an array, a copy of that array is returned.

options is a JS object that can contain any of the following keys:

  • retries: The maximum amount of times to retry the operation. Default is 10. Seting this to 1 means do it once, then retry it once.
  • factor: The exponential factor to use. Default is 2.
  • minTimeout: The number of milliseconds before starting the first retry. Default is 1000.
  • maxTimeout: The maximum number of milliseconds between two retries. Default is Infinity.
  • randomize: Randomizes the timeouts by multiplying with a factor between 1 to 2. Default is false.

The formula used to calculate the individual timeouts is:

Math.min(random * minTimeout * Math.pow(factor, attempt), maxTimeout)

Have a look at this article for a better explanation of approach.

If you want to tune your factor / times settings to attempt the last retry after a certain amount of time, you can use wolfram alpha. For example in order to tune for 10 attempts in 5 minutes, you can use this equation:

screenshot

Explaining the various values from left to right:

  • k = 0 ... 9: The retries value (10)
  • 1000: The minTimeout value in ms (1000)
  • x^k: No need to change this, x will be your resulting factor
  • 5 * 60 * 1000: The desired total amount of time for retrying in ms (5 minutes)

To make this a little easier for you, use wolfram alpha to do the calculations:

http://www.wolframalpha.com/input/?i=Sum%5B1000*x^k%2C+{k%2C+0%2C+9}%5D+%3D+5+*+60+*+1000

retry.createTimeout(attempt, opts)

Returns a new timeout (integer in milliseconds) based on the given parameters.

attempt is an integer representing for which retry the timeout should be calculated. If your retry operation was executed 4 times you had one attempt and 3 retries. If you then want to calculate a new timeout, you should set attempt to 4 (attempts are zero-indexed).

opts can include factor, minTimeout, randomize (boolean) and maxTimeout. They are documented above.

retry.createTimeout() is used internally by retry.timeouts() and is public for you to be able to create your own timeouts for reinserting an item, see issue #13.

retry.wrap(obj, [options], [methodNames])

Wrap all functions of the obj with retry. Optionally you can pass operation options and an array of method names which need to be wrapped.

retry.wrap(obj)

retry.wrap(obj, ['method1', 'method2'])

retry.wrap(obj, {retries: 3})

retry.wrap(obj, {retries: 3}, ['method1', 'method2'])

The options object can take any options that the usual call to retry.operation can take.

new RetryOperation(timeouts, [options])

Creates a new RetryOperation where timeouts is an array where each value is a timeout given in milliseconds.

Available options:

  • forever: Whether to retry forever, defaults to false.
  • unref: Wether to unref the setTimeout's, defaults to false.

If forever is true, the following changes happen:

  • RetryOperation.errors() will only output an array of one item: the last error.
  • RetryOperation will repeatedly use the timeouts array. Once all of its timeouts have been used up, it restarts with the first timeout, then uses the second and so on.

retryOperation.errors()

Returns an array of all errors that have been passed to retryOperation.retry() so far. The returning array has the errors ordered chronologically based on when they were passed to retryOperation.retry(), which means the first passed error is at index zero and the last is at the last index.

retryOperation.mainError()

A reference to the error object that occured most frequently. Errors are compared using the error.message property.

If multiple error messages occured the same amount of time, the last error object with that message is returned.

If no errors occured so far, the value is null.

retryOperation.attempt(fn, timeoutOps)

Defines the function fn that is to be retried and executes it for the first time right away. The fn function can receive an optional currentAttempt callback that represents the number of attempts to execute fn so far.

Optionally defines timeoutOps which is an object having a property timeout in miliseconds and a property cb callback function. Whenever your retry operation takes longer than timeout to execute, the timeout callback function cb is called.

retryOperation.try(fn)

This is an alias for retryOperation.attempt(fn). This is deprecated. Please use retryOperation.attempt(fn) instead.

retryOperation.start(fn)

This is an alias for retryOperation.attempt(fn). This is deprecated. Please use retryOperation.attempt(fn) instead.

retryOperation.retry(error)

Returns false when no error value is given, or the maximum amount of retries has been reached.

Otherwise it returns true, and retries the operation after the timeout for the current attempt number.

retryOperation.stop()

Allows you to stop the operation being retried. Useful for aborting the operation on a fatal error etc.

retryOperation.reset()

Resets the internal state of the operation object, so that you can call attempt() again as if this was a new operation object.

retryOperation.attempts()

Returns an int representing the number of attempts it took to call fn before it was successful.

License

retry is licensed under the MIT license.

Changelog

0.10.0 Adding stop functionality, thanks to @maxnachlinger.

0.9.0 Adding unref functionality, thanks to @satazor.

0.8.0 Implementing retry.wrap.

0.7.0 Some bug fixes and made retry.createTimeout() public. Fixed issues #10, #12, and #13.

0.6.0 Introduced optional timeOps parameter for the attempt() function which is an object having a property timeout in milliseconds and a property cb callback function. Whenever your retry operation takes longer than timeout to execute, the timeout callback function cb is called.

0.5.0 Some minor refactoring.

0.4.0 Changed retryOperation.try() to retryOperation.attempt(). Deprecated the aliases start() and try() for it.

0.3.0 Added retryOperation.start() which is an alias for retryOperation.try().

0.2.0 Added attempts() function and parameter to retryOperation.try() representing the number of attempts it took to call fn().