http-fetch-retry

http-fetch-retry es una librería ligera para Node.js que extiende el fetch nativo agregando:

• 🔁 Reintentos automáticos con backoff exponencial + jitter
• ⏱ Timeout por request usando AbortController
• 🧠 Manejo seguro de errores de red y timeouts
• 🧩 Compatibilidad total con fetch nativo (retorna Response)

⚠️ Desde v2.x, fetchWithRetry retorna un Response nativo y NO lanza errores por status 4xx/5xx.

Compatible con: - Node.js 18+ - ESM - CommonJS

Instalación

npm install http-fetch-retry

Uso

ESM

import { HttpClient } from 'http-fetch-retry';

const res = await HttpClient.fetchWithRetry({
  method: 'GET',
  url: 'https://api.example.com',
});

if (!res.ok) {
  console.error('HTTP error:', res.status);
}

const data = await res.json();
console.log(data);

CommonJS

const { HttpClient } = require('http-fetch-retry');

const res = await HttpClient.fetchWithRetry({
  method: 'GET',
  url: 'https://api.example.com',
});

const data = await res.json();
console.log(data);

API

HttpClient.fetchWithRetry(request, options)

Extiende fetch nativo agregando reintentos y timeout.

Retorna

Promise<Response>{=html} (Response nativo)

No parsea automáticamente JSON.

Parámetros

request

Objeto compatible con fetch:

{
  url: string,               // requerido
  method?: string,           // default: GET
  headers?: object,
  body?: any
}

options

{
  timeoutMs?: number,        // default 30000
  maxRetries?: number,       // default 3
  baseDelayMs?: number,      // default 300
  maxDelayMs?: number,       // default 5000
  retryStatusCodes?: number[], // default [408,429,500,502,503,504]
  logger?: function
}

Comportamiento de Retry

Reintenta automáticamente cuando:

• Status HTTP: 408, 429, 500, 502, 503, 504
• Error de red (TypeError)
• Timeout (AbortError)

No reintenta si: - maxRetries = 0 - El body no es reutilizable (ej: streams)

Timeout

Internamente usa AbortController.

Si ocurre timeout se lanza:

• FetchTimeoutError

Errores disponibles

• FetchTimeoutError
• FetchRetryError
• FetchResponseError
• HostAuthenticationError
• HostRequestTimeoutError

Todos heredan de CustomError.

Testing

npm test

Cobertura:

npm run test:coverage

Breaking Changes

v2.0.0

• fetchWithRetry ahora retorna Response nativo
• Ya no parsea JSON automáticamente
• Ya no lanza error por status 4xx/5xx
• Comportamiento alineado 100% con fetch

Migración:

Antes:

const data = await HttpClient.fetchWithRetry(...);

Ahora:

const res = await HttpClient.fetchWithRetry(...);
const data = await res.json();

Licencia

MIT