@boy-offi9-inc/reqkit 0.3.0 → 0.5.0

package/README.md

@@ -48,6 +48,30 @@ const pages = await limit.map(urls, (url) =>
   )
 );
 ```
+---
+
+## 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".
+
+## Works with what you already use
+
+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).
+
+## Runtime support
+
+| 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>
+```
 
 ---
 
@@ -63,6 +87,12 @@ const pages = await limit.map(urls, (url) =>
 | 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) |
 
 ---
@@ -280,6 +310,93 @@ 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`.
@@ -316,12 +433,40 @@ const admin = api.extend({ headers: { "x-role": "admin" } }); // merges over the
 | `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).
 
 ---
@@ -337,4 +482,4 @@ const admin = api.extend({ headers: { "x-role": "admin" } }); // merges over the
 
 ## 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), and the AWS Architecture Blog's "full jitter" backoff.
+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.