fetch-extras

Useful utilities for working with Fetch

Build tiny, focused HTTP clients by composing only the features you need on top of the standard fetch API. No wrapper objects, no new interface to learn, no lock-in.

Highlights

• Composable — Each with* function adds a single capability. Stack them to build exactly the client you need.
• Works everywhere — Browsers, Node.js, Deno, Bun, Cloudflare Workers, etc.
• Zero dependencies
• Standard fetch — The input and output are always a plain fetch function. Your code stays portable and familiar.
• Tree-shakeable — Only the utilities you import end up in your bundle.
• TypeScript — Full type definitions with strong generics.
• Schema validation — Validate responses against Standard Schema (Zod, Valibot, ArkType, etc.).

For a full-featured HTTP client on top of Fetch, check out my ky package.

Install

npm install fetch-extras

Usage

import {
	pipeline,
	withTimeout,
	withBaseUrl,
	withHeaders,
	withHttpError,
	withJsonResponse,
} from 'fetch-extras';

// Create a tiny reusable API client that:
// - Times out after 5 seconds
// - Uses a base URL so you only write paths
// - Sends auth headers on every request
// - Throws errors for non-2xx responses
// - Parses JSON responses automatically
const apiFetch = pipeline(
	fetch,
	withTimeout(5000),
	withBaseUrl('https://api.example.com'),
	withHeaders({Authorization: 'Bearer token'}),
	withHttpError(),
	withJsonResponse(),
);

const data = await apiFetch('/users');

pipeline() order is the documented order throughout this package. Runtime wrapper nesting is the inverse, so pipeline(fetch, withTimeout(5000), withHeaders(headers)) becomes withHeaders(headers)(withTimeout(5000)(fetch)).

API

Wrappers

Listed in the recommended pipeline order. Read the list top to bottom as the order you pass wrappers to pipeline().

• withTimeout - Abort requests that take too long
• withBaseUrl - Resolve relative URLs against a base URL
• withSearchParameters - Attach default query parameters to every request
• withHeaders - Attach default headers to every request
• withJsonBody - Auto-stringify plain objects as JSON
• withRateLimit - Enforce client-side rate limiting with a sliding window
• withConcurrency - Cap how many requests can run simultaneously
• withDeduplication - Collapse concurrent identical GET requests into a single call
• withCache - In-memory caching for plain unconditional GET responses with a TTL
• withDownloadProgress - Track download progress
• withUploadProgress - Track upload progress
• withRetry - Retry failed requests with exponential backoff
• withTokenRefresh - Auto-refresh auth tokens on 401 and retry
• withHooks - beforeRequest and afterResponse hooks
• withHttpError - Throw on non-2xx responses

Choose one terminal response wrapper:

• withJsonResponse - Parse response as JSON, with optional Standard Schema validation
• withResponse - Transform the final response into any value

Utilities

• pipeline - Compose with* wrappers without deep nesting
• paginate - Async-iterate over paginated API endpoints
• throwIfHttpError - Throw if a response is non-2xx

Errors

• HttpError - Error class for non-2xx responses
• SchemaValidationError - Error class for schema validation failures

FAQ

How is this different from Ky?

Ky is a full-featured HTTP client with its own API (ky.get(), .json(), etc.). This package instead gives you individual utilities that wrap the standard fetch function. You pick only what you need and compose them together. If you want a batteries-included client, use Ky. If you want to stay close to the fetch API while adding specific capabilities, use this.

How do I use a proxy?

This package wraps the standard fetch API, so proxy support comes from the runtime. In Node.js, use the --use-env-proxy flag.

Related

• is-network-error - Check if a value is a Fetch network error
• ky - HTTP client based on Fetch
• parse-sse - Parse Server-Sent Events (SSE) from a Response