fetch-extras

library3.2.0jsnpmunverified

Composable utilities for the standard Fetch API, version 3.2.0. Provides lightweight, tree-shakeable middleware-style wrappers (withTimeout, withBaseUrl, withHeaders, withRetry, etc.) that decorate the native fetch function. No wrapper objects, no new interface—just pure function composition. Works in browsers, Node.js (>=22), Deno, Bun, Cloudflare Workers. Zero dependencies, full TypeScript generics, Standard Schema response validation. Designed for building minimal, focused HTTP clients without lock-in.

devops

npm install fetch-extras

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FETCH-EXTRAS

fetch-extras

devopsjavascriptv3.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

withTimeout

✓ import { withTimeout } from 'fetch-extras'

✗ import fetchExtras from 'fetch-extras'

Named export from ESM package. No default export.

pipeline

✓ import { pipeline } from 'fetch-extras'

✗ const { pipeline } = require('fetch-extras')

Package is ESM-only since v3. CommonJS require is not supported.

withHttpError

✓ import { withHttpError } from 'fetch-extras'

✗ import { withHttpError } from 'fetch-extras/with-http-error'

All exports are at the package root; no subpath exports.

Creates a reusable API client with timeout, base URL, auth headers, HTTP error throwing, and JSON parsing.

import { pipeline, withTimeout, withBaseUrl, withHeaders, withHttpError, withJsonResponse } from 'fetch-extras'; const apiFetch = pipeline( fetch, withTimeout(5000), withBaseUrl('https://api.example.com'), withHeaders({ 'Authorization': `Bearer ${process.env.KEY ?? ''}` }), withHttpError(), withJsonResponse() ); const data = await apiFetch('/users'); console.log(data);

Debug

Known issues

breakingfetch-extras v3 is ESM-only and requires Node.js >=22.

fix

Ensure your project is ESM (type: module) and Node.js >=22. Use v2.x if CommonJS support is needed.

affects: >=3.0.0

gotchapipeline() order matters: wrappers are applied in the order listed, but at runtime they nest in reverse. See documentation.

fix

Always use pipeline() in the documented order; do not manually compose wrappers unless you understand the nesting.

affects: >=1.0.0

gotchawithCache() caches unconditional GET responses only. Conditional requests (e.g., If-None-Match) are not cached.

fix

If you need conditional caching, handle manually or use a different caching layer.

affects: >=1.0.0

gotchawithRateLimit() uses a sliding window but does not backpressure; calls exceeding the limit are rejected immediately.

fix

For backpressure, combine with withConcurrency() or implement retry logic.

affects: >=1.0.0

deprecatedfetch-extras v2.x is deprecated and no longer maintained.

fix

Upgrade to v3.0.0+ (requires ESM and Node.js >=22).

affects: >=2.0.0 <3.0.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

fetch-extras is ESM-only; using import in a CommonJS file or Node version <22.

fix

Add "type": "module" to your package.json, rename file to .mjs, or use Node.js >=22.

ERR_REQUIRE_ESM: require() of ES Module

Trying to require() an ESM-only package.

fix

Use dynamic import: const { pipeline } = await import('fetch-extras'); or switch to ESM.

TypeError: fetch is not a function

pipeline expects the native fetch function as first argument, but none is available (e.g., older Node without --experimental-fetch).

fix

Ensure your runtime supports fetch, or provide a polyfill. fetch is built into Deno, Bun, Cloudflare Workers, and Node >=18.

Error: withHttpError() should be placed after other wrappers that modify the response

withHttpError() must be after wrappers like withJsonResponse() or withResponse() in the pipeline order.

fix

Place withHttpError() last (or near last) in the pipeline, after any response transformation wrappers.

Upgrade

Version history

3.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/sindresorhus/fetch-extras ↗

packagefetch-extras ↗

homepagehttps://github.com/sindresorhus/fetch-extras#readme ↗