@boy-offi9-inc/reqkit 0.1.7 → 0.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Boy Offi9
+Copyright (c) 2026 Boy Offi9 Inc
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -76,6 +76,8 @@ 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.
+
 ### `withTimeout(fn, ms)`
 
 Races an async function against a timeout, passing it an `AbortSignal` so the underlying request can actually be cancelled.
@@ -93,9 +95,11 @@ const data = await withTimeout(
 One consistent error shape regardless of source (fetch, axios, node http, generic):
 
 ```js
-const { message, status, code, isNetworkError, isTimeout } = normalizeError(err);
+const { message, status, code, isNetworkError, isTimeout, isAborted } = normalizeError(err);
 ```
 
+Understands Node's `TypeError: fetch failed` (real code read from `err.cause`), browser `Failed to fetch`, undici timeouts, and axios. `isTimeout` is only for real timeouts; a deliberate `AbortController.abort()` sets `isAborted` instead.
+
 Every field is always present (`null`/`false` when not applicable) — no existence checks needed.
 
 ### `parseJsonSafe(input)`
@@ -116,6 +120,8 @@ buildQuery({ q: "hello world", tag: ["a", "b"] });
 // "q=hello%20world&tag=a&tag=b"
 ```
 
+`Date` values are serialized as ISO 8601. Nested objects throw a `TypeError` (flatten or `JSON.stringify` them first) instead of silently becoming `[object Object]`.
+
 For 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.
 
 ### `retryAfterAware(fn, opts?)`
@@ -136,6 +142,11 @@ const response = await retryAfterAware(
 | `fallbackDelayMs` | `1000` | used when no usable header is present |
 | `maxDelayMs` | `60000` | |
 | `onRetry` | — | `(status, waitMs, attempt) => void` |
+| `shouldRetryError` | network errors + timeouts | `(err, attempt) => boolean` — decides whether a *thrown* error is retried |
+| `onRetryError` | — | `(err, waitMs, attempt) => void` |
+| `signal` | — | `AbortSignal` — cancels the loop (even mid-wait), throwing `RetryAbortedError` |
+
+The body of every response that gets retried is cancelled so the connection is freed.
 
 ### `withProgress(response, onProgress?)`
 
@@ -147,7 +158,14 @@ const bytes = await withProgress(response, ({ loaded, total, percent }) => {
 });
 ```
 
-Works 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.
+Works without `Content-Length` too — `total`/`percent` are just `null` in that case, `loaded` is still accurate. They're also `null` when a `Content-Encoding` is applied (the header is the compressed size, but you receive decompressed bytes), and `percent` never exceeds 100. Falls back to a single-shot read (still calling `onProgress` once) if the response body is not a stream.
+
+```js
+const bytes = await withProgress(response, onProgress, {
+  maxBytes: 50 * 1024 * 1024, // throws BodyTooLargeError (code "EBODYTOOLARGE") past this
+  signal: controller.signal,  // abort the read
+});
+```
 
 ### `withDedupe(fn, opts?)`
 
@@ -164,6 +182,8 @@ const [a, b] = await Promise.all([getUser(1), getUser(1)]);
 | --- | --- | --- |
 | `keyFn` | `(...args) => JSON.stringify(args)` | derives the dedupe key from call args |
 
+Plain arguments are compared by value (object key order doesn't matter); anything else — `AbortSignal`s, `Response`s, class instances, functions — is compared by identity, so calls with different `AbortSignal`s are never merged. Note that merged callers share one promise, so aborting the request affects everyone waiting on it.
+
 This is deduplication of *concurrent* calls, not a cache — once a call settles (success or failure), the next call with the same key starts fresh.
 
 ```js

package/package.json

@@ -1,20 +1,26 @@
 {
   "name": "@boy-offi9-inc/reqkit",
-  "version": "0.1.7",
+  "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.",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
   "exports": {
     ".": {
-      "types": "./types/index.d.ts",
-      "require": "./src/index.js",
-      "import": "./src/index.mjs"
+      "import": {
+        "types": "./types/index.d.mts",
+        "default": "./src/index.mjs"
+      },
+      "require": {
+        "types": "./types/index.d.ts",
+        "default": "./src/index.js"
+      }
     },
     "./package.json": "./package.json"
   },
   "sideEffects": false,
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "typecheck": "tsc -p tsconfig.json"
   },
   "keywords": [
     "http",
@@ -30,6 +36,14 @@
   ],
   "author": "Boy Offi9",
   "license": "MIT",
+  "homepage": "https://github.com/boy-offi9-inc/reqkit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/boy-offi9-inc/reqkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/boy-offi9-inc/reqkit/issues"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -41,5 +55,8 @@
     "types",
     "README.md",
     "LICENSE"
-  ]
+  ],
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
 }

package/src/_sleep.js

@@ -0,0 +1,32 @@
+class RetryAbortedError extends Error {
+  constructor(cause) {
+    super("Retry loop was aborted");
+    this.name = "RetryAbortedError";
+    if (cause !== undefined) this.cause = cause;
+  }
+}
+
+/**
+ * Abortable sleep shared by withRetry and retryAfterAware. Rejects with
+ * RetryAbortedError (carrying `cause`, usually the last failure) if the
+ * signal aborts before or during the wait.
+ */
+function sleep(ms, signal, cause) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new RetryAbortedError(cause));
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new RetryAbortedError(cause));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+module.exports = { RetryAbortedError, sleep };

package/src/buildQuery.js

@@ -1,6 +1,23 @@
+function toParam(key, value) {
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) {
+      throw new TypeError(`buildQuery: value for "${key}" is an invalid Date`);
+    }
+    return value.toISOString();
+  }
+  if (typeof value === "object" || typeof value === "function" || typeof value === "symbol") {
+    throw new TypeError(
+      `buildQuery: value for "${key}" is not a primitive, Date or array of those — flatten it or JSON.stringify it first`
+    );
+  }
+  return String(value);
+}
+
 /**
  * Builds a query string from a params object. Skips null/undefined values,
- * repeats the key for arrays (`?tag=a&tag=b`), and encodes everything.
+ * repeats the key for arrays (`?tag=a&tag=b`), serializes Dates as ISO 8601,
+ * and encodes everything. Nested objects throw a TypeError instead of
+ * silently becoming "[object Object]".
  *
  * Deliberately minimal — for full query-string parsing/nested-object support,
  * reach for `query-string` (sindresorhus) instead. This just covers the
@@ -15,13 +32,10 @@ function buildQuery(params) {
   for (const [key, value] of Object.entries(params)) {
     if (value === null || value === undefined) continue;
 
-    if (Array.isArray(value)) {
-      for (const v of value) {
-        if (v === null || v === undefined) continue;
-        pairs.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(v))}`);
-      }
-    } else {
-      pairs.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+    const values = Array.isArray(value) ? value : [value];
+    for (const v of values) {
+      if (v === null || v === undefined) continue;
+      pairs.push(`${encodeURIComponent(key)}=${encodeURIComponent(toParam(key, v))}`);
     }
   }
 

