Skip to content
eightyfivePublic

About

Fetch middleware for the modern minimalist

Topics

Resources

Stars

11 stars

Watchers

1 watching

Forks

Repository files navigation

fetch-run

Fetch middleware for the modern minimalist.

A focused TypeScript wrapper around fetch, built around composable middleware.

Api handles JSON request and response bodies. Http uses the same request API while leaving the response untouched.

Install

npm install fetch-run@next

Quick start

This example configures an Api instance with logging and HTTP error handling, then performs a typed request.

import { Api, HTTPError } from 'fetch-run';
import { error, logger } from 'fetch-run/use';

const api = Api.create('https://example.com/api');

// Register response observers before `error`.
api.use(logger);
api.use(error);

type User = { id: number; name: string };

async function loadUser() {
  try {
    return await api.get<User>('users/42');
  } catch (err) {
    if (err instanceof HTTPError) {
      console.error(err.code, await err.response.json());
      return;
    }

    throw err;
  }
}

Api.create() sets Accept: application/json and Content-Type: application/json by default. Pass RequestInit options when creating an instance or making an individual request.

Middleware

Middleware runs on either side of a request: it receives the Request before fetch and the Response afterward. Either value can be inspected or modified.

import type { Layer, Middleware } from 'fetch-run';

const timing: Middleware = (next: Layer) => async (request: Request) => {
  const startedAt = performance.now();
  const response = await next(request);

  console.log(`${request.method} took ${performance.now() - startedAt}ms`);

  return response;
};

api.use(timing);

Middleware executes in last-in, first-out order. Given:

api.use(A);
api.use(B);

the sequence is B before → A before → fetch → A after → B after.

The bundled error middleware throws for unsuccessful HTTP responses. Register middleware that needs to observe the response, such as logger, before error.

API

All Api request methods resolve with parsed JSON.

Method Description
get<Res>(path, options?) Sends a GET request.
search<Res>(path, query, options?) Sends a GET request with a URLSearchParams query.
post<Res, Req>(path, data?, options?) Sends a POST request.
put<Res, Req>(path, data?, options?) Sends a PUT request.
patch<Res, Req>(path, data?, options?) Sends a PATCH request.
delete<Res>(path, options?) Sends a DELETE request.

Req accepts an object, FormData, or no value. Objects are JSON encoded. FormData passes through unchanged and clears the JSON Content-Type header so the browser can set the multipart boundary.

Configuration

const api = Api.create('https://example.com/api', {
  credentials: 'include',
});

api.setHeader('X-Client-Version', '3');
api.setBearer(accessToken);

const unsubscribe = api.subscribe((request, response, data) => {
  if (!response.ok) {
    console.error(request.method, response.status, data);
  }
});

unsubscribe();

setBearer(null) removes the Authorization header. subscribe() receives the request, the original Response, and the parsed JSON body (or null if it cannot be parsed). The response body belongs to the request caller; a subscriber that needs to read it must use response.clone().

Subscriber notifications are asynchronous and do not delay or alter a request's resolved value or rejection. When error throws an HTTPError, subscribers are notified with the corresponding Response and parsed JSON body; the callback does not receive the HTTPError instance.

Included middleware

error

error throws an HTTPError when response.ok is false. HTTPError exposes:

  • code — the HTTP status code
  • request — the originating Request
  • response — the server Response
import { error } from 'fetch-run/use';

api.use(error);

logger

logger writes request and response information to the console, including JSON bodies when available. It is intended for development use.

import { logger } from 'fetch-run/use';

api.use(logger);

Register it before error so failed responses are logged.

retry

retry retries transient failures with exponential backoff. Register it once to configure all requests on an Api or Http instance. Retries are opt-in; existing clients are unchanged until this middleware is registered.

import { createRetry, error, logger } from 'fetch-run/use';

api.use(logger);
api.use(error);
api.use(createRetry({ retry: 3 }));

This allows three additional attempts after the initial request, waiting 1s, 2s, then 4s. With a larger retry budget, delays keep doubling up to a 30s cap. For these defaults, api.use(retry) is also available from fetch-run/use.

The only option is retry: a non-negative safe integer specifying the number of additional attempts. It defaults to 3; use 0 to disable retries. Backoff is always exponential, starting at 1 second and capped at 30 seconds.

Only GET, HEAD, and OPTIONS requests can retry. Write requests (including POST, PUT, PATCH, and DELETE) are never retried.

Retryable failures are network TypeErrors and HTTP 408, 429, 500, 502, 503, 504. Other failures, including ordinary 4xx responses and aborts, are not retried. Retry-After headers are not interpreted automatically.

Passing an AbortSignal cancels both fetch and any pending retry delay. Each request has its own retry budget, including concurrent requests.

Register error before retry, as shown above. Middleware wraps in reverse registration order, so error turns failed responses into HTTPErrors that retry can catch. Retry does not inspect HTTP response statuses itself: omitting error or registering it after retry means HTTP failures will not be retried. After retries are exhausted, the final error is rethrown. In the example above, logger and error see each attempt. Subscribers receive only the final outcome. Use a single retry middleware per client; when also using TanStack Query, enable retries in one layer to avoid multiplying attempts.

xsrf

xsrf reads the browser's XSRF-TOKEN cookie and sets the X-XSRF-TOKEN request header. It works with Laravel Sanctum CSRF protection.

import { xsrf } from 'fetch-run/use';

api.use(xsrf);

Http

Http exposes the same request and middleware APIs as Api, but leaves response parsing to the caller. Use it for downloads, blobs, streams, file uploads, and endpoints that do not return JSON.

import { Http } from 'fetch-run';

const http = Http.create('https://example.com');
const response = await http.get('manual.pdf');
const file = await response.blob();

About

Fetch middleware for the modern minimalist

Topics

Resources

Stars

11 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages