@boy-offi9-inc/reqkit 0.1.7 → 0.3.0

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,15 +1,18 @@
-const { withRetry, RetryAbortedError } = require("./withRetry");
+const { withRetry, RetryAbortedError, StopRetry } = require("./withRetry");
 const { withTimeout, TimeoutError } = require("./withTimeout");
 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");
+const { createLimiter } = require("./createLimiter");
+const { createFetch, HTTPError } = require("./createFetch");
 
 module.exports = {
   withRetry,
   RetryAbortedError,
+  StopRetry,
   withTimeout,
   TimeoutError,
   normalizeError,
@@ -19,5 +22,9 @@ module.exports = {
   parseRetryAfter,
   getWaitMsFromHeaders,
   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,
@@ -12,7 +13,11 @@ export const {
   parseRetryAfter,
   getWaitMsFromHeaders,
   withProgress,
+  BodyTooLargeError,
   withDedupe,
+  createLimiter,
+  createFetch,
+  HTTPError,
 } = reqkit;
 
 export default 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,49 +1,10 @@
-function delay(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-/**
- * 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;
-
-  const seconds = Number(headerValue);
-  if (!Number.isNaN(seconds)) {
-    return Math.max(0, seconds * 1000);
-  }
-
-  const dateMs = Date.parse(headerValue);
-  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 { withRetry } = require("./withRetry");
+const { normalizeError } = require("./normalizeError");
+const { parseRetryAfter, getWaitMsFromHeaders } = require("./_http");
 
-  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;
+function defaultShouldRetryError(err) {
+  const normalized = normalizeError(err);
+  return normalized.isNetworkError || normalized.isTimeout;
 }
 
 /**
@@ -52,39 +13,63 @@ function getWaitMsFromHeaders(headers) {
  * 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
+ * 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 = {}) {
+function retryAfterAware(fn, opts = {}) {
   const {
     retries = 3,
     retryStatusCodes = [429, 503],
     fallbackDelayMs = 1000,
     maxDelayMs = 60000,
     onRetry,
+    shouldRetryError = defaultShouldRetryError,
+    onRetryError,
+    signal,
   } = opts;
 
-  for (let attempt = 0; attempt <= retries; attempt++) {
-    const response = await fn(attempt);
-
-    if (!retryStatusCodes.includes(response.status) || attempt === retries) {
-      return response;
-    }
-
-    const headerWaitMs = getWaitMsFromHeaders(response.headers);
-    const waitMs = Math.min(headerWaitMs ?? fallbackDelayMs * 2 ** attempt, maxDelayMs);
-
-    if (onRetry) onRetry(response.status, waitMs, attempt);
-    await delay(waitMs);
-  }
+  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/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 = {}) {