https://github.com/samplexbro/axios-retryer

An advanced Axios request manager offering intelligent retry logic with token refresh, concurrency control, priority queuing, and a flexible plugin architecture, all built with TypeScript for robust HTTP client integrations.
https://github.com/samplexbro/axios-retryer

axios concurrency http-client priority-queue queue retry-library retryer token-refresh

Last synced: 3 months ago
JSON representation

Host: GitHub
URL: https://github.com/samplexbro/axios-retryer
Owner: sampleXbro
Created: 2024-12-18T09:32:59.000Z (over 1 year ago)
Default Branch: main
Last Pushed: 2025-06-04T12:40:34.000Z (about 1 year ago)
Last Synced: 2025-10-17T09:06:26.416Z (8 months ago)
Topics: axios, concurrency, http-client, priority-queue, queue, retry-library, retryer, token-refresh
Language: TypeScript
Homepage:
Size: 597 KB
Stars: 2
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Codeowners: CODEOWNERS
- Security: SECURITY.md
- Agents: AGENTS.md

Awesome Lists containing this project

README

          


  

  axios-retryer

  TypeScript-first Axios retry library with concurrency control, request prioritization, token refresh, response caching, circuit breaker, and more — as composable plugins.


  [![npm version](https://img.shields.io/npm/v/axios-retryer.svg)](https://www.npmjs.com/package/axios-retryer)

  [![npm downloads](https://img.shields.io/npm/dm/axios-retryer.svg)](https://www.npmjs.com/package/axios-retryer)

  [![codecov](https://codecov.io/github/sampleXbro/axios-retryer/graph/badge.svg?token=BRQB5DJVLK)](https://codecov.io/github/sampleXbro/axios-retryer)

  [![Known Vulnerabilities](https://snyk.io/test/github/sampleXbro/axios-retryer/badge.svg)](https://snyk.io/test/github/sampleXbro/axios-retryer)

  ![Build](https://github.com/sampleXbro/axios-retryer/actions/workflows/publish.yml/badge.svg)

  [![Gzipped Size](https://img.shields.io/bundlephobia/minzip/axios-retryer)](https://bundlephobia.com/package/axios-retryer)

  [![TypeScript](https://img.shields.io/badge/TypeScript-First-blue)](https://www.typescriptlang.org/)

  [![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)



---

**[📖 Full Documentation & Website](https://samplexbro.github.io/axios-retryer)** · [GitHub](https://github.com/sampleXbro/axios-retryer) · [npm](https://www.npmjs.com/package/axios-retryer) · [Changelog](./CHANGELOG.md)

---

## What is axios-retryer?

`axios-retryer` wraps Axios with a production-grade retry manager. It handles the parts that ad hoc interceptors get wrong: concurrent token refresh, orderly request queues, circuit breaking on failing upstreams, response caching, and pluggable observability.

**Key capabilities:**

| | |

|---|---|

| 🔄 **Intelligent retries** | Automatic or manual modes, exponential/linear/static backoff, custom strategies |

| 🚦 **Priority queue** | CRITICAL → LOW priorities, binary-heap scheduling, configurable concurrency |

| 🔑 **Token refresh** | Queues concurrent 401s, refreshes once, replays all with new token |

| 🛡️ **Circuit breaker** | Trips on N failures, fast-fails during recovery, sliding-window analysis |

| 💾 **Response caching** | TTR, exact/prefix/regex invalidation, pluggable storage adapters |

| 📊 **Metrics & events** | Live retry counters, timer health, rich lifecycle event hooks |

| 🌳 **Tree-shakeable plugins** | Each plugin is a separate entry point — unused code stays out of your bundle |

**Requires:** `axios >= 1.7.4`

---

## Installation

```bash

npm install axios-retryer

# yarn add axios-retryer

# pnpm add axios-retryer

```

---

## Quick Start

```typescript

import { createRetryer } from 'axios-retryer';

import { createTokenRefreshPlugin } from 'axios-retryer/plugins/TokenRefreshPlugin';

import { createCircuitBreaker } from 'axios-retryer/plugins/CircuitBreakerPlugin';

const retryer = createRetryer({

  retries: 3,

  maxConcurrentRequests: 10,

});

// Refresh tokens automatically on 401

retryer.use(createTokenRefreshPlugin(async (axios) => {

  const { data } = await axios.post('/auth/refresh');

  return { token: data.accessToken };

}));

// Trip circuit open after 5 failures

retryer.use(createCircuitBreaker({ failureThreshold: 5, openTimeout: 30_000 }));

// Drop-in replacement for axios

const { data } = await retryer.axiosInstance.get('/api/users');

```

Try it: [![Edit on CodeSandbox](https://img.shields.io/badge/Edit_on-CodeSandbox-blue?logo=codesandbox)](https://codesandbox.io/p/sandbox/axios-retryer-demo-fppdc4)

---

## Plugins

Import only what your app needs. Each plugin is a documented, tree-shakeable entry point:

| Plugin | Import | Purpose |

|--------|--------|---------|

| `TokenRefreshPlugin` | `axios-retryer/plugins/TokenRefreshPlugin` | Auth token refresh on 401; optional [no-token opt-out](https://samplexbro.github.io/axios-retryer/docs/plugins/token-refresh#opt-out-of-refresh) |

| `CircuitBreakerPlugin` | `axios-retryer/plugins/CircuitBreakerPlugin` | Fail-fast on repeated upstream failures |

| `CachingPlugin` | `axios-retryer/plugins/CachingPlugin` | In-memory response cache with TTR |

| `ManualRetryPlugin` | `axios-retryer/plugins/ManualRetryPlugin` | Store failures and replay on reconnect |

| `MetricsPlugin` | `axios-retryer/plugins/MetricsPlugin` | Live retry counters and events |

| `DebugSanitizationPlugin` | `axios-retryer/plugins/DebugSanitizationPlugin` | Redact secrets from debug logs |

---

## Comparison

| Feature | axios-retryer | axios-retry | retry-axios |

|---------|--------------|-------------|-------------|

| Automatic & Manual Modes | ✅ | ❌ | ❌ |

| Concurrency Control | ✅ | ❌ | ❌ |

| Priority Queue | ✅ | ❌ | ❌ |

| Token Refresh Plugin | ✅ | ❌ | ❌ |

| Circuit Breaker | ✅ | ❌ | ❌ |

| Response Caching | ✅ | ❌ | ❌ |

| Cancellation | ✅ | ❌ | ❌ |

| Plugin Architecture | ✅ | ❌ | ❌ |

| TypeScript-First | ✅ | ⚠️ | ⚠️ |

| Tree-Shakeable | ✅ | ❌ | ❌ |

---

## Performance

Current release benchmarks (standard profile, local suite):

- **Healthy-path throughput:** `2,647 req/sec`

- **Peak burst throughput:** `4,013 req/sec`

- **Cache hit rate:** `100%`

- **Test suite:** `67/67` suites · `675/675` tests passing

---

## Documentation

The full documentation — detailed API reference, all plugin options, guides, examples, and migration notes — lives at:

**[https://samplexbro.github.io/axios-retryer](https://samplexbro.github.io/axios-retryer)**

Quick links:

- [Installation](https://samplexbro.github.io/axios-retryer/docs/installation)

- [Configuration reference](https://samplexbro.github.io/axios-retryer/docs/configuration)

- [Plugins overview](https://samplexbro.github.io/axios-retryer/docs/plugins)

- [Production setup guide](https://samplexbro.github.io/axios-retryer/guides/production)

- [Offline support guide](https://samplexbro.github.io/axios-retryer/guides/offline)

- [Migration 1.x → 2.0](https://samplexbro.github.io/axios-retryer/guides/migration)

- [API reference](https://samplexbro.github.io/axios-retryer/docs/api-reference)

- [SECURITY.md](./SECURITY.md) · [KNOWN_ISSUES.md](./KNOWN_ISSUES.md) · [BENCHMARK_RESULTS.md](./BENCHMARK_RESULTS.md)

---

## Contributing

Bug reports, feature ideas, and pull requests are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

## License

MIT — see [LICENSE](./LICENSE).

---

Made with ❤️ by sampleX (Serhii Zhabskyi)

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/samplexbro/axios-retryer

Awesome Lists containing this project

README

axios-retryer