\n\n# reqkit\n\nSmall, 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.\n\n```js\nconst { withRetry, normalizeError } = require(\"@boy-offi9-inc/reqkit\");\n\nconst data = await withRetry(() => fetch(url).then(r => r.json()));\n```\n\n---\n\n## Why this exists\n\nMost 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.\n\n**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).\n\n- **`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.\n- **`withProgress`** — progress callback for any streamed response body (downloads, large payloads, anything), not tied to a specific HTTP client.\n- **`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.\n\nZero dependencies. CJS + ESM. TypeScript types included.\n\n---\n\n## Install\n\n```bash\nnpm install @boy-offi9-inc/reqkit\n```\n\n---\n\n## API\n\n### `withRetry(fn, opts?)`\n\nRetries an async function with exponential backoff + jitter.\n\n```js\nconst data = await withRetry(\n () => fetch(url).then(r => r.json()),\n { retries: 3, baseDelayMs: 300, onRetry: (err, attempt, delayMs) => console.log(`retry ${attempt} in ${delayMs}ms`) }\n);\n```\n\n| Option | Default | Description |\n|---|---|---|\n| `retries` | `3` | max retry attempts after the first try |\n| `baseDelayMs` | `300` | initial delay |\n| `maxDelayMs` | `10000` | delay ceiling |\n| `shouldRetry` | retries anything but AbortError | `(err, attempt) => boolean` |\n| `onRetry` | — | `(err, attempt, delayMs) => void` |\n| `signal` | — | `AbortSignal` — cancels the whole retry loop, including any pending backoff wait, throwing `RetryAbortedError` |\n\n```js\n// Cancel a long retry/backoff sequence externally — e.g. the user navigated away\nconst controller = new AbortController();\nconst promise = withRetry(() => fetch(url), { retries: 5, signal: controller.signal });\ncontroller.abort(); // rejects with RetryAbortedError, even mid-backoff\n```\n\n### `withTimeout(fn, ms)`\n\nRaces an async function against a timeout, passing it an `AbortSignal` so the underlying request can actually be cancelled.\n\n```js\nconst data = await withTimeout(\n signal => fetch(url, { signal }).then(r => r.json()),\n 5000\n);\n// throws TimeoutError on timeout, regardless of whether fn cooperates with the signal\n```\n\n### `normalizeError(err)`\n\nOne consistent error shape regardless of source (fetch, axios, node http, generic):\n\n```js\nconst { message, status, code, isNetworkError, isTimeout } = normalizeError(err);\n```\n\nEvery field is always present (`null`/`false` when not applicable) — no existence checks needed.\n\n### `parseJsonSafe(input)`\n\nNever throws on malformed JSON. Accepts a `Response` or a raw string.\n\n```js\nconst { data, error } = await parseJsonSafe(response);\nif (error) { /* handle malformed JSON without a try/catch */ }\n```\n\n### `buildQuery(params)`\n\nMinimal query string builder — skips `null`/`undefined`, repeats the key for arrays, encodes everything.\n\n```js\nbuildQuery({ q: \"hello world\", tag: [\"a\", \"b\"] });\n// \"q=hello%20world&tag=a&tag=b\"\n```\n\nFor full parsing/nested-object support, use [`query-string`](https://www.npmjs.com/package/query-string) instead — this only covers the common flat-object case with zero dependencies.\n\n### `retryAfterAware(fn, opts?)`\n\nRetries a fetch-like call, honoring `Retry-After`/`X-RateLimit-Reset` headers on 429/503 instead of blind backoff.\n\n```js\nconst response = await retryAfterAware(\n () => fetch(url),\n { retries: 3, retryStatusCodes: [429, 503] }\n);\n```\n\n| Option | Default | Description |\n|---|---|---|\n| `retries` | `3` | |\n| `retryStatusCodes` | `[429, 503]` | |\n| `fallbackDelayMs` | `1000` | used when no usable header is present |\n| `maxDelayMs` | `60000` | |\n| `onRetry` | — | `(status, waitMs, attempt) => void` |\n\n### `withProgress(response, onProgress?)`\n\nReads a streamed `Response` body while reporting progress, returns the collected bytes as a `Uint8Array`.\n\n```js\nconst bytes = await withProgress(response, ({ loaded, total, percent }) => {\n console.log(`${percent ?? \"?\"}% (${loaded}/${total ?? \"?\"} bytes)`);\n});\n```\n\nWorks without `Content-Length` too — `total`/`percent` are just `null` in that case, `loaded` is still accurate. Falls back to a single-shot read (still calling `onProgress` once) if the response body is not a stream.\n\n### `withDedupe(fn, opts?)`\n\nCoalesces concurrent calls with the same arguments into a single in-flight call — every caller gets the same result, but the underlying request only fires once. Useful when several parts of a UI ask for the same resource around the same time.\n\n```js\nconst getUser = withDedupe((id) => fetch(`/api/users/${id}`).then(r => r.json()));\n\n// Only one network request goes out — both callers share it.\nconst [a, b] = await Promise.all([getUser(1), getUser(1)]);\n```\n\n| Option | Default | Notes |\n| --- | --- | --- |\n| `keyFn` | `(...args) => JSON.stringify(args)` | derives the dedupe key from call args |\n\nThis is deduplication of *concurrent* calls, not a cache — once a call settles (success or failure), the next call with the same key starts fresh.\n\n```js\n// Custom key when the default arg-based key isn't quite right\nconst fn = withDedupe((req) => doFetch(req), { keyFn: (req) => req.url });\n```\n\n---\n\n## Design notes\n\n- **Zero dependencies.** Nothing to audit, nothing to break underneath you.\n- **CJS + ESM.** `require()` and `import` both work.\n- **Composable, not a client.** Every function takes and returns plain values (`Response`, plain objects, `Uint8Array`) — nothing proprietary to learn.\n- **TypeScript types included**, hand-written (no build step to go wrong).\n","readmeFilename":"README.md"}
![\"reqkit](\"https://i.ibb.co/1f63mDTg/logo-wordmark.png\"){kind=logo}
\n \n![\"License:](\"https://img.shields.io/badge/License-MIT-yellow.svg\"){kind=icon}
\n ![\"Node](\"https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white\"){kind=icon}
![\"npm](\"https://img.shields.io/badge/npm-%40boy--offi9--inc%2Freqkit-CB3837?logo=npm&logoColor=white\"){kind=icon}
![\"Zero](\"https://img.shields.io/badge/dependencies-zero-brightgreen\"){kind=icon}
![\"CJS](\"https://img.shields.io/badge/module-CJS%20%2B%20ESM-blue\"){kind=icon}
![\"TypeScript](\"https://img.shields.io/badge/types-included-3178C6?logo=typescript&logoColor=white\"){kind=icon}