@metreeca/http

Composable middleware for the standard fetch API.

@metreeca/http layers recurring HTTP concerns over the standard fetch function, without introducing a bespoke client API. A middleware wraps a fetch implementation, returning a new one with the same signature that adjusts requests and responses as they flow through, and a chain of them is assembled into a single client to be shared across an application:

• Drop-in Clients: every client is a standard fetch function, interchangeable with the platform primitive
• Bundled Middlewares: recurring concerns come solved and tested, keeping call sites free of boilerplate
• Open Customisation: your own middlewares are written and layered exactly like the bundled ones

Installation

npm install @metreeca/http

[!WARNING]

TypeScript consumers must use "moduleResolution": "nodenext"/"node16"/"bundler" in tsconfig.json. The legacy "node" resolver is not supported.

Usage

A client is assembled once from the middlewares an application needs and shared across it, with the root module supplying the assembler and each subpath module a middleware:

import { createFetch } from "@metreeca/http";
import { bearer } from "@metreeca/http/bearer";
import { headers } from "@metreeca/http/headers";
import { success } from "@metreeca/http/success";
import { timeout } from "@metreeca/http/timeout";

const client = createFetch(                // shared across the application
	bearer(() => session.token),             // Authorization header, resolved per request
	headers({ Accept: "application/json" }), // stated on every request
	timeout(5000),                           // gives up on a server that never replies
	success()                                // rejects unless response.ok
);

const response = await client("https://api.example.com/data");

Middlewares are layered in declaration order: requests are processed by the first middleware first and reach the standard fetch function last, while responses travel back through the chain in reverse. The resulting client is itself a standard fetch function, so it is handed to anything expecting the platform primitive and is itself wrapped again by a further chain.

[!NOTE]

This section introduces the overall organisation; each module documents its own concern in detail in the API reference:

| Module | Description | |----------------------------|------------------------------------| | @metreeca/http | Client assembly and HTTP utilities | | Request Authentication | | | @metreeca/http/basic | Basic authentication | | @metreeca/http/bearer | Bearer authentication | | Exchange Control | | | @metreeca/http/headers | Default header fields | | @metreeca/http/throttle | Adaptive pacing and retries | | @metreeca/http/timeout | Bounded response wait | | @metreeca/http/success | Uniform failure reporting | | @metreeca/http/monitor | Exchange reporting | | Exchange Resolution | | | @metreeca/http/cache | HTTP response caching | | @metreeca/http/protocol | Custom protocol handlers | | @metreeca/http/transport | Custom fetch transport |

Support

• open an issue to report a problem or to suggest a new feature
• start a discussion to ask a how-to question or to share an idea

License

This project is licensed under the Apache 2.0 License – see LICENSE file for details.