replayable — record & replay requests in tests, without network
retry — retries with exponential backoff and jitter
ftch
All options are optional:
import { ftch } from 'micro-ftch';let enabled = true;const ctrl = new AbortController();const f = ftch(fetch, { isValidRequest: () => enabled, // killswitch: false makes requests throw killswitchSignal: ctrl.signal, // one-shot hard killswitch, aborts in-flight requests allowedHosts: ['rpc.example.com', 'http://localhost:8545'], // origin allowlist log: (url, opts) => console.log(url, opts), timeout: 5000, // ms; can also be set per-request: f(url, { timeout: 1000 }) concurrencyLimit: 10, // max in-flight requests, extras are queued rps: 10, // max request starts per second
isValidRequest can be toggled at any time and may return a Promise<boolean>;
it is checked before a request, after response headers, and after the body is buffered.
killswitchSignal, once aborted, cancels active requests and blocks all future ones;
construct a new wrapper to re-enable network access.
referrerPolicy: 'no-referrer' is set by default for privacy.
jsonrpc
Batches multiple calls into one JSON-RPC HTTP request. Can massively speed things up
when servers are single-threaded or have small per-user limits.
jsonrpc automatically restricts requests to the exact origin of rpcUrl, whether its
transport is native fetch or an ftch wrapper. Cross-origin redirects are blocked before the
new origin is contacted. Add trusted redirect origins explicitly with
{ allowedHosts: ['rpc-failover.example'] }; the original RPC origin remains allowed.
When the transport was not created by ftch, requests also default to a 240-second timeout and
10 concurrent HTTP requests. Set timeout or concurrencyLimit here to override either value;
an ftch transport keeps its existing operational limits unless these options are provided.
replayable
Records requests and replays them in tests, without calling network code.
Captured entries include response status and headers, so error handling can be
replay-tested too. Logs store requests and responses verbatim, including any
secrets they contain — treat exported fixtures as sensitive.
retry
Retries failed requests with exponential backoff, full jitter and Retry-After support.
By default only safe methods (GET/HEAD/OPTIONS) are retried — retrying a POST can duplicate
a non-idempotent action — and only on network errors or status 408/429/5xx.
Pass a custom shouldRetry to override the policy.
allowedHosts entries are origins: example.com means exactly https://example.com:443,
a port (example.com:8443) means an alternate HTTPS origin, HTTP must be explicit
(http://localhost:8545). Paths, queries and credentials are not valid entries.
Redirects are followed by the wrapper one hop at a time, so the allowlist and
isValidRequest are checked before every hop's request is sent. Hops are capped at 20;
credentials, cookies and API-key headers (extend via sensitiveHeaders) are stripped
on cross-origin hops.
HTTPS→HTTP downgrades are rejected, even without an allowlist. Opt in with
allowInsecureRedirects: true if a trusted endpoint requires one.
allowedHosts is not a complete SSRF sandbox: it validates URL origins, but DNS may
still resolve a permitted hostname to an internal address. Enforce trusted DNS and
network-level egress rules when requests cross a security boundary.