@boy-offi9-inc/reqkit 0.2.0 → 0.5.0

package/README.md

@@ -5,6 +5,8 @@
 </p>
 
 <p align="center">
+  <a href="https://www.npmjs.com/package/@boy-offi9-inc/reqkit"><img src="https://img.shields.io/npm/v/@boy-offi9-inc/reqkit?color=CB3837&logo=npm&logoColor=white" alt="npm version"></a>
+  <a href="https://github.com/boy-offi9-inc/reqkit/actions/workflows/ci.yml"><img src="https://github.com/boy-offi9-inc/reqkit/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
   <img src="https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white" alt="Node >=18">
   <img src="https://img.shields.io/badge/npm-%40boy--offi9--inc%2Freqkit-CB3837?logo=npm&logoColor=white" alt="npm package">
@@ -15,27 +17,96 @@
 
 # reqkit
 
-Small, composable HTTP helper functions. Not a client, not an axios replacement — works alongside `fetch`, `axios`, or anything else you're already using. Pull in the one function you need; ignore the rest.
+**Tiny, zero-dependency HTTP helpers for `fetch`, axios, or anything else — retries that respect `Retry-After`, timeouts that really cancel, and errors that make sense.**
+
+Not a client, not an axios replacement. Pull in the one function you need, or let [`createFetch`](#createfetchdefaults) wire them together for you — you always get a plain `Response` back.
 
 ```js
-const { withRetry, normalizeError } = require("@boy-offi9-inc/reqkit");
+import { createFetch } from "@boy-offi9-inc/reqkit";
+
+const api = createFetch({
+  baseUrl: "https://api.example.com/v1",
+  headers: () => ({ authorization: `Bearer ${getToken()}` }),
+  timeout: 10_000, // per attempt
+});
 
-const data = await withRetry(() => fetch(url).then(r => r.json()));
+const user = await api.json("/users/1", { query: { expand: "team" } });
+// retries network errors, timeouts and 429/5xx, waits for Retry-After,
+// doesn't retry a POST unless you opt in, throws HTTPError on non-2xx
 ```
 
+Or take just the pieces you want:
+
+```js
+import { createLimiter, withRetry, withTimeout } from "@boy-offi9-inc/reqkit";
+
+const limit = createLimiter(4); // 4 downloads at a time
+const pages = await limit.map(urls, (url) =>
+  withRetry(
+    () => withTimeout((signal) => fetch(url, { signal }), 8000),
+    { retryStatusCodes: [429, 503] } // and it waits for Retry-After
+  )
+);
+```
 ---
 
-## Why this exists
+## Playground
+
+Try everything in your browser — retries obeying `Retry-After`, rate limiting, the circuit breaker, caching, SSE streaming and a resumable download that survives a dropped connection. It runs against a fake in-memory server, so there's nothing to install and no network involved.
+
+Run it locally: `npm run build && python3 -m http.server -d docs` → open `http://localhost:8000`. (ES modules don't load from `file://`, so it needs a server.) The repo's `pages.yml` workflow publishes the same folder to GitHub Pages — enable it once under Settings → Pages → Source: "GitHub Actions".
 
-Most HTTP retry/timeout wrappers bundle everything into a client you have to fully adopt. This is the opposite: standalone functions that compose with whatever you're already using, and a couple of small helpers that you can pick up independently.
+## Works with what you already use
 
-**Honest note:** `withRetry`, `withTimeout`, and `normalizeError` solve a well-covered problem — there are other solid packages doing similar things (`fetchy`, `fetchpilot`, `p-retry`, to name a few).
+Recipes for **axios, ky, got, undici/node-fetch**, testing, and LLM streaming live in [RECIPES.md](./RECIPES.md): keep your client, bolt on just the piece you're missing (`Retry-After`-aware retries, a rate limiter, a circuit breaker).
 
-- **`retryAfterAware`** — actually reads `Retry-After`/`X-RateLimit-Reset` headers instead of blind backoff on 429s. Most retry libraries treat rate-limit responses like any other failure and ignore the server's suggested retry time.
-- **`withProgress`** — progress callback for any streamed response body (downloads, large payloads, anything), not tied to a specific HTTP client.
-- **`withDedupe`** — coalesces concurrent calls with the same key into one in-flight call, so simultaneous requests for the same resource don't each hit the network.
+## Runtime support
 
-Zero dependencies. CJS + ESM. TypeScript types included.
+| Runtime | Status |
+|---|---|
+| **Node 18, 20, 22, 24** | Primary target. Full test suite runs in CI on all four. |
+| **Deno, Bun, browsers, Cloudflare Workers** | Use the dependency-free ESM bundle (`@boy-offi9-inc/reqkit/browser`, or `import … from "npm:@boy-offi9-inc/reqkit"` in Deno). Only web-standard APIs are used. CI smoke-tests the bundle on Deno, Bun and headless Chromium — **experimental** until those jobs have a track record; please open an issue if one misbehaves. |
+
+```html
+<script type="module">
+  import { createFetch } from "https://cdn.jsdelivr.net/npm/@boy-offi9-inc/reqkit@0.5.0/dist/reqkit.mjs";
+</script>
+```
+
+---
+
+## Pick what you need
+
+| You want to… | Use |
+|---|---|
+| Retry on errors *and* bad statuses, honoring `Retry-After` | [`withRetry`](#withretryfn-opts) / [`retryAfterAware`](#retryafterawarefn-opts) |
+| Time out *and actually cancel* the request | [`withTimeout`](#withtimeoutfn-ms-opts) |
+| One error shape from fetch, axios and node (incl. `fetch failed`) | [`normalizeError`](#normalizeerrorerr) |
+| Parse JSON without try/catch | [`parseJsonSafe`](#parsejsonsafeinput) |
+| Build a query string from an object | [`buildQuery`](#buildqueryparams) |
+| Download progress and size caps for any stream | [`withProgress`](#withprogressresponse-onprogress-opts) |
+| Merge identical concurrent calls into one | [`withDedupe`](#withdedupefn-opts) |
+| Run N things at a time | [`createLimiter`](#createlimiterconcurrency) |
+| Slow down *before* the server says 429 (obey `X-RateLimit-*`) | [`createRateLimiter`](#createratelimiteropts) |
+| Stop hammering a service that keeps failing | [`createCircuitBreaker`](#createcircuitbreakeropts) |
+| Cache GETs (TTL, stale-while-revalidate, ETag/304) | [`createFetch` → `cache`](#caching) |
+| Resume a download after the connection drops | [`downloadResumable`](#downloadresumableurl-opts) |
+| Read SSE / NDJSON / lines from a streamed body (LLM tokens!) | [`readSSE` / `readNDJSON` / `readLines`](#streaming-readsse-readndjson-readlines) |
+| Test retry/timeout code without a network | [`createMockFetch`](#createmockfetch) |
+| All of the above, wired up | [`createFetch`](#createfetchdefaults) |
+
+---
+
+## Why this exists
+
+Most HTTP retry/timeout wrappers bundle everything into a client you have to fully adopt. This is the opposite: standalone functions that compose with whatever you're already using. Zero dependencies, CJS + ESM, TypeScript types included.
+
+**Honest note:** retries, timeouts and error normalization are a well-covered problem — there are other solid packages doing similar things (`fetchy`, `fetchpilot`, `p-retry`, to name a few). What reqkit leans on:
+
+- **It reads the server.** Retries wait for `Retry-After` / `X-RateLimit-Reset` instead of blind backoff on 429s — most retry libraries treat rate-limit responses like any other failure.
+- **It's safe by default.** `createFetch` only retries idempotent methods, so a timed-out `POST` can't double-charge anyone.
+- **It understands real-world errors.** Node's `TypeError: fetch failed` and the browser's `Failed to fetch` are classified as network errors, and a deliberate abort is never reported as a timeout.
+- **It's not tied to a client.** `withProgress`, `withDedupe` and `createLimiter` work with any streamed body or async function.
 
 ---
 
@@ -51,23 +122,36 @@ npm install @boy-offi9-inc/reqkit
 
 ### `withRetry(fn, opts?)`
 
-Retries an async function with exponential backoff + jitter.
+Retries an async function with exponential backoff + jitter. Retries on thrown errors, and — opt in — on *results* (HTTP status codes or any predicate), waiting for `Retry-After` / `X-RateLimit-Reset` when the result has headers.
 
 ```js
 const data = await withRetry(
   () => fetch(url).then(r => r.json()),
   { retries: 3, baseDelayMs: 300, onRetry: (err, attempt, delayMs) => console.log(`retry ${attempt} in ${delayMs}ms`) }
 );
+
+// fetch doesn't throw on 4xx/5xx — retry on statuses by returning the Response:
+const res = await withRetry(() => fetch(url), { retryStatusCodes: [429, 500, 502, 503, 504] });
 ```
 
 | Option | Default | Description |
 |---|---|---|
-| `retries` | `3` | max retry attempts after the first try |
+| `retries` | `3` | max retry attempts after the first try (`Infinity` works with `maxRetryTime`) |
 | `baseDelayMs` | `300` | initial delay |
-| `maxDelayMs` | `10000` | delay ceiling |
-| `shouldRetry` | retries anything but AbortError | `(err, attempt) => boolean` |
-| `onRetry` | — | `(err, attempt, delayMs) => void` |
-| `signal` | — | `AbortSignal` — cancels the whole retry loop, including any pending backoff wait, throwing `RetryAbortedError` |
+| `maxDelayMs` | `10000` | backoff ceiling |
+| `factor` | `2` | backoff multiplier |
+| `jitter` | `0.2` | extra random fraction on top of the delay; `0` disables; `"full"` picks uniformly in `[0, delay]` (AWS "full jitter" — best when many clients retry at once) |
+| `maxRetryTime` | `Infinity` | total time budget across attempts and waits; once the next wait would blow it, the last error/result is surfaced |
+| `shouldRetry` | retries anything but AbortError | `(err, attempt) => boolean` — for thrown errors |
+| `retryStatusCodes` | `[]` | retry when `result.status` is in this list |
+| `shouldRetryResult` | — | `(result, attempt) => boolean` — retry on any result predicate |
+| `respectRetryAfter` | `true` | wait for `Retry-After` / `X-RateLimit-Reset` from `result.headers` |
+| `maxRetryAfterMs` | `60000` | cap on a header-provided wait |
+| `calculateDelay` | — | `({ attempt, error, result, delayMs }) => ms \| false` — override the wait, or `false` to stop |
+| `onRetry` | — | `(err, attempt, delayMs, { reason, result, status }) => void` — `err` is `undefined` when a result triggered the retry |
+| `signal` | — | `AbortSignal` — cancels the whole retry loop, including any pending backoff wait, throwing `RetryAbortedError` (its `cause` is the last failure) |
+
+When retries run out on a *result* (e.g. a 503), the last result is returned rather than thrown — you decide what a bad status means. Bodies of retried responses are cancelled so connections are freed.
 
 ```js
 // Cancel a long retry/backoff sequence externally — e.g. the user navigated away
@@ -76,9 +160,19 @@ const promise = withRetry(() => fetch(url), { retries: 5, signal: controller.sig
 controller.abort(); // rejects with RetryAbortedError, even mid-backoff
 ```
 
-> **Heads up:** `fetch` doesn't throw on 4xx/5xx, so `withRetry` alone won't retry a `500`. Throw inside `fn` for the statuses you care about (`if (!r.ok) throw ...`), or use `retryAfterAware` below, which retries on status codes.
+**Stop early with `StopRetry`** — throw it from inside `fn` when an error is not worth retrying (bad credentials, a 400...):
 
-### `withTimeout(fn, ms)`
+```js
+const { withRetry, StopRetry } = require("@boy-offi9-inc/reqkit");
+
+await withRetry(async () => {
+  const res = await fetch(url);
+  if (res.status === 401) throw new StopRetry(new Error("bad token")); // rethrown as-is, no more attempts
+  return res;
+});
+```
+
+### `withTimeout(fn, ms, opts?)`
 
 Races an async function against a timeout, passing it an `AbortSignal` so the underlying request can actually be cancelled.
 
@@ -90,6 +184,12 @@ const data = await withTimeout(
 // throws TimeoutError on timeout, regardless of whether fn cooperates with the signal
 ```
 
+Pass your own `signal` to cancel from the outside too — it's linked into the one `fn` receives, and aborting it rejects with its reason even if `fn` ignores the signal. Use `ms: Infinity` to disable the timer and only link the signal. A negative or non-number `ms` throws a `TypeError`.
+
+```js
+await withTimeout(signal => fetch(url, { signal }), 5000, { signal: userController.signal });
+```
+
 ### `normalizeError(err)`
 
 One consistent error shape regardless of source (fetch, axios, node http, generic):
@@ -126,7 +226,7 @@ For full parsing/nested-object support, use [`query-string`](https://www.npmjs.c
 
 ### `retryAfterAware(fn, opts?)`
 
-Retries a fetch-like call, honoring `Retry-After`/`X-RateLimit-Reset` headers on 429/503 instead of blind backoff.
+A ready-made preset over `withRetry`: retries a fetch-like call on 429/503, honoring `Retry-After`/`X-RateLimit-Reset` headers instead of blind backoff (no jitter; thrown network errors and timeouts are retried too). Use `withRetry` directly for jitter, budgets, or custom statuses.
 
 ```js
 const response = await retryAfterAware(
@@ -148,7 +248,7 @@ const response = await retryAfterAware(
 
 The body of every response that gets retried is cancelled so the connection is freed.
 
-### `withProgress(response, onProgress?)`
+### `withProgress(response, onProgress?, opts?)`
 
 Reads a streamed `Response` body while reporting progress, returns the collected bytes as a `Uint8Array`.
 
@@ -193,9 +293,193 @@ const fn = withDedupe((req) => doFetch(req), { keyFn: (req) => req.url });
 
 ---
 
+### `createLimiter(concurrency)`
+
+At most `concurrency` calls run at once; the rest wait in a FIFO queue.
+
+```js
+const limit = createLimiter(4);
+
+const files = await limit.map(urls, (url) => download(url)); // results keep input order
+// or one at a time:
+const res = await limit(() => fetch(url));
+
+limit.activeCount;  // running now
+limit.pendingCount; // waiting
+```
+
+A task that throws or rejects only fails its own promise — the queue keeps going. `concurrency` must be an integer ≥ 1 (or `Infinity`).
+
+### `createRateLimiter(opts?)`
+
+A *proactive* limiter: it slows you down before the server has to say 429. It's fed by your own budget (`requests` per `perMs`, sliding window) **and** by what the server tells you — `X-RateLimit-Remaining` / `-Reset`, `RateLimit-*`, and `Retry-After` on 429/503. Once the server says `remaining: 0`, everything pauses until the reset. Callers are served FIFO.
+
+```js
+const rl = createRateLimiter({ requests: 10, perMs: 1000 });
+
+const res = await rl.run(() => fetch(url)); // acquire → call → learn from the response headers
+// or by hand:
+await rl.acquire({ signal });  // rejects with the signal's reason if aborted while waiting
+rl.update(response);
+rl.blockedForMs;               // time left on a server-imposed pause
+```
+
+Reset headers are understood in both flavors: delta seconds (`30`) and absolute epoch (seconds or ms). In `createFetch`, waiting for the budget never counts against the per-attempt timeout.
+
+### `createCircuitBreaker(opts?)`
+
+After `failureThreshold` consecutive failures the circuit **opens** and calls fail instantly with `CircuitOpenError` for `resetTimeoutMs` — so a dying service isn't hammered and your callers don't sit waiting on it. Then it goes **half-open**, lets a probe through, and closes again on success.
+
+```js
+const breaker = createCircuitBreaker({ failureThreshold: 5, resetTimeoutMs: 30_000 });
+
+try {
+  const res = await breaker.run(() => fetch(url));
+} catch (err) {
+  if (err instanceof CircuitOpenError) console.log(`try again in ${err.retryAfterMs}ms`);
+}
+breaker.state; // "closed" | "open" | "half-open"
+```
+
+By default a thrown error (except `AbortError`) or a result with `status >= 500` counts as a failure; override with `isFailure(valueOrError, isError)`. `CircuitOpenError` has `code: "CIRCUIT_OPEN"` and is never classified as a network error, so retries stop the moment the circuit opens.
+
+### Streaming: `readSSE`, `readNDJSON`, `readLines`
+
+Async iterators over a streamed body — a `Response`, a web `ReadableStream`, or any async iterable (Node streams). Early `break` and `signal` abort both cancel the stream so the connection is released.
+
+```js
+// LLM-style token stream (Server-Sent Events)
+for await (const { event, data, id } of readSSE(response, { signal })) {
+  if (data === "[DONE]") break;
+  process.stdout.write(JSON.parse(data).token);
+}
+
+for await (const row of readNDJSON(response)) console.log(row); // newline-delimited JSON
+for await (const line of readLines(response)) console.log(line);
+```
+
+`readSSE` follows the spec: multi-line `data:` is joined with `\n`, comments are ignored, `event` defaults to `"message"`, `id` carries over, `retry` is parsed, and an event cut off by the end of the stream is dropped. `readNDJSON` skips blank lines and names the bad line on a parse error (or pass `skipInvalid: true`). Line splitting handles `\n`, `\r\n`, `\r`, a BOM, and multi-byte characters split across chunks.
+
+### `downloadResumable(url, opts?)`
+
+Downloads into memory and, if the connection drops mid-body, **resumes with an HTTP `Range` request** instead of starting over. It sends `If-Range` with the first response's strong ETag (or `Last-Modified`), so a file that changed on the server is restarted rather than stitched together wrongly; if the server ignores `Range`, it restarts from zero.
+
+```js
+const bytes = await downloadResumable(url, {
+  onProgress: ({ loaded, total, percent }) => console.log(percent),
+  maxBytes: 200 * 1024 * 1024, // BodyTooLargeError past this
+  retries: 5,                  // consecutive attempts *without progress*
+  signal,
+  onRetry: (err, attempt, delayMs, { resumeFrom }) => console.log(`resuming from byte ${resumeFrom}`),
+});
+```
+
+It honors `Retry-After` on 429/503, never retries a 4xx (other than 408/425/429) or a size-limit error, and asks for `Accept-Encoding: identity` so byte offsets line up. Pass `fetch: myCreateFetchInstance` to route it through your own client.
+
+### `createMockFetch()`
+
+A scriptable, fetch-compatible test double — for testing code with retries, timeouts, and rate limits without a network.
+
+```js
+const mock = createMockFetch();
+
+mock.on("GET", "/users/1")
+  .replyOnce(503, "busy", { headers: { "retry-after": "0" } })  // consumed in order…
+  .reply(200, { id: 1 });                                        // …then this, forever
+mock.post(/orders/).failOnce(mock.networkError("ECONNRESET"));   // reject like a real network failure
+mock.get("/slow").reply(200, "late", { delayMs: 500 });          // respects AbortSignal → test timeouts
+
+const api = createFetch({ fetch: mock.fetch, baseUrl: "https://api.test" });
+await api.json("/users/1"); // { id: 1 } — after one retry
+mock.calls;                 // [{ url, method, headers, body, json, signal }, ...]
+mock.reset();
+```
+
+String matchers match the full URL, `pathname + search`, or the bare `pathname`; RegExp and `(url) => boolean` work too, and `"*"` matches any method. `replyWith(call => …)` returns a `Response` or `{ status, body, headers }`. Unmatched requests reject with a clear error (and are still recorded in `mock.calls`).
+
+### `createFetch(defaults)`
+
+Opt-in assembly of the pieces above into a fetch-like function. It's still plain `fetch` underneath: you get a standard `Response`, and you can pass your own `fetch`.
+
+```js
+const { createFetch } = require("@boy-offi9-inc/reqkit");
+
+const api = createFetch({
+  baseUrl: "https://api.example.com/v1",
+  headers: () => ({ authorization: `Bearer ${getToken()}` }), // object, or a function for changing tokens
+  timeout: 10_000,            // per attempt
+  retry: { retries: 3 },      // false to disable
+  dedupe: true,               // merge identical concurrent GETs
+});
+
+const user = await api.json("/users/1", { query: { expand: ["team", "roles"] } });
+const created = await api("/users", { method: "POST", json: { name: "Ada" } }); // Response
+
+try {
+  await api("/missing");
+} catch (err) {
+  if (err instanceof HTTPError) console.log(err.status, await err.response.json());
+}
+
+const admin = api.extend({ headers: { "x-role": "admin" } }); // merges over the parent
+```
+
+| Default / per-request option | Default | Description |
+|---|---|---|
+| `baseUrl` | — | joined onto relative URLs; absolute URLs are left alone |
+| `headers` | — | object, `Headers`, or `() => headers` (sync or async) |
+| `query` *(per request)* | — | object, serialized with `buildQuery` |
+| `json` *(per request)* | — | serialized as the body, `content-type: application/json` set for you |
+| `timeout` | `30000` | per attempt, in ms; `false` disables |
+| `signal` *(per request)* | — | external abort; surfaces as a plain `AbortError`, never retried |
+| `retry` | see below | `false` disables; otherwise `{ retries, statusCodes, methods, baseDelayMs, maxDelayMs, factor, jitter, maxRetryTime, shouldRetry, calculateDelay, onRetry }` |
+| `rateLimit` | — | `true` just learns from `X-RateLimit-*` / `Retry-After`; `{ requests, perMs }` also enforces a budget; or pass a shared [`createRateLimiter`](#createratelimiteropts) |
+| `circuitBreaker` | — | `true` / options → one breaker **per origin**; or pass a shared [`createCircuitBreaker`](#createcircuitbreakeropts), or `(url) => breaker`. An open circuit stops retries immediately. |
+| `cache` | — | in-memory GET cache — see [Caching](#caching). `true` = 60s TTL. Per request: `cache: false` bypasses, `"reload"` refreshes |
+| `dedupe` | `false` | merge identical concurrent `GET`/`HEAD` calls; every caller gets its own readable clone. Requests with their own `signal` are never merged. |
+| `throwHttpErrors` | `true` | throw `HTTPError` for non-2xx (`err.status`, `err.response`, `err.url`, `err.method`) |
+| `fetch` | `globalThis.fetch` | swap in undici, node-fetch, a test double... |
+| `onRequest(ctx)` | — | once per call; may mutate `ctx.url` / `ctx.init` (e.g. add a header) |
+| `onResponse(ctx)` | — | once per call, with the final response, before `HTTPError` is thrown |
+
+#### Caching
+
+```js
+const api = createFetch({
+  baseUrl: "https://api.example.com",
+  cache: { ttl: 30_000, staleWhileRevalidate: 5 * 60_000 },
+});
+
+await api.json("/config"); // network
+await api.json("/config"); // fresh → served from memory, no request
+// after 30s: stale → returned instantly, refreshed in the background
+// after 5m30s: revalidated with If-None-Match / If-Modified-Since — a 304 reuses the cached body
+```
+
+| `cache` option | Default | Description |
+|---|---|---|
+| `ttl` | `60000` | serve without asking the server for this long |
+| `staleWhileRevalidate` | `0` | after the TTL, keep serving the stale copy this long while refreshing in the background |
+| `maxEntries` | `100` | size of the built-in LRU store |
+| `maxBodyBytes` | `1 MiB` | bigger responses aren't cached |
+| `store` | built-in LRU | bring your own (`get`/`set`/`delete`, sync or async) — Redis, IndexedDB, a `Map`… |
+| `onEvent` | — | `({ type: "hit" \| "stale" \| "revalidated" \| "miss" \| "store", url })` for logging/metrics |
+
+Only `GET` `200` responses are cached; `Cache-Control: no-store` and `Vary: *` are respected. **Every request header is part of the cache key**, so a response fetched with one user's `Authorization` can never be served to another. Each hit is a fresh `Response`, so bodies can be read as many times as you like. `extend()` children share the parent's cache, limiter and breakers.
+
+**Retry defaults:** 2 retries on network errors, timeouts, and status `408, 425, 429, 500, 502, 503, 504`, honoring `Retry-After`. Only **idempotent methods** (`GET, HEAD, OPTIONS, PUT, DELETE`) are retried — `POST`/`PATCH` aren't, so a timeout can't double-charge anyone. Opt a request in by sending an `Idempotency-Key` header, or by listing the method in `retry.methods`. Stream bodies are never retried (they can't be replayed).
+
+---
+
 ## Design notes
 
 - **Zero dependencies.** Nothing to audit, nothing to break underneath you.
 - **CJS + ESM.** `require()` and `import` both work.
 - **Composable, not a client.** Every function takes and returns plain values (`Response`, plain objects, `Uint8Array`) — nothing proprietary to learn.
-- **TypeScript types included**, hand-written (no build step to go wrong).
+- **TypeScript types included**, hand-written (no build step to go wrong), with separate entries for CJS and ESM.
+
+---
+
+## Prior art
+
+reqkit's building blocks are small, from-scratch implementations of ideas that proved themselves in popular libraries — go look at them, they're great: [`p-retry`](https://github.com/sindresorhus/p-retry) (`StopRetry`, time budgets), [`ky`](https://github.com/sindresorhus/ky) and [`ofetch`](https://github.com/unjs/ofetch) (`HTTPError`, `json`/`query`/`baseUrl`, `extend`, retry statuses), [`got`](https://github.com/sindresorhus/got) and [`axios-retry`](https://github.com/softonic/axios-retry) (retry only idempotent methods, `calculateDelay`), [`p-limit`](https://github.com/sindresorhus/p-limit) (concurrency limiter), [`opossum`](https://github.com/nodeshift/opossum) (circuit breaker), [`bottleneck`](https://github.com/SGrondin/bottleneck) / [`p-throttle`](https://github.com/sindresorhus/p-throttle) (rate limiting), [`eventsource-parser`](https://github.com/rexxars/eventsource-parser) (SSE), [`nock`](https://github.com/nock/nock) / undici's `MockAgent` (mocking), the HTTP caching RFCs (`stale-while-revalidate`, conditional requests), and the AWS Architecture Blog's "full jitter" backoff.

package/RECIPES.md

@@ -0,0 +1,243 @@
+# Recipes
+
+reqkit is a set of small functions, so it slots *around* the HTTP client you already use. Each recipe below keeps your client and adds just the piece you're missing.
+
+> The snippets use only reqkit's documented API plus each library's documented hooks/interceptors. The reqkit side is covered by its test suite; the third-party libraries (axios, ky, got) aren't installed in reqkit's CI, so if a snippet drifts with a new major version of one of them, please open an issue.
+
+- [axios](#axios) · [ky](#ky) · [got](#got) · [undici / node-fetch / any fetch](#undici--node-fetch--any-fetch)
+- [Deno, Bun, Cloudflare Workers, browsers](#deno-bun-cloudflare-workers-browsers)
+- [Testing your own code](#testing-your-own-code)
+- [LLM streaming (SSE)](#llm-streaming-sse)
+
+A tiny helper used in the axios and got recipes — reqkit reads headers through `.get(name)`, and those libraries hand you plain objects:
+
+```js
+const asHeaders = (h) => ({
+  get: (name) => (typeof h?.get === "function" ? h.get(name) : h?.[name.toLowerCase()]) ?? null,
+});
+```
+
+---
+
+## axios
+
+axios throws on 4xx/5xx, so retry decisions go in `shouldRetry`. `normalizeError` already understands axios errors (`status`, `isNetworkError`, `isTimeout`, cancellation).
+
+**Retries that honor `Retry-After`:**
+
+```js
+import axios from "axios";
+import { withRetry, normalizeError, getWaitMsFromHeaders } from "@boy-offi9-inc/reqkit";
+
+const RETRY_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+
+export function getWithRetry(url, config) {
+  return withRetry(() => axios.get(url, config), {
+    retries: 3,
+    shouldRetry: (err) => {
+      const n = normalizeError(err);
+      return !n.isAborted && (n.isNetworkError || n.isTimeout || RETRY_STATUS.has(n.status));
+    },
+    // use the server's Retry-After when it sent one, otherwise reqkit's backoff
+    calculateDelay: ({ error, delayMs }) => {
+      const wait = getWaitMsFromHeaders(asHeaders(error?.response?.headers));
+      return wait === null ? delayMs : Math.min(wait, 60_000);
+    },
+  });
+}
+```
+
+Only retry idempotent requests (GET/PUT/DELETE) this way — a retried POST can run twice.
+
+**Proactive rate limiting** (slow down *before* the 429) with interceptors:
+
+```js
+import { createRateLimiter } from "@boy-offi9-inc/reqkit";
+
+const rl = createRateLimiter({ requests: 10, perMs: 1000 });
+const api = axios.create({ baseURL: "https://api.example.com" });
+
+api.interceptors.request.use(async (config) => {
+  await rl.acquire({ signal: config.signal });
+  return config;
+});
+api.interceptors.response.use(
+  (res) => {
+    rl.update({ status: res.status, headers: asHeaders(res.headers) }); // learns X-RateLimit-* / Retry-After
+    return res;
+  },
+  (err) => {
+    if (err.response) rl.update({ status: err.response.status, headers: asHeaders(err.response.headers) });
+    throw err;
+  }
+);
+```
+
+**Circuit breaker:**
+
+```js
+import { createCircuitBreaker, CircuitOpenError } from "@boy-offi9-inc/reqkit";
+
+const breaker = createCircuitBreaker({
+  failureThreshold: 5,
+  resetTimeoutMs: 30_000,
+  // count network errors and 5xx — not 404s or user cancellations
+  isFailure: (err, isError) => isError && !axios.isCancel(err) && (!err.response || err.response.status >= 500),
+});
+
+try {
+  const { data } = await breaker.run(() => api.get("/users"));
+} catch (err) {
+  if (err instanceof CircuitOpenError) showOfflineBanner(err.retryAfterMs);
+}
+```
+
+---
+
+## ky
+
+ky already retries, so the best additions are the pieces it doesn't have: a **rate limiter** and a **circuit breaker**. ky's hooks make the limiter a few lines:
+
+```js
+import ky from "ky";
+import { createRateLimiter, createCircuitBreaker, readSSE } from "@boy-offi9-inc/reqkit";
+
+const rl = createRateLimiter({ requests: 5, perMs: 1000 });
+
+const api = ky.create({
+  prefixUrl: "https://api.example.com",
+  hooks: {
+    beforeRequest: [async (request) => { await rl.acquire({ signal: request.signal }); }],
+    afterResponse: [(request, options, response) => { rl.update(response); }], // ky gives you a real Response
+  },
+});
+
+const breaker = createCircuitBreaker({
+  // ky throws HTTPError for non-2xx with `err.response`
+  isFailure: (err, isError) => isError && err.name !== "AbortError" && (!err.response || err.response.status >= 500),
+});
+
+const users = await breaker.run(() => api.get("users").json());
+```
+
+Prefer reqkit's retries over ky's? Set `retry: 0` on the ky instance and wrap the call in `withRetry` (with `shouldRetry` using `normalizeError`, as in the axios recipe).
+
+---
+
+## got
+
+```js
+import got from "got";
+import { createRateLimiter } from "@boy-offi9-inc/reqkit";
+
+const rl = createRateLimiter({ requests: 10, perMs: 1000 });
+
+const api = got.extend({
+  prefixUrl: "https://api.example.com",
+  hooks: {
+    beforeRequest: [async () => { await rl.acquire(); }],
+    afterResponse: [
+      (response) => {
+        rl.update({ status: response.statusCode, headers: asHeaders(response.headers) });
+        return response;
+      },
+    ],
+  },
+});
+```
+
+got has its own retry logic (it only retries idempotent methods by default, and honors `Retry-After`), so there's usually no need to add reqkit's.
+
+---
+
+## undici / node-fetch / any fetch
+
+`createFetch` takes any fetch-compatible function:
+
+```js
+import { fetch as undiciFetch, Agent } from "undici";
+import { createFetch } from "@boy-offi9-inc/reqkit";
+
+const dispatcher = new Agent({ connections: 20 });
+const api = createFetch({
+  baseUrl: "https://api.example.com",
+  fetch: (url, init) => undiciFetch(url, { ...init, dispatcher }),
+  retry: { retries: 3 },
+  cache: { ttl: 30_000 },
+});
+```
+
+The standalone helpers (`withRetry`, `withTimeout`, `createLimiter`, `createRateLimiter`, `downloadResumable`, …) don't care which client sits underneath.
+
+---
+
+## Deno, Bun, Cloudflare Workers, browsers
+
+reqkit only uses web-standard APIs, and the package ships a dependency-free ESM bundle at `@boy-offi9-inc/reqkit/browser`.
+
+```js
+// Deno
+import { createFetch } from "npm:@boy-offi9-inc/reqkit";
+
+// Bun / Node / Workers (via wrangler's bundler)
+import { createFetch } from "@boy-offi9-inc/reqkit";
+
+// Browser, no build step — pin the version
+import { createFetch } from "https://cdn.jsdelivr.net/npm/@boy-offi9-inc/reqkit@0.5.0/dist/reqkit.mjs";
+```
+
+Notes: in Workers the in-memory cache and rate limiter live **per isolate**, so treat them as best-effort or pass a `store` backed by KV / Durable Objects. In browsers, `cache` is separate from the HTTP cache the browser already keeps. Node 18+ is the primary, fully tested target; CI also smoke-tests the bundle on Deno, Bun and headless Chromium (those jobs are new — if one is red, open an issue).
+
+---
+
+## Testing your own code
+
+Take `fetch` as a parameter (or pass it to `createFetch`) and hand in `createMockFetch` during tests:
+
+```js
+import { createMockFetch, createFetch } from "@boy-offi9-inc/reqkit";
+
+test("recovers from a flaky upstream", async () => {
+  const mock = createMockFetch();
+  mock.get("/profile")
+    .failOnce(mock.networkError())                                   // connection refused
+    .replyOnce(503, "busy", { headers: { "retry-after": "0" } })     // then overloaded
+    .reply(200, { name: "Ada" });                                    // then fine
+
+  const api = createFetch({ fetch: mock.fetch, baseUrl: "https://api.test", retry: { baseDelayMs: 1 } });
+
+  expect(await api.json("/profile")).toEqual({ name: "Ada" });
+  expect(mock.calls).toHaveLength(3);
+});
+
+test("gives up politely on a hanging server", async () => {
+  const mock = createMockFetch();
+  mock.get("/slow").reply(200, "late", { delayMs: 5_000 }); // delayMs respects AbortSignal
+  const api = createFetch({ fetch: mock.fetch, baseUrl: "https://api.test", timeout: 50, retry: false });
+  await expect(api("/slow")).rejects.toMatchObject({ name: "TimeoutError" });
+});
+```
+
+---
+
+## LLM streaming (SSE)
+
+```js
+import { readSSE } from "@boy-offi9-inc/reqkit";
+
+const res = await fetch("https://api.example.com/v1/chat", {
+  method: "POST",
+  headers: { "content-type": "application/json", accept: "text/event-stream" },
+  body: JSON.stringify({ prompt: "Hello", stream: true }),
+  signal, // abort → the stream is cancelled and the connection released
+});
+
+let text = "";
+for await (const { data } of readSSE(res, { signal })) {
+  if (data === "[DONE]") break;
+  text += JSON.parse(data).token;
+  render(text);
+}
+```
+
+Want the request itself to be retried, timed out and rate limited? Make it through `createFetch` instead — it returns the same `Response`, so `readSSE(res)` works unchanged.