🚀 fetch-retry-logic

A lightweight, zero-dependency wrapper for the native Fetch API that adds exponential backoff, jitter, and customizable retry logic.

Why use this?

Network requests fail. Whether it's a spotty mobile connection or a temporary server overload (503), failing immediately creates a poor user experience. fetch-retry-logic helps your app stay resilient by retrying failed requests automatically.

• Zero Dependencies: Uses the native fetch you already know.
• Exponential Backoff: Prevents "retry storms" by waiting longer after each failure.
• Jitter Support: Randomizes delays to prevent synchronized server hits.
• TypeScript First: Full type safety for your options.

📦 Installation

npm install fetch-retry-logic

🛠️ Usage

Use it exactly like a normal fetch, but with an optional retry configuration object.

import { fetchRetry } from 'fetch-retry-logic';

const response = await fetchRetry('https://api.example.com/data', {
  method: 'GET',
  retry: {
    retries: 5,
    backoff: 1000,
    jitter: true,
    retryOn: [500, 503, 429]
  }
});

const data = await response.json();

⚙️ Configuration Options

| Option | Type | Default | Description | |-------|-----|-----------|------| | retries | number | 3 |Total number of retry attempts | | backoff | number | 1000 | Base delay in milliseconds. Doubles each attempt.| | jitter | boolean | true | Adds a small random offset to the backoff delay. | | retryOn | number[] | [408, 429, 500, 502, 503, 504] |HTTP status codes that trigger a retry.| | maxBackoff | number | 30000 | Maximum delay in milliseconds to which backoff is clamped. |

🧪 Testing

This library is fully tested with Vitest. To run the tests:

npm test

Notes:

• The retry object is only used by fetchRetry and is not forwarded to the underlying fetch call.
• When a 429 response includes a Retry-After header, the library will honor both numeric (seconds) and HTTP-date formats.
• If you pass an AbortSignal via the signal option, the wait between retries is abortable and will stop immediately when signalled.

Contribution

We welcome contributions! If you'd like to contribute to fetch-retry-logic, please follow our Contribution Guidelines.

Author

Subramanya KS

License

This project is licensed under the MIT License - see the LICENSE file for details.