@boy-offi9-inc/reqkit 0.1.0 → 0.1.7

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/@boy-offi9-inc/reqkit" aria-label="npm">
-    <img src="./assets/logo-wordmark.svg" alt="reqkit on npm" width="480" />
+    <img src="https://i.ibb.co/1f63mDTg/logo-wordmark.png" alt="reqkit on npm" width="480" />
   </a>
 </p>
 
@@ -15,7 +15,7 @@
 
 # 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; igno[...]
+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.
 
 ```js
 const { withRetry, normalizeError } = require("@boy-offi9-inc/reqkit");
@@ -27,12 +27,13 @@ const data = await withRetry(() => fetch(url).then(r => r.json()));
 
 ## Why this exists
 
-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 o[...]
+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.
 
-**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[...]
+**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).
 
-- **`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 ig[...]
+- **`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)`
 
@@ -138,7 +147,29 @@ 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 respon[...]
+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 });
+```
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boy-offi9-inc/reqkit",
-  "version": "0.1.0",
+  "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;

package/assets/logo-wordmark.svg

@@ -1,37 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<svg width="640" height="160" viewBox="0 0 640 160" xmlns="http://www.w3.org/2000/svg">
-  <defs>
-    <linearGradient id="wm-bg" x1="0" y1="0" x2="640" y2="160" gradientUnits="userSpaceOnUse">
-      <stop offset="0" stop-color="#101825"/>
-      <stop offset="1" stop-color="#080c14"/>
-    </linearGradient>
-    <linearGradient id="wm-icon-bg" x1="0" y1="0" x2="240" y2="240" gradientUnits="userSpaceOnUse">
-      <stop offset="0" stop-color="#16202e"/>
-      <stop offset="1" stop-color="#0c121c"/>
-    </linearGradient>
-    <linearGradient id="wm-arc" x1="175" y1="88" x2="98" y2="60" gradientUnits="userSpaceOnUse">
-      <stop offset="0" stop-color="#3d8bff"/>
-      <stop offset="1" stop-color="#ffb43d"/>
-    </linearGradient>
-  </defs>
-
-  <rect x="0" y="0" width="640" height="160" rx="20" fill="url(#wm-bg)"/>
-
-  <!-- icon, scaled down from the 240x240 mark -->
-  <g transform="translate(24,20) scale(0.5)">
-    <rect x="6" y="6" width="228" height="228" rx="46" fill="url(#wm-icon-bg)"/>
-
-    <path d="M 175.4 88 A 64 64 0 1 1 98.1 59.9"
-          fill="none" stroke="url(#wm-arc)" stroke-width="13" stroke-linecap="round"/>
-
-    <polygon points="113.1,54.4 103.1,67.7 96.9,50.8" fill="#ffb43d"/>
-
-    <circle cx="169" cy="161.1" r="7" fill="#3d8bff"/>
-    <circle cx="78.9" cy="169" r="6" fill="#6f9fff"/>
-    <circle cx="59.9" cy="98.1" r="5" fill="#a3c2ff"/>
-  </g>
-
-  <!-- wordmark -->
-  <text x="164" y="82" font-family="'JetBrains Mono', 'Courier New', monospace" font-size="42" font-weight="700" fill="#eef2f7">req<tspan fill="#ffb43d">kit</tspan></text>
-  <text x="165" y="112" font-family="'JetBrains Mono', 'Courier New', monospace" font-size="16" fill="#6b7688">HTTP helpers — retry, timeout, rate-limit aware</text>
-</svg>