package/src/index.js

@@ -4,7 +4,7 @@ const { normalizeError } = require("./normalizeError");
 const { parseJsonSafe } = require("./parseJsonSafe");
 const { buildQuery } = require("./buildQuery");
 const { retryAfterAware, parseRetryAfter, getWaitMsFromHeaders } = require("./retryAfterAware");
-const { withProgress } = require("./withProgress");
+const { withProgress, BodyTooLargeError } = require("./withProgress");
 const { withDedupe } = require("./withDedupe");
 
 module.exports = {
@@ -19,5 +19,6 @@ module.exports = {
   parseRetryAfter,
   getWaitMsFromHeaders,
   withProgress,
+  BodyTooLargeError,
   withDedupe,
 };

package/src/index.mjs

@@ -12,6 +12,7 @@ export const {
   parseRetryAfter,
   getWaitMsFromHeaders,
   withProgress,
+  BodyTooLargeError,
   withDedupe,
 } = reqkit;
 

package/src/normalizeError.js

@@ -1,79 +1,124 @@
 /**
- * Normalizes errors from fetch, axios, node's http/https, and generic
+ * Normalizes errors from fetch, axios, node's http/https, undici and generic
  * Error objects into one consistent shape:
- *   { message, status, code, isNetworkError, isTimeout, cause }
+ *   { message, status, code, isNetworkError, isTimeout, isAborted, cause }
  *
  * Every field is always present (null/false when not applicable) so callers
  * can destructure without existence checks.
+ *
+ * - `isTimeout` is true only for real timeouts (reqkit's TimeoutError,
+ *   AbortSignal.timeout(), ETIMEDOUT, undici timeouts) — not for a plain
+ *   user-initiated abort.
+ * - `isAborted` is true when the request was cancelled on purpose
+ *   (AbortController.abort(), axios cancel).
  */
-function normalizeError(err) {
-  const base = {
+
+function shape(err, overrides) {
+  return {
     message: "Unknown error",
     status: null,
     code: null,
     isNetworkError: false,
     isTimeout: false,
+    isAborted: false,
     cause: err,
+    ...overrides,
   };
+}
+
+// Node's fetch (undici) throws `TypeError: fetch failed` and puts the real
+// reason (ECONNREFUSED, ENOTFOUND, UND_ERR_*...) on `err.cause`, sometimes
+// inside an AggregateError. Walk the chain to find the first string code.
+function findCode(err) {
+  const seen = new Set();
+  const queue = [err];
+  while (queue.length && seen.size < 10) {
+    const cur = queue.shift();
+    if (!cur || typeof cur !== "object" || seen.has(cur)) continue;
+    seen.add(cur);
+    if (typeof cur.code === "string") return cur.code;
+    queue.push(cur.cause);
+    if (Array.isArray(cur.errors)) queue.push(...cur.errors);
+  }
+  return null;
+}
+
+function isTimeoutCode(code) {
+  return code === "ETIMEDOUT" || code === "ESOCKETTIMEDOUT" || /^UND_ERR_.*TIMEOUT$/.test(code || "");
+}
+
+function isNetworkCode(code) {
+  if (!code) return false;
+  return /^E[A-Z0-9]+$/.test(code) || code === "EAI_AGAIN" || code === "EAI_FAIL" || code.startsWith("UND_ERR_");
+}
 
-  if (!err) return base;
+// Browsers and Node throw a bare TypeError for network-level fetch failures.
+const FETCH_NETWORK_MESSAGE =
+  /fetch failed|failed to fetch|network ?request failed|load failed|networkerror when attempting to fetch/i;
+
+function isFetchNetworkTypeError(err) {
+  return err.name === "TypeError" && FETCH_NETWORK_MESSAGE.test(err.message || "");
+}
+
+function normalizeError(err) {
+  if (!err) return shape(err);
 
   // axios error shape: err.response.{status,data}, err.request, err.code
   if (err.isAxiosError || (err.response && typeof err.response.status === "number" && err.config)) {
-    return {
+    return shape(err, {
       message: err.response?.data?.message || err.message || "Request failed",
       status: err.response?.status ?? null,
       code: err.code ?? null,
       isNetworkError: !err.response && Boolean(err.request),
-      isTimeout: err.code === "ECONNABORTED" || /timeout/i.test(err.message || ""),
-      cause: err,
-    };
+      isTimeout: err.code === "ECONNABORTED" || err.code === "ETIMEDOUT" || /timeout/i.test(err.message || ""),
+      isAborted: err.code === "ERR_CANCELED" || err.name === "CanceledError",
+    });
   }
 
   // fetch Response passed in directly (not thrown, but common enough to handle)
   if (typeof err.status === "number" && typeof err.ok === "boolean") {
-    return {
+    return shape(err, {
       message: err.statusText || `Request failed with status ${err.status}`,
       status: err.status,
-      code: null,
-      isNetworkError: false,
-      isTimeout: false,
-      cause: err,
-    };
+    });
   }
 
-  // our own TimeoutError, or DOMException from AbortController
-  if (err.name === "AbortError" || err.name === "TimeoutError" || err.code === "ETIMEDOUT") {
-    return {
+  const chainCode = findCode(err);
+
+  // reqkit's TimeoutError, AbortSignal.timeout() (DOMException TimeoutError),
+  // node ETIMEDOUT, undici connect/headers/body timeouts
+  if (err.name === "TimeoutError" || isTimeoutCode(chainCode)) {
+    return shape(err, {
       message: err.message || "Request timed out",
-      status: null,
-      code: "ETIMEDOUT",
-      isNetworkError: false,
+      code: chainCode || "ETIMEDOUT",
       isTimeout: true,
-      cause: err,
-    };
+    });
+  }
+
+  // Deliberate cancellation via AbortController — not a timeout.
+  if (err.name === "AbortError") {
+    return shape(err, {
+      message: err.message || "Request aborted",
+      code: "ABORT_ERR",
+      isAborted: true,
+    });
   }
 
-  // node http/https / undici network-level failures
-  if (err.code && /^E[A-Z]+$/.test(err.code)) {
-    return {
-      message: err.message || `Network error (${err.code})`,
-      status: null,
-      code: err.code,
+  // node http/https / undici network-level failures, including
+  // `TypeError: fetch failed` with the real code on err.cause
+  if (isNetworkCode(chainCode) || isFetchNetworkTypeError(err)) {
+    return shape(err, {
+      message: err.message || `Network error (${chainCode})`,
+      code: chainCode,
       isNetworkError: true,
-      isTimeout: false,
-      cause: err,
-    };
+    });
   }
 
-  return {
+  return shape(err, {
     message: err.message || String(err),
-    status: err.status ?? err.statusCode ?? null,
+    status: err.status ?? err.statusCode ?? err.response?.status ?? err.response?.statusCode ?? null,
     code: err.code ?? null,
-    isNetworkError: false,
-    isTimeout: false,
-    cause: err,
-  };
+  });
 }
 
 module.exports = { normalizeError };

package/src/retryAfterAware.js

@@ -1,20 +1,21 @@
-function delay(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
+const { RetryAbortedError, sleep } = require("./_sleep");
+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) return null;
+  if (headerValue === null || headerValue === undefined) return null;
+  const value = String(headerValue).trim();
+  if (!value) return null;
 
-  const seconds = Number(headerValue);
-  if (!Number.isNaN(seconds)) {
-    return Math.max(0, seconds * 1000);
+  // delta-seconds (spec says integer; tolerate "1.5" from sloppy servers)
+  if (/^\d+(\.\d+)?$/.test(value)) {
+    return Number(value) * 1000;
   }
 
-  const dateMs = Date.parse(headerValue);
+  const dateMs = Date.parse(value);
   if (!Number.isNaN(dateMs)) {
     return Math.max(0, dateMs - Date.now());
   }
@@ -46,22 +47,50 @@ function getWaitMsFromHeaders(headers) {
   return null;
 }
 
+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.
  *
+ * 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
+ * connection is released.
+ *
  * `fn` should return a fetch Response (or anything with `.status` and
  * `.headers.get()`).
  *
- * @param {() => Promise<Response>} fn
+ * @param {(attempt: number) => Promise<Response>} fn
  * @param {object} [opts]
  * @param {number} [opts.retries=3]
  * @param {number[]} [opts.retryStatusCodes=[429, 503]]
  * @param {number} [opts.fallbackDelayMs=1000] - used when no usable header is present
  * @param {number} [opts.maxDelayMs=60000]
  * @param {(status: number, waitMs: number, attempt: number) => void} [opts.onRetry]
+ * @param {(err: any, attempt: number) => boolean} [opts.shouldRetryError] -
+ *   decides whether a thrown error is retried. Default: network errors and
+ *   timeouts only.
+ * @param {(err: any, waitMs: number, attempt: number) => void} [opts.onRetryError]
+ * @param {AbortSignal} [opts.signal] - cancels the retry loop, throwing
+ *   RetryAbortedError
  */
 async function retryAfterAware(fn, opts = {}) {
   const {
@@ -70,10 +99,27 @@ async function retryAfterAware(fn, opts = {}) {
     fallbackDelayMs = 1000,
     maxDelayMs = 60000,
     onRetry,
+    shouldRetryError = defaultShouldRetryError,
+    onRetryError,
+    signal,
   } = opts;
 
+  let lastErr;
   for (let attempt = 0; attempt <= retries; attempt++) {
-    const response = await fn(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;
@@ -82,8 +128,9 @@ async function retryAfterAware(fn, opts = {}) {
     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 delay(waitMs);
+    await sleep(waitMs, signal);
   }
 }
 

package/src/withDedupe.js

@@ -1,10 +1,45 @@
+// Non-plain objects (AbortSignal, Response, class instances, functions...)
+// can't be meaningfully JSON-serialized — JSON.stringify turns every
+// AbortSignal into "{}", which would make unrelated calls share one request.
+// Give them a stable identity-based id instead.
+const identityIds = new WeakMap();
+let nextIdentityId = 1;
+
+function identityOf(value) {
+  let id = identityIds.get(value);
+  if (id === undefined) {
+    id = nextIdentityId++;
+    identityIds.set(value, id);
+  }
+  return id;
+}
+
+function isPlainObject(value) {
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function keyReplacer(_key, value) {
+  if (typeof value === "bigint") return { $bigint: String(value) };
+  if (typeof value === "function") return { $ref: identityOf(value) };
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value;
+  if (!isPlainObject(value)) return { $ref: identityOf(value) };
+
+  // Sort plain-object keys so {a:1,b:2} and {b:2,a:1} dedupe together.
+  const sorted = {};
+  for (const k of Object.keys(value).sort()) sorted[k] = value[k];
+  return sorted;
+}
+
 function defaultKeyFn(...args) {
   try {
-    return JSON.stringify(args);
+    return JSON.stringify(args, keyReplacer);
   } catch {
-    // Fall back to a stable-ish key if args aren't JSON-serializable
-    // (e.g. contain a function or circular ref).
-    return args.map((a) => String(a)).join("|");
+    // Circular structures etc. Fall back to identity for objects.
+    return args
+      .map((a) => ((a && typeof a === "object") || typeof a === "function" ? `#${identityOf(a)}` : String(a)))
+      .join("|");
   }
 }
 
@@ -22,7 +57,10 @@ function defaultKeyFn(...args) {
  * @param {(...args: any[]) => Promise<any>} fn
  * @param {object} [opts]
  * @param {(...args: any[]) => string} [opts.keyFn] - derives a dedupe key
- *   from the call arguments. Defaults to JSON.stringify(args).
+ *   from the call arguments. By default plain data is compared by value
+ *   (object key order doesn't matter) and anything else — AbortSignals,
+ *   Responses, class instances, functions — by identity, so two calls with
+ *   different AbortSignals are never merged.
  * @returns {(...args: any[]) => Promise<any>}
  */
 function withDedupe(fn, opts = {}) {

package/src/withProgress.js

@@ -1,48 +1,107 @@
+class BodyTooLargeError extends Error {
+  constructor(maxBytes) {
+    super(`Response body exceeded the ${maxBytes}-byte limit`);
+    this.name = "BodyTooLargeError";
+    this.code = "EBODYTOOLARGE";
+    this.maxBytes = maxBytes;
+  }
+}
+
+function cancelQuietly(reader) {
+  try {
+    const p = reader.cancel();
+    if (p && typeof p.catch === "function") p.catch(() => {});
+  } catch {
+    // already closed / released — nothing to do
+  }
+}
+
 /**
  * Reads a fetch Response body while reporting progress, and returns the
  * fully collected bytes as a Uint8Array. Works for any streamed response,
  * not just file downloads — same shape whether it's a media file, a large
  * JSON payload, or anything else worth showing progress for.
  *
- * If the server doesn't send Content-Length, `total` will be null in the
- * progress callback — the loaded count is still accurate.
+ * `total` is null (and `percent` with it) when the size isn't trustworthy:
+ * no Content-Length, or a Content-Encoding is applied (Content-Length is then
+ * the *compressed* size while fetch hands you *decompressed* bytes, so
+ * loaded could exceed total). `percent` is always clamped to 0–100.
  *
  * @param {Response} response
- * @param {(progress: { loaded: number, total: number | null, percent: number | null }) => void} onProgress
+ * @param {(progress: { loaded: number, total: number | null, percent: number | null }) => void} [onProgress]
+ * @param {object} [opts]
+ * @param {number} [opts.maxBytes] - abort with BodyTooLargeError once more
+ *   than this many bytes have been received
+ * @param {AbortSignal} [opts.signal] - cancels the read; rejects with the
+ *   signal's reason (an AbortError by default)
  * @returns {Promise<Uint8Array>}
  */
-async function withProgress(response, onProgress) {
+async function withProgress(response, onProgress, opts = {}) {
+  const { maxBytes, signal } = opts;
+  signal?.throwIfAborted?.();
+
   if (!response.body || typeof response.body.getReader !== "function") {
     // No streaming support available — fall back to a single-shot read,
     // still reporting one final progress event so callers don't need a branch.
     const buf = new Uint8Array(await response.arrayBuffer());
+    signal?.throwIfAborted?.();
+    if (maxBytes !== undefined && buf.byteLength > maxBytes) {
+      throw new BodyTooLargeError(maxBytes);
+    }
     if (onProgress) {
       onProgress({ loaded: buf.byteLength, total: buf.byteLength, percent: 100 });
     }
     return buf;
   }
 
+  const encoding = response.headers?.get?.("content-encoding");
+  const encoded = Boolean(encoding) && encoding.trim().toLowerCase() !== "identity";
   const contentLength = response.headers?.get?.("content-length");
-  const total = contentLength ? Number(contentLength) : null;
+  const parsed = contentLength ? Number(contentLength) : NaN;
+  const total = !encoded && Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
 
   const reader = response.body.getReader();
+
+  // Fail fast when the declared size already exceeds the cap.
+  if (maxBytes !== undefined && total !== null && total > maxBytes) {
+    cancelQuietly(reader);
+    throw new BodyTooLargeError(maxBytes);
+  }
+
+  const onAbort = () => cancelQuietly(reader);
+  signal?.addEventListener("abort", onAbort, { once: true });
+
   const chunks = [];
   let loaded = 0;
+  let finished = false;
 
-  for (;;) {
-    const { done, value } = await reader.read();
-    if (done) break;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      // reader.cancel() on abort makes read() resolve as done — check the
+      // signal first so an aborted read never looks like a complete one.
+      signal?.throwIfAborted?.();
+      if (done) break;
 
-    chunks.push(value);
-    loaded += value.byteLength;
+      chunks.push(value);
+      loaded += value.byteLength;
 
-    if (onProgress) {
-      onProgress({
-        loaded,
-        total,
-        percent: total ? Math.round((loaded / total) * 100) : null,
-      });
+      if (maxBytes !== undefined && loaded > maxBytes) {
+        throw new BodyTooLargeError(maxBytes);
+      }
+
+      if (onProgress) {
+        onProgress({
+          loaded,
+          total,
+          percent: total ? Math.min(100, Math.round((loaded / total) * 100)) : null,
+        });
+      }
     }
+    finished = true;
+  } finally {
+    signal?.removeEventListener("abort", onAbort);
+    if (!finished) cancelQuietly(reader);
   }
 
   const result = new Uint8Array(loaded);
@@ -54,4 +113,4 @@ async function withProgress(response, onProgress) {
   return result;
 }
 
-module.exports = { withProgress };
+module.exports = { withProgress, BodyTooLargeError };

package/src/withRetry.js

@@ -1,3 +1,5 @@
+const { RetryAbortedError, sleep } = require("./_sleep");
+
 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) —
@@ -5,33 +7,6 @@ function defaultShouldRetry(err) {
   return Boolean(err) && err.name !== "AbortError";
 }
 
-class RetryAbortedError extends Error {
-  constructor() {
-    super("Retry loop was aborted");
-    this.name = "RetryAbortedError";
-  }
-}
-
-function delay(ms, signal) {
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted) {
-      reject(new RetryAbortedError());
-      return;
-    }
-    const timer = setTimeout(resolve, ms);
-    if (signal) {
-      signal.addEventListener(
-        "abort",
-        () => {
-          clearTimeout(timer);
-          reject(new RetryAbortedError());
-        },
-        { once: true }
-      );
-    }
-  });
-}
-
 /**
  * Retries an async function with exponential backoff + jitter.
  *
@@ -60,7 +35,7 @@ async function withRetry(fn, opts = {}) {
   let lastErr;
   for (let attempt = 0; attempt <= retries; attempt++) {
     if (signal?.aborted) {
-      throw new RetryAbortedError();
+      throw new RetryAbortedError(lastErr);
     }
     try {
       return await fn(attempt);
@@ -74,7 +49,7 @@ async function withRetry(fn, opts = {}) {
       const jitter = Math.random() * exponential * 0.2;
       const waitMs = Math.round(exponential + jitter);
       if (onRetry) onRetry(err, attempt, waitMs);
-      await delay(waitMs, signal);
+      await sleep(waitMs, signal, err);
     }
   }
   throw lastErr;

package/types/index.d.mts

@@ -0,0 +1,3 @@
+import * as reqkit from "./index.js";
+export * from "./index.js";
+export default reqkit;

package/types/index.d.ts

@@ -9,6 +9,8 @@ export interface RetryOptions {
 
 export class RetryAbortedError extends Error {
   name: "RetryAbortedError";
+  /** The last failure before the loop was aborted, if there was one. */
+  cause?: unknown;
 }
 
 export function withRetry<T>(fn: (attempt: number) => Promise<T>, opts?: RetryOptions): Promise<T>;
@@ -26,6 +28,8 @@ export interface NormalizedError {
   code: string | null;
   isNetworkError: boolean;
   isTimeout: boolean;
+  /** True when the request was cancelled on purpose (AbortController, axios cancel). */
+  isAborted: boolean;
   cause: unknown;
 }
 
@@ -46,6 +50,11 @@ export interface RetryAfterAwareOptions {
   fallbackDelayMs?: number;
   maxDelayMs?: number;
   onRetry?: (status: number, waitMs: number, attempt: number) => void;
+  /** Decide whether a thrown error is retried. Default: network errors and timeouts only. */
+  shouldRetryError?: (err: unknown, attempt: number) => boolean;
+  onRetryError?: (err: unknown, waitMs: number, attempt: number) => void;
+  /** Cancels the retry loop, including any pending wait. Throws RetryAbortedError. */
+  signal?: AbortSignal;
 }
 
 export function retryAfterAware(
@@ -62,9 +71,24 @@ export interface DownloadProgress {
   percent: number | null;
 }
 
+export interface WithProgressOptions {
+  /** Reject with BodyTooLargeError once more than this many bytes arrive. */
+  maxBytes?: number;
+  /** Cancels the read; rejects with the signal's reason. */
+  signal?: AbortSignal;
+}
+
+export class BodyTooLargeError extends Error {
+  name: "BodyTooLargeError";
+  code: "EBODYTOOLARGE";
+  maxBytes: number;
+  constructor(maxBytes: number);
+}
+
 export function withProgress(
   response: Response,
-  onProgress?: (progress: DownloadProgress) => void
+  onProgress?: (progress: DownloadProgress) => void,
+  opts?: WithProgressOptions
 ): Promise<Uint8Array>;
 
 export interface DedupeOptions {