Registry / http-networking / exponential-backoff

exponential-backoff

library3.1.3jsnpmunverified

The `exponential-backoff` package provides a robust utility for retrying asynchronous (Promise-returning) functions with an exponential delay between attempts. Currently stable at version 3.1.3, the library maintains an active development status with regular chore and security updates, although it does not adhere to a strict release cadence. Its key differentiators include extensive configurability through the `BackOffOptions` object, allowing control over aspects like initial delay, maximum delay, number of attempts, jitter application (`full` or `none`), and a custom `retry` function for conditional reattempts. The package ships with TypeScript types, enhancing developer experience in TypeScript projects. It is designed to be a flexible solution for handling transient errors in network requests, database operations, or other unreliable processes.

http-networking

npm install exponential-backoff

github ↗package ↗

INSTALL

IMPORT

SIG · EXPONENTIAL-BACKOF

exponential-backoff

http-networkingjavascriptv3.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

backOff

✓ import { backOff } from 'exponential-backoff';

✗ const { backOff } = require('exponential-backoff');

The library primarily uses ESM exports. While CommonJS `require` might work via transpilation or bundlers, native ESM `import` is the recommended and most reliable approach since v3.

BackOffOptions

✓ import type { BackOffOptions } from 'exponential-backoff';

✗ import { BackOffOptions } from 'exponential-backoff';

Used for TypeScript type declarations. Import with `type` keyword for tree-shaking and clarity, although a regular named import works at runtime if it were a value.

JitterType

✓ import type { JitterType } from 'exponential-backoff';

Type import for the 'jitter' option, defining possible string literal values 'full' or 'none'.

Demonstrates how to use `backOff` to retry an unreliable asynchronous function with custom exponential backoff options, including delay, attempts, jitter, and a custom retry condition.

import { backOff } from 'exponential-backoff'; interface WeatherResponse { temperature: number; unit: string; } // Simulate an unreliable API call let attemptCount = 0; function getUnreliableWeather(): Promise<WeatherResponse> { attemptCount++; console.log(`Attempting to fetch weather... (Attempt ${attemptCount})`); return new Promise((resolve, reject) => { if (Math.random() > 0.7 || attemptCount >= 3) { // Succeeds on ~30% chance or after 3 attempts resolve({ temperature: 25, unit: 'C' }); } else { reject(new Error('Failed to fetch weather data.')); } }); } async function main() { try { console.log('Starting weather fetch with exponential backoff...'); const response = await backOff( () => getUnreliableWeather(), { numOfAttempts: 5, // Try up to 5 times startingDelay: 200, // Start with 200ms delay timeMultiple: 2, // Double delay each time maxDelay: 5000, // Max 5 seconds delay jitter: 'full', retry: (e, attemptNumber) => { console.warn(`Retry attempt ${attemptNumber}: ${e.message}`); return true; // Always retry for now } } ); console.log('Successfully fetched weather:', response); } catch (e: any) { console.error('Failed to fetch weather after multiple retries:', e.message); } finally { console.log(`Total attempts: ${attemptCount}`); } } main();

Debug

Known issues

breakingMajor versions (e.g., v2 to v3) often introduce breaking changes to the API, options, or internal behavior. Always consult the official migration guide when upgrading between major versions.

fix

Refer to the package's GitHub repository for the dedicated migration guide (`/doc/migration-guide.md`) to understand specific changes and update your code accordingly.

affects: >=2.0

gotchaThe default `retry` function always returns `true`. If `numOfAttempts` is set to `Infinity` (which is the default `maxDelay` but `numOfAttempts` defaults to 10), and your `request` function consistently fails, it can lead to an infinite retry loop.

fix

Explicitly define a `numOfAttempts` or implement a custom `retry` function that returns `false` under specific error conditions or after a certain number of attempts to prevent uncontrolled retries.

affects: >=1.0

gotchaThe `numOfAttempts` option has a minimum value of `1`. Providing a value less than `1` will result in the option being clamped to `1`, which might lead to unexpected behavior if you intend zero retries.

fix

Ensure `numOfAttempts` is explicitly set to `1` or higher. For no retries, simply call the promise-returning function directly without `backOff`.

affects: >=1.0

Errors

Common errors & fixes

TypeError: (0 , exponential_backoff__WEBPACK_IMPORTED_MODULE_0__.backOff) is not a function

This error typically occurs in environments (like Webpack or Babel) when trying to `require` an ESM-first package or due to incorrect default/named import resolution. It indicates the bundler couldn't find the `backOff` export.

fix

Ensure you are using standard ESM `import { backOff } from 'exponential-backoff';`. If using CommonJS, check your transpilation settings to ensure ESM imports are correctly handled or consider updating your build tools. In some cases, a package might not correctly expose its exports for CommonJS.

My function keeps retrying indefinitely even after many failures.

You likely have `numOfAttempts` set to a very high number (or effectively `Infinity` due to an oversight) and are using the default `retry` function, which always returns `true`.

fix

Configure `numOfAttempts` to a finite, reasonable number. Alternatively, provide a custom `retry` function that checks the error (`e`) or `attemptNumber` and returns `false` to stop retrying when a certain condition is met (e.g., non-transient error, max attempts reached).

Argument of type '(...)' is not assignable to parameter of type 'BackOffOptions'. Object literal may only specify known properties, and '' does not exist in type 'BackOffOptions'.

This TypeScript error indicates you're passing an option to `backOff` that is not part of the `BackOffOptions` interface, likely due to a typo or using a deprecated option name.

fix

Review the `BackOffOptions` interface and the available options in the documentation. Correct any misspelled option names or remove unsupported properties from the options object.

Upgrade

Version history

3.1.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/coveooss/exponential-backoff ↗

packagehttps://www.npmjs.com/package/exponential-backoff ↗