@boy-offi9-inc/reqkit 0.2.0 → 0.3.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,66 @@
 
 # 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 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:
 
-const data = await withRetry(() => fetch(url).then(r => r.json()));
+```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
+## 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) |
+| All of the above, wired up | [`createFetch`](#createfetchdefaults) |
+
+---
 
-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.
+## Why this exists
 
-**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).
+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.
 
-- **`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.
+**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:
 
-Zero dependencies. CJS + ESM. TypeScript types included.
+- **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 +92,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 +130,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...):
+
+```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)`
+### `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 +154,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 +196,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 +218,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 +263,78 @@ 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`).
+
+### `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 }` |
+| `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 |
+
+**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), and the AWS Architecture Blog's "full jitter" backoff.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@boy-offi9-inc/reqkit",
-  "version": "0.2.0",
-  "description": "Small, composable HTTP helper functions — retry with backoff, timeouts, normalized errors, safe JSON parsing, rate-limit-aware retry, and download progress. Not a client, works alongside fetch/axios/anything.",
+  "version": "0.3.0",
+  "description": "Small, composable HTTP helpers — retry with backoff and Retry-After, timeouts, normalized errors, safe JSON, download progress, dedupe, a concurrency limiter, and an opt-in createFetch. Not a client; works alongside fetch/axios/anything.",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
   "exports": {
@@ -32,7 +32,13 @@
     "retry-after",
     "download-progress",
     "error-normalization",
-    "utility"
+    "utility",
+    "limiter",
+    "concurrency",
+    "dedupe",
+    "http-client",
+    "fetch-wrapper",
+    "abort-signal"
   ],
   "author": "Boy Offi9",
   "license": "MIT",
@@ -54,6 +60,7 @@
     "src",
     "types",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "devDependencies": {

package/src/_http.js

@@ -0,0 +1,59 @@
+/**
+ * Parses a Retry-After header value into milliseconds. Per HTTP spec it's
+ * either an integer number of seconds, or an HTTP-date.
+ */
+function parseRetryAfter(headerValue) {
+  if (headerValue === null || headerValue === undefined) return null;
+  const value = String(headerValue).trim();
+  if (!value) return null;
+
+  // delta-seconds (spec says integer; tolerate "1.5" from sloppy servers)
+  if (/^\d+(\.\d+)?$/.test(value)) {
+    return Number(value) * 1000;
+  }
+
+  const dateMs = Date.parse(value);
+  if (!Number.isNaN(dateMs)) {
+    return Math.max(0, dateMs - Date.now());
+  }
+
+  return null;
+}
+
+/**
+ * Reads a wait time from common rate-limit headers, trying Retry-After first,
+ * then falling back to X-RateLimit-Reset (epoch seconds or ms) if present.
+ */
+function getWaitMsFromHeaders(headers) {
+  if (!headers || typeof headers.get !== "function") return null;
+
+  const retryAfter = parseRetryAfter(headers.get("retry-after"));
+  if (retryAfter !== null) return retryAfter;
+
+  const resetHeader = headers.get("x-ratelimit-reset") || headers.get("x-rate-limit-reset");
+  if (resetHeader) {
+    const resetValue = Number(resetHeader);
+    if (!Number.isNaN(resetValue)) {
+      // Could be epoch seconds or epoch ms — treat values below a
+      // year-2100-in-seconds threshold as seconds.
+      const resetMs = resetValue > 4102444800 ? resetValue : resetValue * 1000;
+      return Math.max(0, resetMs - Date.now());
+    }
+  }
+
+  return null;
+}
+
+async function discardBody(response) {
+  // An unread body keeps the underlying connection busy; cancel it before
+  // we sit through a backoff and fire the next request.
+  try {
+    if (response.body && typeof response.body.cancel === "function" && !response.bodyUsed) {
+      await response.body.cancel();
+    }
+  } catch {
+    // locked / already consumed / not a web stream — safe to ignore
+  }
+}
+
+module.exports = { parseRetryAfter, getWaitMsFromHeaders, discardBody };

package/src/createFetch.js

@@ -0,0 +1,218 @@
+const { withRetry, RetryAbortedError } = require("./withRetry");
+const { withTimeout } = require("./withTimeout");
+const { withDedupe } = require("./withDedupe");
+const { buildQuery } = require("./buildQuery");
+const { parseJsonSafe } = require("./parseJsonSafe");
+const { normalizeError } = require("./normalizeError");
+
+const DEFAULT_RETRY_STATUS_CODES = [408, 425, 429, 500, 502, 503, 504];
+// Safe to repeat without side effects. POST/PATCH are deliberately absent.
+const DEFAULT_RETRY_METHODS = ["GET", "HEAD", "OPTIONS", "PUT", "DELETE"];
+
+class HTTPError extends Error {
+  constructor(response, request) {
+    const statusText = response.statusText ? ` ${response.statusText}` : "";
+    super(`Request failed with status ${response.status}${statusText}: ${request.method} ${request.url}`);
+    this.name = "HTTPError";
+    this.status = response.status;
+    this.statusText = response.statusText || "";
+    this.response = response;
+    this.url = request.url;
+    this.method = request.method;
+  }
+}
+
+function isAbsoluteUrl(url) {
+  return /^[a-z][a-z0-9+.-]*:/i.test(url);
+}
+
+function joinUrl(baseUrl, url, query) {
+  let full = String(url);
+  if (baseUrl && !isAbsoluteUrl(full)) {
+    full = `${String(baseUrl).replace(/\/+$/, "")}/${full.replace(/^\/+/, "")}`;
+  }
+  const qs = query ? buildQuery(query) : "";
+  if (qs) full += (full.includes("?") ? "&" : "?") + qs;
+  return full;
+}
+
+async function resolveHeaders(source) {
+  const value = typeof source === "function" ? await source() : source;
+  return new Headers(value || undefined);
+}
+
+function mergeHeaders(...headerSets) {
+  const out = new Headers();
+  for (const set of headerSets) {
+    set.forEach((value, key) => out.set(key, value));
+  }
+  return out;
+}
+
+function isStreamBody(body) {
+  return Boolean(body) && typeof body === "object" && typeof body.getReader === "function";
+}
+
+function mergeDefaults(base, extra) {
+  const headersOf = (d) => d.headers;
+  const merged = { ...base, ...extra };
+
+  if (base.headers || extra.headers) {
+    merged.headers = async () => {
+      const a = await resolveHeaders(headersOf(base));
+      const b = await resolveHeaders(headersOf(extra));
+      return mergeHeaders(a, b);
+    };
+  }
+  if (base.retry !== false && extra.retry !== false && (base.retry || extra.retry)) {
+    merged.retry = { ...base.retry, ...extra.retry };
+  }
+  return merged;
+}
+
+/**
+ * Builds a fetch-like function from the other reqkit pieces — only if you
+ * want that. It's still plain `fetch` underneath: you get a standard
+ * `Response` back, and `fetch` itself stays swappable.
+ *
+ * What you get on top of fetch:
+ *  - `baseUrl`, `query` (via buildQuery), `json` request bodies
+ *  - default headers (an object, or a function for tokens that change)
+ *  - per-attempt `timeout` (withTimeout) and external `signal`
+ *  - retries (withRetry) on network errors/timeouts and retryable statuses,
+ *    honoring Retry-After; only for idempotent methods unless you opt in
+ *  - concurrent GET de-duplication (withDedupe)
+ *  - `HTTPError` on non-2xx (turn off with `throwHttpErrors: false`)
+ *  - `onRequest` / `onResponse` hooks
+ *
+ * @param {object} [defaults]
+ * @param {string} [defaults.baseUrl]
+ * @param {HeadersInit | (() => HeadersInit | Promise<HeadersInit>)} [defaults.headers]
+ * @param {number | false} [defaults.timeout=30000] - per attempt, ms
+ * @param {false | object} [defaults.retry] - false disables. Options:
+ *   `retries`(2), `statusCodes`, `methods`, `baseDelayMs`, `maxDelayMs`,
+ *   `factor`, `jitter`, `maxRetryTime`, `onRetry`, `calculateDelay`
+ * @param {boolean} [defaults.dedupe=false] - merge identical concurrent GET/HEAD calls
+ * @param {boolean} [defaults.throwHttpErrors=true]
+ * @param {typeof fetch} [defaults.fetch=globalThis.fetch]
+ * @param {(ctx: {url: string, init: object}) => void | Promise<void>} [defaults.onRequest] -
+ *   runs once per call; may mutate ctx.url / ctx.init (e.g. add a header)
+ * @param {(ctx: {url: string, init: object, response: Response}) => void | Promise<void>} [defaults.onResponse]
+ */
+function createFetch(defaults = {}) {
+  const {
+    baseUrl,
+    headers: defaultHeaders,
+    timeout: defaultTimeout = 30000,
+    retry: defaultRetry = {},
+    dedupe = false,
+    throwHttpErrors: defaultThrow = true,
+    fetch: customFetch,
+    onRequest,
+    onResponse,
+  } = defaults;
+
+  const doFetch = (...args) => (customFetch || globalThis.fetch)(...args);
+
+  // Shared in-flight GETs. Every caller gets its own clone of the response so
+  // body reads don't fight each other.
+  const sharedFetch = withDedupe((key, url, init) => doFetch(url, init), { keyFn: (key) => key });
+
+  async function request(input, init = {}) {
+    const {
+      query,
+      json,
+      timeout = defaultTimeout,
+      retry: retryOpt,
+      throwHttpErrors = defaultThrow,
+      signal,
+      headers: initHeaders,
+      ...fetchInit
+    } = init;
+
+    const method = String(fetchInit.method || "GET").toUpperCase();
+    const headers = mergeHeaders(await resolveHeaders(defaultHeaders), new Headers(initHeaders || undefined));
+
+    let body = fetchInit.body;
+    if (json !== undefined) {
+      body = JSON.stringify(json);
+      if (!headers.has("content-type")) headers.set("content-type", "application/json");
+    }
+
+    const ctx = { url: joinUrl(baseUrl, input, query), init: { ...fetchInit, method, headers, body } };
+    if (onRequest) await onRequest(ctx);
+    const finalHeaders = ctx.init.headers instanceof Headers ? ctx.init.headers : new Headers(ctx.init.headers);
+    const finalMethod = String(ctx.init.method || method).toUpperCase();
+
+    // --- retry policy ------------------------------------------------------
+    const retryCfg = retryOpt === false || defaultRetry === false ? false : { ...defaultRetry, ...retryOpt };
+    const methods = (retryCfg && retryCfg.methods) || DEFAULT_RETRY_METHODS;
+    const hasIdempotencyKey = finalHeaders.has("idempotency-key");
+    const canRetry =
+      retryCfg !== false &&
+      !isStreamBody(ctx.init.body) && // a consumed stream can't be replayed
+      (methods.map((m) => m.toUpperCase()).includes(finalMethod) || hasIdempotencyKey);
+
+    const attemptOnce = () =>
+      withTimeout(
+        (attemptSignal) => {
+          const attemptInit = { ...ctx.init, method: finalMethod, headers: finalHeaders, signal: attemptSignal };
+          const useDedupe = dedupe && !signal && !ctx.init.body && (finalMethod === "GET" || finalMethod === "HEAD");
+          if (!useDedupe) return doFetch(ctx.url, attemptInit);
+          // No per-attempt signal on a shared request: aborting one caller
+          // must never cancel everyone else's.
+          // It still gets its own timeout so a hung server can't leak the request.
+          const sharedInit = { ...attemptInit, signal: timeout === false ? undefined : AbortSignal.timeout(timeout) };
+          const key = `${finalMethod} ${ctx.url} ${JSON.stringify([...finalHeaders.entries()].sort())}`;
+          return sharedFetch(key, ctx.url, sharedInit).then((res) => res.clone());
+        },
+        timeout === false ? Infinity : timeout,
+        { signal }
+      );
+
+    const { statusCodes, methods: _methods, retries = 2, shouldRetry: customShouldRetry, ...retryRest } = retryCfg || {};
+
+    let response;
+    try {
+      response = canRetry
+        ? await withRetry(attemptOnce, {
+            ...retryRest,
+            retries,
+            retryStatusCodes: statusCodes || DEFAULT_RETRY_STATUS_CODES,
+            shouldRetry:
+              customShouldRetry ||
+              ((err) => {
+                const n = normalizeError(err);
+                return n.isNetworkError || n.isTimeout;
+              }),
+            signal,
+          })
+        : await attemptOnce();
+    } catch (err) {
+      // Present a user abort as the plain AbortError they caused, not as retry internals.
+      if (err instanceof RetryAbortedError && signal && signal.aborted) throw signal.reason ?? err;
+      throw err;
+    }
+
+    if (onResponse) await onResponse({ url: ctx.url, init: ctx.init, response });
+    if (throwHttpErrors && !response.ok) {
+      throw new HTTPError(response, { method: finalMethod, url: ctx.url });
+    }
+    return response;
+  }
+
+  /** Like `request`, but resolves to the parsed JSON body (null for an empty body). */
+  request.json = async (input, init) => {
+    const response = await request(input, init);
+    const { data, error } = await parseJsonSafe(response);
+    if (error) throw error;
+    return data;
+  };
+
+  /** A new fetch with these defaults merged over the current ones (headers and retry are merged, the rest replaced). */
+  request.extend = (overrides = {}) => createFetch(mergeDefaults(defaults, overrides));
+
+  return request;
+}
+
+module.exports = { createFetch, HTTPError };

package/src/createLimiter.js

@@ -0,0 +1,55 @@
+/**
+ * Creates a concurrency limiter: at most `concurrency` calls run at once,
+ * the rest wait in a FIFO queue. Handy for "download these 200 files, 4 at a
+ * time" without pulling in a queue library. (Same idea as p-limit.)
+ *
+ * ```js
+ * const limit = createLimiter(4);
+ * const bytes = await Promise.all(urls.map((u) => limit(() => download(u))));
+ * // or: await limit.map(urls, (u) => download(u));
+ * ```
+ *
+ * @param {number} [concurrency=Infinity] - integer >= 1, or Infinity
+ */
+function createLimiter(concurrency = Infinity) {
+  if (concurrency !== Infinity && !(Number.isInteger(concurrency) && concurrency >= 1)) {
+    throw new TypeError("createLimiter: `concurrency` must be an integer >= 1 (or Infinity)");
+  }
+
+  const queue = [];
+  let active = 0;
+
+  function next() {
+    while (active < concurrency && queue.length > 0) {
+      active++;
+      queue.shift()();
+    }
+  }
+
+  function limit(fn, ...args) {
+    return new Promise((resolve, reject) => {
+      queue.push(() => {
+        Promise.resolve()
+          .then(() => fn(...args))
+          .then(resolve, reject)
+          .finally(() => {
+            active--;
+            next();
+          });
+      });
+      next();
+    });
+  }
+
+  Object.defineProperties(limit, {
+    activeCount: { get: () => active },
+    pendingCount: { get: () => queue.length },
+  });
+
+  /** Runs `fn(item, index)` for every item through the limiter. Results keep input order. */
+  limit.map = (items, fn) => Promise.all(Array.from(items, (item, i) => limit(fn, item, i)));
+
+  return limit;
+}
+
+module.exports = { createLimiter };

package/src/index.js

@@ -1,4 +1,4 @@
-const { withRetry, RetryAbortedError } = require("./withRetry");
+const { withRetry, RetryAbortedError, StopRetry } = require("./withRetry");
 const { withTimeout, TimeoutError } = require("./withTimeout");
 const { normalizeError } = require("./normalizeError");
 const { parseJsonSafe } = require("./parseJsonSafe");
@@ -6,10 +6,13 @@ const { buildQuery } = require("./buildQuery");
 const { retryAfterAware, parseRetryAfter, getWaitMsFromHeaders } = require("./retryAfterAware");
 const { withProgress, BodyTooLargeError } = require("./withProgress");
 const { withDedupe } = require("./withDedupe");
+const { createLimiter } = require("./createLimiter");
+const { createFetch, HTTPError } = require("./createFetch");
 
 module.exports = {
   withRetry,
   RetryAbortedError,
+  StopRetry,
   withTimeout,
   TimeoutError,
   normalizeError,
@@ -21,4 +24,7 @@ module.exports = {
   withProgress,
   BodyTooLargeError,
   withDedupe,
+  createLimiter,
+  createFetch,
+  HTTPError,
 };

package/src/index.mjs

@@ -3,6 +3,7 @@ import reqkit from "./index.js";
 export const {
   withRetry,
   RetryAbortedError,
+  StopRetry,
   withTimeout,
   TimeoutError,
   normalizeError,
@@ -14,6 +15,9 @@ export const {
   withProgress,
   BodyTooLargeError,
   withDedupe,
+  createLimiter,
+  createFetch,
+  HTTPError,
 } = reqkit;
 
 export default reqkit;

package/src/retryAfterAware.js

@@ -1,75 +1,23 @@
-const { RetryAbortedError, sleep } = require("./_sleep");
+const { withRetry } = require("./withRetry");
 const { normalizeError } = require("./normalizeError");
-
-/**
- * Parses a Retry-After header value into milliseconds. Per HTTP spec it's
- * either an integer number of seconds, or an HTTP-date.
- */
-function parseRetryAfter(headerValue) {
-  if (headerValue === null || headerValue === undefined) return null;
-  const value = String(headerValue).trim();
-  if (!value) return null;
-
-  // delta-seconds (spec says integer; tolerate "1.5" from sloppy servers)
-  if (/^\d+(\.\d+)?$/.test(value)) {
-    return Number(value) * 1000;
-  }
-
-  const dateMs = Date.parse(value);
-  if (!Number.isNaN(dateMs)) {
-    return Math.max(0, dateMs - Date.now());
-  }
-
-  return null;
-}
-
-/**
- * Reads a wait time from common rate-limit headers, trying Retry-After first,
- * then falling back to X-RateLimit-Reset (epoch seconds or ms) if present.
- */
-function getWaitMsFromHeaders(headers) {
-  if (!headers || typeof headers.get !== "function") return null;
-
-  const retryAfter = parseRetryAfter(headers.get("retry-after"));
-  if (retryAfter !== null) return retryAfter;
-
-  const resetHeader = headers.get("x-ratelimit-reset") || headers.get("x-rate-limit-reset");
-  if (resetHeader) {
-    const resetValue = Number(resetHeader);
-    if (!Number.isNaN(resetValue)) {
-      // Could be epoch seconds or epoch ms — treat values below a
-      // year-2100-in-seconds threshold as seconds.
-      const resetMs = resetValue > 4102444800 ? resetValue : resetValue * 1000;
-      return Math.max(0, resetMs - Date.now());
-    }
-  }
-
-  return null;
-}
+const { parseRetryAfter, getWaitMsFromHeaders } = require("./_http");
 
 function defaultShouldRetryError(err) {
   const normalized = normalizeError(err);
   return normalized.isNetworkError || normalized.isTimeout;
 }
 
-async function discardBody(response) {
-  // An unread body keeps the underlying connection busy; cancel it before
-  // we sit through a backoff and fire the next request.
-  try {
-    if (response.body && typeof response.body.cancel === "function" && !response.bodyUsed) {
-      await response.body.cancel();
-    }
-  } catch {
-    // locked / already consumed / not a web stream — safe to ignore
-  }
-}
-
 /**
  * Retries a fetch-like call, honoring Retry-After / X-RateLimit-Reset
  * headers on 429/503 responses instead of blind exponential backoff — most
  * generic retry libraries treat rate-limit responses like any other failure
  * and ignore the header the server is explicitly giving you.
  *
+ * This is a thin preset over `withRetry` (retryStatusCodes + Retry-After,
+ * no jitter, network errors/timeouts only for thrown errors). Reach for
+ * `withRetry` directly when you need jitter, `maxRetryTime`, `StopRetry`,
+ * `calculateDelay`, ...
+ *
  * Also retries thrown network errors / timeouts (see `shouldRetryError`),
  * and the whole loop — including any backoff wait — can be cancelled with
  * `signal`. The body of each response that gets retried is cancelled so the
@@ -92,7 +40,7 @@ async function discardBody(response) {
  * @param {AbortSignal} [opts.signal] - cancels the retry loop, throwing
  *   RetryAbortedError
  */
-async function retryAfterAware(fn, opts = {}) {
+function retryAfterAware(fn, opts = {}) {
   const {
     retries = 3,
     retryStatusCodes = [429, 503],
@@ -104,34 +52,24 @@ async function retryAfterAware(fn, opts = {}) {
     signal,
   } = opts;
 
-  let lastErr;
-  for (let attempt = 0; attempt <= retries; attempt++) {
-    if (signal?.aborted) throw new RetryAbortedError(lastErr);
-
-    let response;
-    try {
-      response = await fn(attempt);
-    } catch (err) {
-      lastErr = err;
-      if (attempt === retries || !shouldRetryError(err, attempt)) throw err;
-
-      const waitMs = Math.min(fallbackDelayMs * 2 ** attempt, maxDelayMs);
-      if (onRetryError) onRetryError(err, waitMs, attempt);
-      await sleep(waitMs, signal, err);
-      continue;
-    }
-
-    if (!retryStatusCodes.includes(response.status) || attempt === retries) {
-      return response;
-    }
-
-    const headerWaitMs = getWaitMsFromHeaders(response.headers);
-    const waitMs = Math.min(headerWaitMs ?? fallbackDelayMs * 2 ** attempt, maxDelayMs);
-
-    await discardBody(response);
-    if (onRetry) onRetry(response.status, waitMs, attempt);
-    await sleep(waitMs, signal);
-  }
+  return withRetry(fn, {
+    retries,
+    retryStatusCodes,
+    baseDelayMs: fallbackDelayMs,
+    maxDelayMs,
+    maxRetryAfterMs: maxDelayMs,
+    factor: 2,
+    jitter: 0,
+    shouldRetry: shouldRetryError,
+    onRetry: (err, attempt, waitMs, ctx) => {
+      if (ctx.reason === "result") {
+        if (onRetry) onRetry(ctx.status, waitMs, attempt);
+      } else if (onRetryError) {
+        onRetryError(err, waitMs, attempt);
+      }
+    },
+    signal,
+  });
 }
 
 module.exports = { retryAfterAware, parseRetryAfter, getWaitMsFromHeaders };

package/src/withRetry.js

@@ -1,58 +1,147 @@
 const { RetryAbortedError, sleep } = require("./_sleep");
+const { getWaitMsFromHeaders, discardBody } = require("./_http");
 
 function defaultShouldRetry(err) {
-  // Retry network-level failures by default. HTTP status handling is the
-  // caller's job (they know what "failure" means for their response shape) —
-  // see retryAfterAware.js for a version that understands status codes.
+  // Retry thrown errors except deliberate aborts. Narrow it with `shouldRetry`
+  // (e.g. network errors only). HTTP *statuses* aren't errors with fetch, so
+  // opt in with `retryStatusCodes` / `shouldRetryResult`.
   return Boolean(err) && err.name !== "AbortError";
 }
 
 /**
- * Retries an async function with exponential backoff + jitter.
+ * Throw this from inside `fn` to stop retrying immediately. If you pass an
+ * Error, that exact error is what withRetry rethrows; with a string, the
+ * StopRetry itself is thrown. (Same idea as p-retry's AbortError.)
+ */
+class StopRetry extends Error {
+  constructor(reasonOrMessage) {
+    const isError = reasonOrMessage instanceof Error;
+    super(isError ? reasonOrMessage.message : String(reasonOrMessage ?? "Retrying was stopped"));
+    this.name = "StopRetry";
+    this.original = isError ? reasonOrMessage : null;
+  }
+}
+
+/**
+ * Retries an async function with exponential backoff + jitter. Retries on
+ * thrown errors, and — opt-in — on *results* too (HTTP status codes, or any
+ * predicate), honoring Retry-After / X-RateLimit-Reset when the result has
+ * headers.
  *
  * @param {(attempt: number) => Promise<any>} fn
  * @param {object} [opts]
- * @param {number} [opts.retries=3] - max retry attempts after the first try
+ * @param {number} [opts.retries=3] - max retry attempts after the first try (Infinity is fine with maxRetryTime)
  * @param {number} [opts.baseDelayMs=300] - initial delay
- * @param {number} [opts.maxDelayMs=10000] - delay ceiling
- * @param {(err: any, attempt: number) => boolean} [opts.shouldRetry]
- * @param {(err: any, attempt: number, delayMs: number) => void} [opts.onRetry]
+ * @param {number} [opts.maxDelayMs=10000] - backoff ceiling
+ * @param {number} [opts.factor=2] - backoff multiplier
+ * @param {number|"full"} [opts.jitter=0.2] - fraction of extra random delay
+ *   added on top (0 disables); "full" picks uniformly in [0, delay] — the
+ *   AWS "full jitter" strategy, best when many clients retry at once
+ * @param {number} [opts.maxRetryTime=Infinity] - total time budget in ms
+ *   across all attempts and waits; once the next wait would blow it, stop
+ *   and surface the last error/result
+ * @param {(err: any, attempt: number) => boolean} [opts.shouldRetry] - for thrown errors
+ * @param {number[]} [opts.retryStatusCodes=[]] - retry when the result's `.status` is in this list
+ * @param {(result: any, attempt: number) => boolean} [opts.shouldRetryResult] - retry on any result predicate
+ * @param {boolean} [opts.respectRetryAfter=true] - use Retry-After/X-RateLimit-Reset from `result.headers`
+ * @param {number} [opts.maxRetryAfterMs=60000] - cap on a header-provided wait
+ * @param {(info: {attempt: number, error: any, result: any, delayMs: number}) => number|false} [opts.calculateDelay]
+ *   - override the wait; return a number of ms, or false to stop retrying
+ * @param {(err: any, attempt: number, delayMs: number, ctx: {reason: "error"|"result", result?: any, status?: number}) => void} [opts.onRetry]
+ *   - `err` is undefined when the retry was triggered by a result
  * @param {AbortSignal} [opts.signal] - cancels the whole retry loop,
- *   including any pending backoff wait, throwing RetryAbortedError. This is
- *   separate from a per-call AbortSignal you might pass into `fn` yourself —
- *   this one governs whether *another attempt starts at all*.
+ *   including any pending backoff wait, throwing RetryAbortedError (with the
+ *   last failure as `cause`). Separate from a per-call signal you pass into
+ *   `fn` yourself — this one governs whether *another attempt starts at all*.
  */
 async function withRetry(fn, opts = {}) {
   const {
     retries = 3,
     baseDelayMs = 300,
     maxDelayMs = 10000,
+    factor = 2,
+    jitter = 0.2,
+    maxRetryTime = Infinity,
     shouldRetry = defaultShouldRetry,
+    retryStatusCodes = [],
+    shouldRetryResult,
+    respectRetryAfter = true,
+    maxRetryAfterMs = 60000,
+    calculateDelay,
     onRetry,
     signal,
   } = opts;
 
+  const startedAt = Date.now();
+
+  function backoff(attempt) {
+    const exponential = Math.min(baseDelayMs * factor ** attempt, maxDelayMs);
+    if (jitter === "full") return Math.round(Math.random() * exponential);
+    const extra = Math.random() * exponential * (Number(jitter) || 0);
+    return Math.round(exponential + extra);
+  }
+
+  // Returns the wait in ms, or null if retrying should stop (custom
+  // calculateDelay said so, or the time budget would be exceeded).
+  function planWait(defaultMs, attempt, error, result) {
+    let waitMs = defaultMs;
+    if (calculateDelay) {
+      const custom = calculateDelay({ attempt, error, result, delayMs: defaultMs });
+      if (custom === false || custom === null || custom === undefined) return null;
+      waitMs = Math.max(0, Number(custom) || 0);
+    }
+    if (Date.now() - startedAt + waitMs > maxRetryTime) return null;
+    return waitMs;
+  }
+
+  function wantsResultRetry(result, attempt) {
+    if (
+      retryStatusCodes.length > 0 &&
+      result &&
+      typeof result.status === "number" &&
+      retryStatusCodes.includes(result.status)
+    ) {
+      return true;
+    }
+    return shouldRetryResult ? Boolean(shouldRetryResult(result, attempt)) : false;
+  }
+
   let lastErr;
-  for (let attempt = 0; attempt <= retries; attempt++) {
+  for (let attempt = 0; ; attempt++) {
     if (signal?.aborted) {
       throw new RetryAbortedError(lastErr);
     }
+
+    let result;
     try {
-      return await fn(attempt);
+      result = await fn(attempt);
     } catch (err) {
+      if (err instanceof StopRetry) throw err.original ?? err;
       lastErr = err;
-      const isLastAttempt = attempt === retries;
-      if (isLastAttempt || !shouldRetry(err, attempt)) {
-        throw err;
-      }
-      const exponential = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
-      const jitter = Math.random() * exponential * 0.2;
-      const waitMs = Math.round(exponential + jitter);
-      if (onRetry) onRetry(err, attempt, waitMs);
+      if (attempt >= retries || !shouldRetry(err, attempt)) throw err;
+
+      const waitMs = planWait(backoff(attempt), attempt, err, undefined);
+      if (waitMs === null) throw err;
+
+      if (onRetry) onRetry(err, attempt, waitMs, { reason: "error" });
       await sleep(waitMs, signal, err);
+      continue;
     }
+
+    if (attempt >= retries || !wantsResultRetry(result, attempt)) return result;
+
+    let defaultMs = backoff(attempt);
+    if (respectRetryAfter) {
+      const headerMs = getWaitMsFromHeaders(result && result.headers);
+      if (headerMs !== null) defaultMs = Math.min(headerMs, maxRetryAfterMs);
+    }
+    const waitMs = planWait(defaultMs, attempt, undefined, result);
+    if (waitMs === null) return result;
+
+    await discardBody(result);
+    if (onRetry) onRetry(undefined, attempt, waitMs, { reason: "result", result, status: result && result.status });
+    await sleep(waitMs, signal);
   }
-  throw lastErr;
 }
 
-module.exports = { withRetry, RetryAbortedError };
+module.exports = { withRetry, RetryAbortedError, StopRetry };

package/src/withTimeout.js

@@ -7,34 +7,62 @@ class TimeoutError extends Error {
 }
 
 /**
- * Races an async function against a timeout. If `fn` accepts an AbortSignal
- * as its argument, it's passed one so the underlying request can actually be
- * cancelled (not just abandoned) — e.g. `withTimeout(signal => fetch(url, { signal }), 5000)`.
+ * Races an async function against a timeout. `fn` is handed an AbortSignal
+ * so the underlying request can actually be cancelled (not just abandoned) —
+ * e.g. `withTimeout(signal => fetch(url, { signal }), 5000)`.
+ *
+ * Pass your own `signal` to also cancel from the outside (user navigated
+ * away, shutdown...). That signal is linked into the one `fn` receives, and
+ * aborting it rejects with its reason even if `fn` ignores the signal.
+ * `ms: Infinity` disables the timer (handy to only link a signal).
  *
  * @param {(signal: AbortSignal) => Promise<any>} fn
  * @param {number} ms
+ * @param {object} [opts]
+ * @param {AbortSignal} [opts.signal] - external cancellation
  */
-async function withTimeout(fn, ms) {
+async function withTimeout(fn, ms, opts = {}) {
+  const { signal } = opts;
+
+  if (typeof ms !== "number" || Number.isNaN(ms) || ms < 0) {
+    throw new TypeError("withTimeout: `ms` must be a non-negative number (or Infinity)");
+  }
+  signal?.throwIfAborted?.();
+
   const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), ms);
+  let timedOut = false;
+
+  const timer =
+    ms === Infinity
+      ? null
+      : setTimeout(() => {
+          timedOut = true;
+          controller.abort(new TimeoutError(ms));
+        }, ms);
+
+  const onExternalAbort = () => controller.abort(signal.reason);
+  signal?.addEventListener("abort", onExternalAbort, { once: true });
 
-  const timeoutPromise = new Promise((_, reject) => {
-    controller.signal.addEventListener("abort", () => reject(new TimeoutError(ms)));
+  const guard = new Promise((_, reject) => {
+    controller.signal.addEventListener(
+      "abort",
+      () => reject(timedOut ? new TimeoutError(ms) : controller.signal.reason),
+      { once: true }
+    );
   });
 
   try {
-    return await Promise.race([fn(controller.signal), timeoutPromise]);
+    return await Promise.race([fn(controller.signal), guard]);
   } catch (err) {
     // If our timeout is what triggered the abort, always surface TimeoutError —
-    // regardless of whether fn's own rejection or our timeout promise "won"
-    // the race (that's a listener-registration-order detail callers shouldn't
-    // have to think about).
-    if (controller.signal.aborted) {
-      throw new TimeoutError(ms);
-    }
+    // regardless of whether fn's own rejection or our guard "won" the race
+    // (that's a listener-registration-order detail callers shouldn't have to
+    // think about).
+    if (timedOut) throw new TimeoutError(ms);
     throw err;
   } finally {
-    clearTimeout(timer);
+    if (timer) clearTimeout(timer);
+    signal?.removeEventListener("abort", onExternalAbort);
   }
 }
 

package/types/index.d.ts

@@ -1,12 +1,56 @@
+export interface RetryContext {
+  reason: "error" | "result";
+  /** The result that triggered the retry (reason "result"). */
+  result?: unknown;
+  /** The result's HTTP status (reason "result"). */
+  status?: number;
+}
+
+export interface CalculateDelayInfo {
+  attempt: number;
+  error: unknown;
+  result: unknown;
+  /** The delay reqkit would have used. */
+  delayMs: number;
+}
+
 export interface RetryOptions {
+  /** Max retries after the first try. Infinity is fine together with maxRetryTime. Default 3. */
   retries?: number;
+  /** Default 300. */
   baseDelayMs?: number;
+  /** Backoff ceiling. Default 10000. */
   maxDelayMs?: number;
+  /** Backoff multiplier. Default 2. */
+  factor?: number;
+  /** Extra random fraction (default 0.2), or "full" for uniform [0, delay]. */
+  jitter?: number | "full";
+  /** Total time budget across attempts and waits, in ms. */
+  maxRetryTime?: number;
+  /** For thrown errors. */
   shouldRetry?: (err: unknown, attempt: number) => boolean;
-  onRetry?: (err: unknown, attempt: number, delayMs: number) => void;
+  /** Retry when the result's `.status` is in this list. */
+  retryStatusCodes?: number[];
+  /** Retry on any result predicate. */
+  shouldRetryResult?: (result: any, attempt: number) => boolean;
+  /** Use Retry-After / X-RateLimit-Reset from `result.headers`. Default true. */
+  respectRetryAfter?: boolean;
+  /** Cap on a header-provided wait. Default 60000. */
+  maxRetryAfterMs?: number;
+  /** Return ms to wait, or false to stop retrying. */
+  calculateDelay?: (info: CalculateDelayInfo) => number | false | null | undefined;
+  /** `err` is undefined when a result (not an error) triggered the retry. */
+  onRetry?: (err: unknown, attempt: number, delayMs: number, ctx: RetryContext) => void;
   signal?: AbortSignal;
 }
 
+/** Throw inside `fn` to stop retrying. An Error argument is rethrown as-is. */
+export class StopRetry extends Error {
+  name: "StopRetry";
+  original: Error | null;
+  constructor(reasonOrMessage?: unknown);
+}
+
 export class RetryAbortedError extends Error {
   name: "RetryAbortedError";
   /** The last failure before the loop was aborted, if there was one. */
@@ -20,7 +64,17 @@ export class TimeoutError extends Error {
   constructor(ms: number);
 }
 
-export function withTimeout<T>(fn: (signal: AbortSignal) => Promise<T>, ms: number): Promise<T>;
+export interface TimeoutOptions {
+  /** External cancellation, linked into the signal `fn` receives. */
+  signal?: AbortSignal;
+}
+
+/** `ms` may be Infinity to disable the timer (only link `signal`). */
+export function withTimeout<T>(
+  fn: (signal: AbortSignal) => Promise<T>,
+  ms: number,
+  opts?: TimeoutOptions
+): Promise<T>;
 
 export interface NormalizedError {
   message: string;
@@ -99,3 +153,81 @@ export function withDedupe<Fn extends (...args: any[]) => Promise<any>>(
   fn: Fn,
   opts?: DedupeOptions
 ): Fn;
+
+export interface Limiter {
+  <A extends any[], R>(fn: (...args: A) => R | Promise<R>, ...args: A): Promise<R>;
+  readonly activeCount: number;
+  readonly pendingCount: number;
+  /** Runs fn(item, index) for each item through the limiter; keeps input order. */
+  map<T, R>(items: Iterable<T>, fn: (item: T, index: number) => R | Promise<R>): Promise<R[]>;
+}
+
+export function createLimiter(concurrency?: number): Limiter;
+
+export class HTTPError extends Error {
+  name: "HTTPError";
+  status: number;
+  statusText: string;
+  response: Response;
+  url: string;
+  method: string;
+  constructor(response: Response, request: { method: string; url: string });
+}
+
+export interface CreateFetchRetryOptions {
+  /** Default 2. */
+  retries?: number;
+  /** Default [408, 425, 429, 500, 502, 503, 504]. */
+  statusCodes?: number[];
+  /** Methods that may be retried. Default GET, HEAD, OPTIONS, PUT, DELETE. */
+  methods?: string[];
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  factor?: number;
+  jitter?: number | "full";
+  maxRetryTime?: number;
+  shouldRetry?: (err: unknown, attempt: number) => boolean;
+  calculateDelay?: RetryOptions["calculateDelay"];
+  onRetry?: RetryOptions["onRetry"];
+}
+
+export interface FetchHookContext {
+  url: string;
+  init: RequestInit & { headers: Headers };
+}
+
+export interface CreateFetchDefaults {
+  baseUrl?: string;
+  headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+  /** Per attempt, in ms. false disables. Default 30000. */
+  timeout?: number | false;
+  /** false disables retrying. */
+  retry?: false | CreateFetchRetryOptions;
+  /** Merge identical concurrent GET/HEAD calls. Default false. */
+  dedupe?: boolean;
+  /** Throw HTTPError on non-2xx. Default true. */
+  throwHttpErrors?: boolean;
+  fetch?: typeof fetch;
+  onRequest?: (ctx: FetchHookContext) => void | Promise<void>;
+  onResponse?: (ctx: FetchHookContext & { response: Response }) => void | Promise<void>;
+}
+
+export interface ReqkitRequestInit extends Omit<RequestInit, "headers"> {
+  headers?: HeadersInit;
+  query?: Record<string, unknown>;
+  /** Serialized as the body with a JSON content-type. */
+  json?: unknown;
+  timeout?: number | false;
+  retry?: false | CreateFetchRetryOptions;
+  throwHttpErrors?: boolean;
+}
+
+export interface ReqkitFetch {
+  (input: string, init?: ReqkitRequestInit): Promise<Response>;
+  /** Resolves to the parsed JSON body (null for an empty body). */
+  json<T = unknown>(input: string, init?: ReqkitRequestInit): Promise<T>;
+  /** New instance with these defaults merged over the current ones. */
+  extend(overrides?: CreateFetchDefaults): ReqkitFetch;
+}
+
+export function createFetch(defaults?: CreateFetchDefaults): ReqkitFetch;