fetchcraft

Lightweight fetch utilities for Node.js — retry with exponential backoff, LRU response caching, URL normalization, and pagination helpers. Zero dependencies, uses the built-in fetch API (Node 18+).

Installation

npm install fetchcraft

Quick Start

const { fetchWithRetry, FetchCache, buildUrl, paginate } = require('fetchcraft');

// Retry on transient failures
const resp = await fetchWithRetry('https://api.example.com/data', {}, {
  attempts: 3,
  base: 500,
  retryOn: [429, 500, 503],
});

// Cached fetch — responses cached for 60 seconds
const cache = new FetchCache({ ttl: 60, maxSize: 128 });
const r1 = await cache.fetch('https://api.example.com/users');  // network
const r2 = await cache.fetch('https://api.example.com/users');  // cache

// Build URLs
buildUrl('https://api.example.com', '/users', { page: 2, limit: 50 });
// → 'https://api.example.com/users?page=2&limit=50'

// Paginate a REST API
for await (const page of paginate(fetch, 'https://api.example.com/items')) {
  for (const item of page) process(item);
}

API

fetchWithRetry(url, init?, retryOpts?)

Fetch with automatic retry and exponential backoff.

| Option | Default | Description | |---|---|---| | attempts | 3 | Max attempts | | base | 500 | Base delay (ms) | | factor | 2 | Backoff multiplier | | maxDelay | 30000 | Max delay (ms) | | jitter | true | Full jitter | | retryOn | [429,500,502,503,504] | Status codes to retry |

FetchCache({ ttl, maxSize, retryOpts })

LRU-cached fetch wrapper.

const cache = new FetchCache({ ttl: 300, maxSize: 256 });
const resp  = await cache.fetch(url);
cache.clearCache();

URL helpers

| Function | Description | |---|---| | buildUrl(base, path, params) | Construct URL with query params | | normalizeUrl(url) | Canonical form: lowercase, sorted params, no fragment | | stripAuth(url) | Remove user:pass@ |

safeJson(resp, default?)

Parse JSON safely — returns default on any error.

paginate(fetcher, url, opts?)

Async generator — yields JSON data arrays across paginated endpoints.

License

MIT © runtimedev