Bluebird Promise Retry Utility

Common errors

• Error: operation timed out

  cause The retry operation exhausted its maximum number of attempts (`max_tries`) or exceeded its calculated `timeout` duration before the wrapped function succeeded.
  fix Increase the `max_tries` option, or adjust `interval` and `backoff` to allow more attempts within the `timeout` period. Alternatively, debug the underlying function to understand why it's consistently failing and fix it.

• Promise is not defined

  cause The `bluebird` library, which `bluebird-retry` depends on, has not been properly imported or is not available in the global scope/module context.
  fix Ensure `bluebird` is installed (`npm install bluebird`) and imported at the top of your file: `const Promise = require('bluebird');`.

• TypeError: retry.StopError is not a constructor

  cause You are attempting to use `retry.StopError` but `retry` was not correctly imported or is not the object containing the `StopError` class.
  fix Ensure you are importing `bluebird-retry` using `const retry = require('bluebird-retry');` and then referencing `retry.StopError` correctly. Do not try to destructure `StopError` directly from the package import.

Warnings

• breaking The `bluebird` library was changed from a direct dependency to a peer dependency. Applications must now explicitly install `bluebird` alongside `bluebird-retry`.
  Fix: Ensure `bluebird` is installed in your project: `npm install bluebird` or `yarn add bluebird`.
• gotcha The `timeout` option does not create a real-time timeout, but rather computes a maximum number of attempts based on the `interval` and `backoff` options. If both `timeout` and `max_tries` are specified, the limit that comes first will apply.
  Fix: Understand that `timeout` is an estimation for `max_tries`. For strict time limits, consider wrapping `bluebird-retry` with a separate Bluebird `Promise.delay` and `Promise.race` if fine-grained control is critical.
• gotcha By default, `bluebird-retry` absorbs all intermediate rejection messages, and will only propagate the final error if the operation ultimately times out or reaches `max_tries`. This can make debugging initial failures difficult.
  Fix: To throw the last encountered error instance instead of a timeout error, set the `throw_original` option to `true`. Alternatively, use the `predicate` option to filter which errors cause a retry.
• deprecated The package uses `.try` and `.catch` aliases (`.attempt` and `.caught` respectively) for older browser support. While functionally equivalent in Bluebird, modern Bluebird versions and native Promises prefer `.try` (or direct `try/catch` with `async/await`) and `.catch`.
  Fix: No direct fix needed as it's an internal implementation detail, but be aware that if you're writing new code, using standard Bluebird or native promise methods is generally preferred.
• gotcha As a package in maintenance mode (last update several years ago), it may not fully leverage modern JavaScript features like `async/await` directly without explicit Bluebird promisification, nor is it optimized for ESM environments without transpilation or bundler configuration.
  Fix: For new applications, consider using native `async/await` with a custom retry loop or a more modern retry library that explicitly supports `async/await` and ESM. If using `bluebird-retry`, stick to its documented CommonJS usage.

Install

• npm install bluebird-retry npm
• yarn add bluebird-retry yarn
• pnpm add bluebird-retry pnpm

Imports

• retry
  wrong:

  import retry from 'bluebird-retry';

  correct:

  const retry = require('bluebird-retry');

  Primarily designed for CommonJS; direct ESM import might not work without bundler configuration. The `retry` function is the main export.
• retry.StopError
  wrong:

  import { StopError } from 'bluebird-retry';

  correct:

  const retry = require('bluebird-retry');
  // ... then later ...
  throw new retry.StopError('message');

  StopError is a property of the main `retry` export, not a named export. It's used to gracefully exit the retry loop.
• Promise (from bluebird)
  wrong:

  import { Promise } from 'bluebird';

  correct:

  const Promise = require('bluebird');

  bluebird-retry depends on Bluebird. If your operation uses `Promise.resolve` or `Promise.reject`, you must ensure Bluebird is imported and available, especially in older CJS contexts. Bluebird also has an ESM export, but CJS `require` is typical for older patterns.

Quickstart

This example demonstrates how to use `bluebird-retry` to repeatedly execute an asynchronous function until it returns a successful promise, configured with a maximum number of attempts and a fixed interval.

const Promise = require('bluebird');
const retry = require('bluebird-retry');

let count = 0;
function myfunc() {
    console.log('myfunc called ' + (++count) + ' times');
    if (count < 3) {
        // Simulate an asynchronous failure with a Bluebird rejection
        return Promise.reject(new Error('fail the first two times'));
    } else {
        // Simulate an asynchronous success
        return Promise.resolve('succeed the third time');
    }
}

retry(myfunc, { max_tries: 5, interval: 500 })
.then(function(result) {
    console.log(result);
})
.catch(function(err) {
    console.error('Operation failed completely:', err.message);
});