fetch-run

library2.8.3jsnpmunverified

A lightweight middleware library for the Fetch API, version 2.8.3, released monthly with active maintenance. It provides a composable middleware pipeline for fetch requests and responses, similar to koa or express middleware. Key differentiators: minimal (1.2KB gzipped), zero dependencies, supports both browser and Node.js (undici-based fetch), and TypeScript-first with full type inference. Unlike heavier solutions like axios or ky, fetch-run focuses solely on middleware chaining without bundling a fetch polyfill.

testing devops

npm install fetch-run

package ↗

INSTALL

IMPORT

SIG · FETCH-RUN

fetch-run

testingjavascriptv2.8.3

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.

createFetch

✓ import { createFetch } from 'fetch-run'

✗ import createFetch from 'fetch-run'

Named export, not default. ESM-only; no CommonJS support.

compose

✓ import { compose } from 'fetch-run'

✗ const { compose } = require('fetch-run')

Named export; require() works in CJS but TypeScript strict mode may require esModuleInterop.

fetchRun

✓ import { fetchRun } from 'fetch-run'

✗ import { FetchRun } from 'fetch-run'

camelCase, not PascalCase. Used for direct middleware application without createFetch.

Middleware

✓ import type { Middleware } from 'fetch-run'

✗ import { Middleware } from 'fetch-run'

Type import for middleware type definitions. Not a runtime value.

Creates a fetch instance with middleware stack including logging and Bearer token authentication.

import { createFetch } from 'fetch-run'; // Logging middleware const logger = (next) => async (url, init) => { console.log('Request:', url); const response = await next(url, init); console.log('Response status:', response.status); return response; }; // Authorization middleware const auth = (token) => (next) => async (url, init) => { const headers = new Headers(init?.headers); headers.set('Authorization', `Bearer ${token}`); return next(url, { ...init, headers }); }; const fetch = createFetch( logger, auth(process.env.API_TOKEN ?? '') ); async function main() { const res = await fetch('https://api.example.com/data'); const data = await res.json(); console.log(data); } main().catch(console.error);

Debug

Known issues

breakingVersion 2.0 dropped support for Node < 18 (fetch not polyfilled).

fix

Upgrade to Node 18+ or use a fetch polyfill like 'undici' with a custom adapter.

affects: <2.0.0

breakingMiddleware signature changed from async function to sync function returning an async function in v2.0.

fix

Wrap middleware definitions in a higher-order function: `(next) => async (url, init) => { ... }`

affects: <2.0.0

deprecated`compose` is deprecated in v2.5+ in favor of direct `createFetch` for cleaner syntax.

fix

Replace `compose(logger, auth)` with `createFetch(logger, auth)`.

affects: >=2.5.0

gotchaMiddleware must return a Response object, not modify it in place. Mutations may cause undefined behavior.

fix

Always clone and return a new Response: `const newRes = new Response(res.body, res); return newRes;`

affects: >=2.0.0

gotchaTypeScript users: `createFetch` expects tuple of middleware; order matters. Incorrect typings can cause inference failures.

fix

Use `as const` for middleware arrays if needed: `const stack = [logger, auth] as const;`

affects: >=2.0.0

breakingNode.js 18 native fetch is used by default. If using a custom fetch (e.g., undici), it must be injected explicitly.

fix

Pass a custom fetch via `createFetch(middleware, { fetch: customFetch })`.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: middleware is not a function

Passed middleware incorrectly, e.g., forgot to call the higher-order function that returns middleware.

fix

Ensure each middleware is a function returning a function of `(next) => async (url, init) => { ... }` not a direct async function.

Cannot read properties of undefined (reading 'headers')

Trying to modify response headers without cloning the response object.

fix

Always clone response before mutation: `response = new Response(response.body, response)` and then modify headers.

Module '"fetch-run"' has no exported member 'compose'

Importing `compose` that was removed in v2.8.0 or using wrong import path/name.

fix

Use `createFetch` instead of `compose` (removed since v2.8). If using older version, import `compose` from 'fetch-run/compose'.

Type 'void' is not assignable to type 'Response | Promise<Response>'

Middleware callback doesn't return a Response or Promise<Response> at end.

fix

Always return `await next(url, init)` or a new Response at the end of middleware.

Upgrade

Version history

2.8.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

packagefetch-run ↗