@boy-offi9-inc/reqkit 0.1.2 → 0.1.7

package/README.md

@@ -33,6 +33,7 @@ Most HTTP retry/timeout wrappers bundle everything into a client you have to ful
 
 - **`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.
 
 Zero dependencies. CJS + ESM. TypeScript types included.
 
@@ -66,6 +67,14 @@ const data = await withRetry(
 | `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` |
+
+```js
+// Cancel a long retry/backoff sequence externally — e.g. the user navigated away
+const controller = new AbortController();
+const promise = withRetry(() => fetch(url), { retries: 5, signal: controller.signal });
+controller.abort(); // rejects with RetryAbortedError, even mid-backoff
+```
 
 ### `withTimeout(fn, ms)`
 
@@ -140,6 +149,28 @@ 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.
 
+### `withDedupe(fn, opts?)`
+
+Coalesces 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.
+
+```js
+const getUser = withDedupe((id) => fetch(`/api/users/${id}`).then(r => r.json()));
+
+// Only one network request goes out — both callers share it.
+const [a, b] = await Promise.all([getUser(1), getUser(1)]);
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `keyFn` | `(...args) => JSON.stringify(args)` | derives the dedupe key from call args |
+
+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
+// Custom key when the default arg-based key isn't quite right
+const fn = withDedupe((req) => doFetch(req), { keyFn: (req) => req.url });
+```
+
 ---
 
 ## Design notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boy-offi9-inc/reqkit",
-  "version": "0.1.2",
+  "version": "0.1.7",
   "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",
@@ -40,7 +40,6 @@
     "src",
     "types",
     "README.md",
-    "LICENSE",
-    "assets"
+    "LICENSE"
   ]
 }

package/src/index.js

@@ -1,13 +1,15 @@
-const { withRetry } = require("./withRetry");
+const { withRetry, RetryAbortedError } = 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 { withDedupe } = require("./withDedupe");
 
 module.exports = {
   withRetry,
+  RetryAbortedError,
   withTimeout,
   TimeoutError,
   normalizeError,
@@ -17,4 +19,5 @@ module.exports = {
   parseRetryAfter,
   getWaitMsFromHeaders,
   withProgress,
+  withDedupe,
 };

package/src/index.mjs

@@ -2,6 +2,7 @@ import reqkit from "./index.js";
 
 export const {
   withRetry,
+  RetryAbortedError,
   withTimeout,
   TimeoutError,
   normalizeError,
@@ -11,6 +12,7 @@ export const {
   parseRetryAfter,
   getWaitMsFromHeaders,
   withProgress,
+  withDedupe,
 } = reqkit;
 
 export default reqkit;

package/src/withDedupe.js

@@ -0,0 +1,50 @@
+function defaultKeyFn(...args) {
+  try {
+    return JSON.stringify(args);
+  } 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("|");
+  }
+}
+
+/**
+ * Wraps an async function so that concurrent calls with the same key share
+ * a single in-flight promise instead of firing duplicate requests. Common
+ * use case: several parts of a UI ask for the same resource at once (e.g. a
+ * user profile) — only one network request actually goes out, and every
+ * caller resolves with the same result.
+ *
+ * The in-flight entry is cleared as soon as the call settles (success or
+ * failure), so the next call — even with the same key — always starts a
+ * fresh request. This is deduplication of concurrent calls, not a cache.
+ *
+ * @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).
+ * @returns {(...args: any[]) => Promise<any>}
+ */
+function withDedupe(fn, opts = {}) {
+  const { keyFn = defaultKeyFn } = opts;
+  const inFlight = new Map();
+
+  return function deduped(...args) {
+    const key = keyFn(...args);
+
+    if (inFlight.has(key)) {
+      return inFlight.get(key);
+    }
+
+    const promise = Promise.resolve()
+      .then(() => fn(...args))
+      .finally(() => {
+        inFlight.delete(key);
+      });
+
+    inFlight.set(key, promise);
+    return promise;
+  };
+}
+
+module.exports = { withDedupe };

package/src/withRetry.js

@@ -5,20 +5,47 @@ function defaultShouldRetry(err) {
   return Boolean(err) && err.name !== "AbortError";
 }
 
-function delay(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+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.
  *
- * @param {() => Promise<any>} fn
+ * @param {(attempt: number) => Promise<any>} fn
  * @param {object} [opts]
  * @param {number} [opts.retries=3] - max retry attempts after the first try
  * @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 {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*.
  */
 async function withRetry(fn, opts = {}) {
   const {
@@ -27,10 +54,14 @@ async function withRetry(fn, opts = {}) {
     maxDelayMs = 10000,
     shouldRetry = defaultShouldRetry,
     onRetry,
+    signal,
   } = opts;
 
   let lastErr;
   for (let attempt = 0; attempt <= retries; attempt++) {
+    if (signal?.aborted) {
+      throw new RetryAbortedError();
+    }
     try {
       return await fn(attempt);
     } catch (err) {
@@ -43,10 +74,10 @@ 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);
+      await delay(waitMs, signal);
     }
   }
   throw lastErr;
 }
 
-module.exports = { withRetry };
+module.exports = { withRetry, RetryAbortedError };

package/types/index.d.ts

@@ -4,6 +4,11 @@ export interface RetryOptions {
   maxDelayMs?: number;
   shouldRetry?: (err: unknown, attempt: number) => boolean;
   onRetry?: (err: unknown, attempt: number, delayMs: number) => void;
+  signal?: AbortSignal;
+}
+
+export class RetryAbortedError extends Error {
+  name: "RetryAbortedError";
 }
 
 export function withRetry<T>(fn: (attempt: number) => Promise<T>, opts?: RetryOptions): Promise<T>;
@@ -61,3 +66,12 @@ export function withProgress(
   response: Response,
   onProgress?: (progress: DownloadProgress) => void
 ): Promise<Uint8Array>;
+
+export interface DedupeOptions {
+  keyFn?: (...args: any[]) => string;
+}
+
+export function withDedupe<Fn extends (...args: any[]) => Promise<any>>(
+  fn: Fn,
+  opts?: DedupeOptions
+): Fn;