@codingaryan/smoothapi 1.0.0 → 1.1.0

package/README.md

@@ -1,123 +1,174 @@
-# @codingaryan/smoothapi
-
-API resilience library for TypeScript/JavaScript. It wraps the native `fetch` API with **exponential backoff, full jitter, and a finite-state machine circuit breaker** to protect against cascading failures.
-
-Zero dependencies. Small bundle size. Built for modern ESM.
-
-## Install
-
-```bash
-npm install @codingaryan/smoothapi
-```
-
-## Features
-
-- **Exponential Backoff with Full Jitter:** Prevents the "thundering herd" problem by randomizing retry delays.
-- **Circuit Breaker (FSM):** Isolated per-domain state machine (`CLOSED` → `OPEN` → `HALF_OPEN`).
-- **Smart Retries:** Automatically retries on specific HTTP status codes (e.g., 429, 500, 502, 503, 504) while throwing immediately on client errors (400, 401, 404).
-- **Graceful Fallbacks:** Optionally serve cached or default data instantly when the circuit is `OPEN`.
-
-## Usage
-
-### Basic Usage (Defaults)
-
-If you don't need custom configurations, you can instantiate the resilient fetch with its defaults by simply passing an empty object.
-
-```typescript
-import { createResilientFetch } from '@codingaryan/smoothapi';
-
-// Create it with default settings
-const fetchWithRetry = createResilientFetch({});
-
-async function main() {
-  try {
-    // Drop-in replacement for native fetch
-    const response = await fetchWithRetry('https://api.example.com/data');
-    const data = await response.json();
-    console.log(data);
-  } catch (err) {
-    console.error("Request failed completely:", err);
-  }
-}
-```
-
-**Default Settings provided automatically:**
-- **Retries**: 3 attempts
-- **Backoff Base Delay**: 100 milliseconds
-- **Circuit Failure Threshold**: Trips after 3 consecutive failures
-- **Circuit Cooldown**: Stays open for 10 seconds before probing
-- **Status Codes to Retry**: `429`, `500`, `502`, `503`, and `504`
-
-### Advanced Usage (Custom Settings)
-
-You can override any of the defaults to suit your application's needs, such as adding a fallback object.
-
-```typescript
-import { createResilientFetch } from '@codingaryan/smoothapi';
-
-const fetchWithRetry = createResilientFetch({
-  backoff: {
-    baseDelay: 100,      // ms to wait before first retry
-    maxDelay: 30000,     // cap on exponential growth
-    maxRetries: 3        // max number of retry attempts
-  },
-  circuitBreaker: {
-    failureThreshold: 3, // trip OPEN after 3 consecutive failures
-    cooldownMs: 10000    // stay OPEN for 10 seconds before probing
-  },
-  // Optional: Return this instead of throwing when the circuit is OPEN
-  fallback: { error: "Service degraded, returning stale data." },
-  // Optional: Custom status codes to retry on
-  retryOn: [429, 500, 502, 503, 504]
-});
-
-async function main() {
-  try {
-    const response = await fetchWithRetry('https://api.example.com/data');
-    
-    // If fallback triggered, it returns your fallback object directly
-    if ('error' in response) {
-        console.log("Fallback triggered:", response.error);
-        return;
-    }
-    
-    // Otherwise it's a standard Response object
-    const data = await response.json();
-    console.log(data);
-  } catch (err) {
-    console.error("Request failed completely:", err);
-  }
-}
-```
-
-### Client Error Handling & Alerts
-
-By default, client errors (e.g. `400`, `401`, `403`, `404`, `405`) resolve immediately and bypass the retry loop. If you want to handle these errors gracefully and alert users:
-
-```typescript
-import { createResilientFetch } from '@codingaryan/smoothapi';
-
-const fetchWithRetry = createResilientFetch({
-  fallbackOnNonRetryable: true,
-  // Optional: Trigger custom UI logic when a client error happens
-  onNonRetryableError: (status, message) => {
-    console.log(`Custom callback: Received status ${status}`);
-  },
-  // Optional: Fallback returned on non-retryable errors
-  fallback: { error: "Page not found." }
-});
-```
-
-* **Default Alerting**: If `fallbackOnNonRetryable` is `true` and no custom `onNonRetryableError` is provided, running in a browser environment will trigger a standard `window.alert("Non-retryable HTTP error: [status]")`. In backend/Node environments, it logs the warning to `console.error`.
-* **Graceful Return**: If no custom `fallback` is configured, it returns a mock `Response` wrapper with the status code and a JSON error body: `{ error: true, status: 404, message: "..." }`. Callers can safely call `.json()`, `.status`, or `.ok` on it without crashing.
-
-## How It Works
-
-1. **Host Extraction:** The domain is automatically extracted from the URL. The circuit breaker state is isolated per host (e.g., `api.github.com` failing won't trip the circuit for `api.stripe.com`).
-2. **Circuit Check:** Before making a network request, the breaker checks the state. If it's `OPEN`, the request is blocked instantly (returning your fallback, or throwing a `CircuitOpenError`).
-3. **Execution & Retries:** If the response status is in your `retryOn` list, it's counted as a failure and retried with backoff.
-4. **Recovery:** After `cooldownMs`, the breaker enters `HALF_OPEN` state. The next request acts as a probe. If it succeeds, the circuit closes. If it fails, it snaps back to `OPEN` immediately.
-
-## License
-
-MIT
+# @codingaryan/smoothapi
+
+API resilience library for TypeScript/JavaScript. It wraps the native `fetch` API with **exponential backoff, full jitter, and a finite-state machine circuit breaker** to protect against cascading failures.
+
+Zero dependencies. Small bundle size. Built for modern ESM.
+
+## Install
+
+```bash
+npm install @codingaryan/smoothapi
+```
+
+## Features
+
+- **Exponential Backoff with Full Jitter:** Prevents the "thundering herd" problem by randomizing retry delays.
+- **Circuit Breaker (FSM):** Isolated per-domain state machine (`CLOSED` → `OPEN` → `HALF_OPEN`).
+- **Smart Retries:** Automatically retries on specific HTTP status codes (e.g., 429, 500, 502, 503, 504) while throwing immediately on client errors (400, 401, 404).
+- **Graceful Fallbacks:** Optionally serve cached or default data instantly when the circuit is `OPEN`.
+- **Request Deduplication:** Automatically coalesce concurrent identical requests into a single network call.
+
+## Usage
+
+### Basic Usage (Defaults)
+
+If you don't need custom configurations, you can instantiate the resilient fetch with its defaults by simply passing an empty object.
+
+```typescript
+import { createResilientFetch } from '@codingaryan/smoothapi';
+
+// Create it with default settings
+const fetchWithRetry = createResilientFetch({});
+
+async function main() {
+  try {
+    // Drop-in replacement for native fetch
+    const response = await fetchWithRetry('https://api.example.com/data');
+    const data = await response.json();
+    console.log(data);
+  } catch (err) {
+    console.error("Request failed completely:", err);
+  }
+}
+```
+
+**Default Settings provided automatically:**
+- **Retries**: 3 attempts
+- **Backoff Base Delay**: 100 milliseconds
+- **Circuit Failure Threshold**: Trips after 3 consecutive failures
+- **Circuit Cooldown**: Stays open for 10 seconds before probing
+- **Status Codes to Retry**: `429`, `500`, `502`, `503`, and `504`
+
+### Advanced Usage (Custom Settings)
+
+You can override any of the defaults to suit your application's needs, such as adding a fallback object.
+
+```typescript
+import { createResilientFetch } from '@codingaryan/smoothapi';
+
+const fetchWithRetry = createResilientFetch({
+  backoff: {
+    baseDelay: 100,      // ms to wait before first retry
+    maxDelay: 30000,     // cap on exponential growth
+    maxRetries: 3        // max number of retry attempts
+  },
+  circuitBreaker: {
+    failureThreshold: 3, // trip OPEN after 3 consecutive failures
+    cooldownMs: 10000    // stay OPEN for 10 seconds before probing
+  },
+  // Optional: Return this instead of throwing when the circuit is OPEN
+  fallback: { error: "Service degraded, returning stale data." },
+  // Optional: Custom status codes to retry on
+  retryOn: [429, 500, 502, 503, 504]
+});
+
+async function main() {
+  try {
+    const response = await fetchWithRetry('https://api.example.com/data');
+    
+    // If fallback triggered, it returns your fallback object directly
+    if ('error' in response) {
+        console.log("Fallback triggered:", response.error);
+        return;
+    }
+    
+    // Otherwise it's a standard Response object
+    const data = await response.json();
+    console.log(data);
+  } catch (err) {
+    console.error("Request failed completely:", err);
+  }
+}
+```
+
+### Client Error Handling & Alerts
+
+By default, client errors (e.g. `400`, `401`, `403`, `404`, `405`) resolve immediately and bypass the retry loop. If you want to handle these errors gracefully and alert users:
+
+```typescript
+import { createResilientFetch } from '@codingaryan/smoothapi';
+
+const fetchWithRetry = createResilientFetch({
+  fallbackOnNonRetryable: true,
+  // Optional: Trigger custom UI logic when a client error happens
+  onNonRetryableError: (status, message) => {
+    console.log(`Custom callback: Received status ${status}`);
+  },
+  // Optional: Fallback returned on non-retryable errors
+  fallback: { error: "Page not found." }
+});
+```
+
+* **Default Alerting**: If `fallbackOnNonRetryable` is `true` and no custom `onNonRetryableError` is provided, running in a browser environment will trigger a standard `window.alert("Non-retryable HTTP error: [status]")`. In backend/Node environments, it logs the warning to `console.error`.
+* **Graceful Return**: If no custom `fallback` is configured, it returns a mock `Response` wrapper with the status code and a JSON error body: `{ error: true, status: 404, message: "..." }`. Callers can safely call `.json()`, `.status`, or `.ok` on it without crashing.
+
+### Request Deduplication
+
+When multiple identical requests are made concurrently, SmoothAPI can execute only one network call and share the result with all callers. This reduces unnecessary load on downstream services.
+
+**Enable with default key function** (deduplicates by URL):
+
+```typescript
+import { createResilientFetch } from '@codingaryan/smoothapi';
+
+const fetchWithRetry = createResilientFetch({
+  deduplication: {} // Empty object activates deduplication
+});
+
+// All three calls share a single network request
+const [a, b, c] = await Promise.all([
+  fetchWithRetry('http://api.example.com/users/1'),
+  fetchWithRetry('http://api.example.com/users/1'),
+  fetchWithRetry('http://api.example.com/users/1'),
+]);
+```
+
+**Custom key function** for advanced coalescing:
+
+```typescript
+const fetchWithRetry = createResilientFetch({
+  deduplication: {
+    // Deduplicate by method + URL (ignores headers/body)
+    keyFn: (url, options) => `${options?.method ?? 'GET'}:${url.toString()}`
+  }
+});
+```
+
+**Opt out of deduplication** for specific requests:
+
+```typescript
+const fetchWithRetry = createResilientFetch({
+  deduplication: {
+    keyFn: (url, options) => {
+      // Skip dedup for POST requests
+      if (options?.method === 'POST') return null;
+      return url.toString();
+    }
+  }
+});
+```
+
+* **Default Behavior**: Deduplicates by URL only (method-agnostic). Concurrent GETs to the same URL are coalesced.
+* **Error Propagation**: If the network call fails, all waiting callers receive the same error.
+* **Settlement**: Once a request completes, the next call to the same URL triggers a fresh network request.
+
+## How It Works
+
+1. **Host Extraction:** The domain is automatically extracted from the URL. The circuit breaker state is isolated per host (e.g., `api.github.com` failing won't trip the circuit for `api.stripe.com`).
+2. **Circuit Check:** Before making a network request, the breaker checks the state. If it's `OPEN`, the request is blocked instantly (returning your fallback, or throwing a `CircuitOpenError`).
+3. **Execution & Retries:** If the response status is in your `retryOn` list, it's counted as a failure and retried with backoff.
+4. **Recovery:** After `cooldownMs`, the breaker enters `HALF_OPEN` state. The next request acts as a probe. If it succeeds, the circuit closes. If it fails, it snaps back to `OPEN` immediately.
+
+## License
+
+MIT

package/dist/dedup.d.ts

@@ -0,0 +1,44 @@
+import type { DeduplicationKeyFn } from "./types.js";
+/**
+ * Tracks in-flight requests and coalesces identical concurrent calls
+ * into a single shared Promise.
+ *
+ * Lifecycle
+ * ---------
+ * 1. First caller for key K → starts the network call, stores the raw
+ *    Promise in the map, and returns a `.then(clone)` chain so the
+ *    original `Response` body stream is never consumed by anyone.
+ * 2. Subsequent callers for K (while the first is still pending) →
+ *    attach their own `.then(clone)` to the same shared Promise, each
+ *    receiving an independent cloned `Response`.
+ * 3. Once the shared Promise settles the entry is deleted, so the *next*
+ *    caller after settlement triggers a fresh network request.
+ *
+ * Response cloning
+ * ----------------
+ * `fetch()` returns a `Response` whose body is a one-time-readable stream.
+ * If two callers received the *same* `Response` object, whichever reads
+ * `.json()` / `.text()` first would disturb the body for the other.
+ * To avoid this, the raw result is kept in the inflight map and every
+ * caller — including the first one — receives `response.clone()`, leaving
+ * the stored original unconsumed and safe to clone again.
+ */
+export declare class RequestDeduplicator {
+    /** Stores the raw (un-cloned) shared Promise for each in-flight key. */
+    private readonly inflight;
+    private readonly keyFn;
+    constructor(keyFn?: DeduplicationKeyFn);
+    /**
+     * Execute `fetcher` if no identical request is already in-flight,
+     * otherwise attach to the existing Promise.  In either case the caller
+     * receives `Response.clone()` so body streams are independent.
+     *
+     * @param url     - Same value passed to the outer resilientFetch.
+     * @param options - Same value passed to the outer resilientFetch.
+     * @param fetcher - A thunk that performs the actual network call.
+     */
+    execute<R>(url: string | URL, options: RequestInit | undefined, fetcher: () => Promise<R>): Promise<R>;
+    /** Number of in-flight deduplicated requests. Useful for tests. */
+    get size(): number;
+}
+//# sourceMappingURL=dedup.d.ts.map

package/dist/dedup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup.d.ts","sourceRoot":"","sources":["../src/dedup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAyBrD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,mBAAmB;IAC9B,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4C;IACrE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;gBAE/B,KAAK,CAAC,EAAE,kBAAkB;IAItC;;;;;;;;OAQG;IACH,OAAO,CAAC,CAAC,EACP,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,OAAO,EAAE,WAAW,GAAG,SAAS,EAChC,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,CAAC,CAAC;IAyBb,mEAAmE;IACnE,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/dedup.js

@@ -0,0 +1,86 @@
+/**
+ * Default key derivation: stringified URL only.
+ * This intentionally ignores `options` (e.g. headers, body) so that
+ * concurrent GET /users/1 calls are always collapsed, even when the
+ * caller did not customise the key function.
+ *
+ * For mutation-safe deduplication (POST, PUT …) supply a custom
+ * `keyFn` via `DeduplicationConfig.keyFn`.
+ */
+const defaultKeyFn = (url) => url.toString();
+/**
+ * Clone `result` if it is a `Response` — necessary because `Response` bodies
+ * are single-consumption streams.  Non-Response values (fallback objects, etc.)
+ * are returned as-is.
+ */
+function cloneIfResponse(result) {
+    if (result instanceof Response) {
+        return result.clone();
+    }
+    return result;
+}
+/**
+ * Tracks in-flight requests and coalesces identical concurrent calls
+ * into a single shared Promise.
+ *
+ * Lifecycle
+ * ---------
+ * 1. First caller for key K → starts the network call, stores the raw
+ *    Promise in the map, and returns a `.then(clone)` chain so the
+ *    original `Response` body stream is never consumed by anyone.
+ * 2. Subsequent callers for K (while the first is still pending) →
+ *    attach their own `.then(clone)` to the same shared Promise, each
+ *    receiving an independent cloned `Response`.
+ * 3. Once the shared Promise settles the entry is deleted, so the *next*
+ *    caller after settlement triggers a fresh network request.
+ *
+ * Response cloning
+ * ----------------
+ * `fetch()` returns a `Response` whose body is a one-time-readable stream.
+ * If two callers received the *same* `Response` object, whichever reads
+ * `.json()` / `.text()` first would disturb the body for the other.
+ * To avoid this, the raw result is kept in the inflight map and every
+ * caller — including the first one — receives `response.clone()`, leaving
+ * the stored original unconsumed and safe to clone again.
+ */
+export class RequestDeduplicator {
+    /** Stores the raw (un-cloned) shared Promise for each in-flight key. */
+    inflight = new Map();
+    keyFn;
+    constructor(keyFn) {
+        this.keyFn = keyFn ?? defaultKeyFn;
+    }
+    /**
+     * Execute `fetcher` if no identical request is already in-flight,
+     * otherwise attach to the existing Promise.  In either case the caller
+     * receives `Response.clone()` so body streams are independent.
+     *
+     * @param url     - Same value passed to the outer resilientFetch.
+     * @param options - Same value passed to the outer resilientFetch.
+     * @param fetcher - A thunk that performs the actual network call.
+     */
+    execute(url, options, fetcher) {
+        const key = this.keyFn(url, options);
+        // null means: "skip deduplication for this request"
+        if (key === null) {
+            return fetcher();
+        }
+        if (this.inflight.has(key)) {
+            // Attach to the existing in-flight promise and return a fresh clone
+            // so this caller's Response stream is fully independent.
+            return this.inflight.get(key).then(cloneIfResponse);
+        }
+        const raw = fetcher().finally(() => {
+            this.inflight.delete(key);
+        });
+        this.inflight.set(key, raw);
+        // The first caller also gets a clone so the raw result stored in the
+        // map is never body-consumed, keeping it safe to clone for latecomers.
+        return raw.then(cloneIfResponse);
+    }
+    /** Number of in-flight deduplicated requests. Useful for tests. */
+    get size() {
+        return this.inflight.size;
+    }
+}
+//# sourceMappingURL=dedup.js.map

package/dist/dedup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup.js","sourceRoot":"","sources":["../src/dedup.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,YAAY,GAAuB,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;AAEjE;;;;GAIG;AACH,SAAS,eAAe,CAAI,MAAS;IACnC,IAAI,MAAM,YAAY,QAAQ,EAAE,CAAC;QAC/B,OAAO,MAAM,CAAC,KAAK,EAAkB,CAAC;IACxC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,mBAAmB;IAC9B,wEAAwE;IACvD,QAAQ,GAAkC,IAAI,GAAG,EAAE,CAAC;IACpD,KAAK,CAAqB;IAE3C,YAAY,KAA0B;QACpC,IAAI,CAAC,KAAK,GAAG,KAAK,IAAI,YAAY,CAAC;IACrC,CAAC;IAED;;;;;;;;OAQG;IACH,OAAO,CACL,GAAiB,EACjB,OAAgC,EAChC,OAAyB;QAEzB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAErC,oDAAoD;QACpD,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACjB,OAAO,OAAO,EAAE,CAAC;QACnB,CAAC;QAED,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,oEAAoE;YACpE,yDAAyD;YACzD,OAAQ,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAgB,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QACtE,CAAC;QAED,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YACjC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAE5B,qEAAqE;QACrE,uEAAuE;QACvE,OAAO,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IACnC,CAAC;IAED,mEAAmE;IACnE,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC5B,CAAC;CACF"}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoB,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAUpE,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,YAAY,EAAE,oBAAoB,CAAC,CAAC,CAAC,IAMzE,KAAK,MAAM,GAAG,GAAG,EACjB,UAAU,WAAW,KACpB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC,CAyEzB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoB,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAWpE,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,YAAY,EAAE,oBAAoB,CAAC,CAAC,CAAC,IASzE,KAAK,MAAM,GAAG,GAAG,EACjB,UAAU,WAAW,KACpB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC,CAuFzB"}

package/dist/index.js

@@ -1,6 +1,7 @@
 import { CircuitBreakerState } from "./state.js";
 import { calculateBackoff, sleep } from "./utils/backoff.js";
 import { CircuitOpenError } from "./types.js";
+import { RequestDeduplicator } from "./dedup.js";
 const BACKOFF_DEFAULTS = {
     baseDelay: 100,
     maxDelay: 30_000,
@@ -11,6 +12,9 @@ export function createResilientFetch(globalConfig) {
     const backoffConfig = { ...BACKOFF_DEFAULTS, ...globalConfig.backoff };
     const retryOn = globalConfig.retryOn ?? DEFAULT_RETRY_ON;
     const breaker = new CircuitBreakerState(globalConfig.circuitBreaker);
+    const deduplicator = globalConfig.deduplication
+        ? new RequestDeduplicator(globalConfig.deduplication.keyFn)
+        : null;
     return async function resilientFetch(url, options) {
         const domain = new URL(url).hostname;
         // Block before any network IO if the circuit is OPEN.
@@ -20,58 +24,69 @@ export function createResilientFetch(globalConfig) {
             }
             throw new CircuitOpenError(domain);
         }
-        let lastError;
-        for (let attempt = 0; attempt <= backoffConfig.maxRetries; attempt++) {
-            try {
-                const response = await fetch(url, options);
-                // fetch() resolves for any HTTP status. Retryable codes need to be
-                // treated as failures manually.
-                if (retryOn.includes(response.status)) {
-                    breaker.recordFailure(domain);
-                    if (attempt < backoffConfig.maxRetries) {
-                        await sleep(calculateBackoff(attempt, backoffConfig));
-                        continue;
+        // The core fetch-with-retry logic extracted into a thunk so the
+        // deduplicator can decide whether to run it or share an existing Promise.
+        const executeRequest = () => {
+            let lastError;
+            const run = async () => {
+                for (let attempt = 0; attempt <= backoffConfig.maxRetries; attempt++) {
+                    try {
+                        const response = await fetch(url, options);
+                        // fetch() resolves for any HTTP status. Retryable codes need to be
+                        // treated as failures manually.
+                        if (retryOn.includes(response.status)) {
+                            breaker.recordFailure(domain);
+                            if (attempt < backoffConfig.maxRetries) {
+                                await sleep(calculateBackoff(attempt, backoffConfig));
+                                continue;
+                            }
+                            return response;
+                        }
+                        if (response.status >= 400 && globalConfig.fallbackOnNonRetryable) {
+                            const message = `Non-retryable HTTP error: ${response.status}${response.statusText ? ' ' + response.statusText : ''}`;
+                            if (globalConfig.onNonRetryableError) {
+                                globalConfig.onNonRetryableError(response.status, message);
+                            }
+                            else if (typeof window !== 'undefined') {
+                                window.alert(message);
+                            }
+                            else {
+                                console.error(message);
+                            }
+                            breaker.recordSuccess(domain);
+                            if (globalConfig.fallback !== undefined) {
+                                return globalConfig.fallback;
+                            }
+                            return new Response(JSON.stringify({
+                                error: true,
+                                status: response.status,
+                                message,
+                            }), {
+                                status: response.status,
+                                statusText: response.statusText,
+                                headers: { "Content-Type": "application/json" }
+                            });
+                        }
+                        breaker.recordSuccess(domain);
+                        return response;
                     }
-                    return response;
-                }
-                if (response.status >= 400 && globalConfig.fallbackOnNonRetryable) {
-                    const message = `Non-retryable HTTP error: ${response.status}${response.statusText ? ' ' + response.statusText : ''}`;
-                    if (globalConfig.onNonRetryableError) {
-                        globalConfig.onNonRetryableError(response.status, message);
-                    }
-                    else if (typeof window !== 'undefined') {
-                        window.alert(message);
-                    }
-                    else {
-                        console.error(message);
-                    }
-                    breaker.recordSuccess(domain);
-                    if (globalConfig.fallback !== undefined) {
-                        return globalConfig.fallback;
+                    catch (err) {
+                        lastError = err;
+                        breaker.recordFailure(domain);
+                        // Don't sleep after the final attempt
+                        if (attempt < backoffConfig.maxRetries) {
+                            await sleep(calculateBackoff(attempt, backoffConfig));
+                        }
                     }
-                    return new Response(JSON.stringify({
-                        error: true,
-                        status: response.status,
-                        message,
-                    }), {
-                        status: response.status,
-                        statusText: response.statusText,
-                        headers: { "Content-Type": "application/json" }
-                    });
                 }
-                breaker.recordSuccess(domain);
-                return response;
-            }
-            catch (err) {
-                lastError = err;
-                breaker.recordFailure(domain);
-                // Don't sleep after the final attempt
-                if (attempt < backoffConfig.maxRetries) {
-                    await sleep(calculateBackoff(attempt, backoffConfig));
-                }
-            }
+                throw lastError;
+            };
+            return run();
+        };
+        if (deduplicator) {
+            return deduplicator.execute(url, options, executeRequest);
         }
-        throw lastError;
+        return executeRequest();
     };
 }
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -1,4 +1,18 @@
 export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+/**
+ * Optional function that derives a cache key from a request.
+ * Defaults to `url.toString()` when not provided.
+ * Return `null` to opt this specific request out of deduplication.
+ */
+export type DeduplicationKeyFn = (url: string | URL, options?: RequestInit) => string | null;
+export interface DeduplicationConfig {
+    /**
+     * Custom function to compute the deduplication key.
+     * Receives the same (url, options) passed to resilientFetch.
+     * Defaults to the stringified URL (method-agnostic).
+     */
+    keyFn?: DeduplicationKeyFn;
+}
 export interface CircuitEntry {
     state: CircuitState;
     failureCount: number;
@@ -20,6 +34,11 @@ export interface ResilientFetchConfig<T = unknown> {
     retryOn?: number[];
     fallbackOnNonRetryable?: boolean;
     onNonRetryableError?: (status: number, message: string) => void;
+    /**
+     * When set, enables request deduplication.
+     * Pass an empty object `{}` to activate with the default key function.
+     */
+    deduplication?: DeduplicationConfig;
 }
 export declare class CircuitOpenError extends Error {
     readonly domain: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAG3D,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,YAAY,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAGD,MAAM,WAAW,oBAAoB,CAAC,CAAC,GAAG,OAAO;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IACjC,cAAc,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC/C,QAAQ,CAAC,EAAE,CAAC,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjE;AAGD,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM;CAO3B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,OAAO,CAAC,EAAE,WAAW,KAClB,MAAM,GAAG,IAAI,CAAC;AAEnB,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,KAAK,CAAC,EAAE,kBAAkB,CAAC;CAC5B;AAGD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,YAAY,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAGD,MAAM,WAAW,oBAAoB,CAAC,CAAC,GAAG,OAAO;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IACjC,cAAc,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC/C,QAAQ,CAAC,EAAE,CAAC,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChE;;;OAGG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC;CACrC;AAGD,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM;CAO3B"}

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA8BA,iEAAiE;AACjE,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,MAAM,CAAS;IAExB,YAAY,MAAc;QACxB,KAAK,CAAC,uCAAuC,MAAM,EAAE,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,kEAAkE;QAClE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAsDA,iEAAiE;AACjE,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,MAAM,CAAS;IAExB,YAAY,MAAc;QACxB,KAAK,CAAC,uCAAuC,MAAM,EAAE,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,kEAAkE;QAClE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codingaryan/smoothapi",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "API resilience library — exponential backoff and circuit breaker for fetch",
   "type": "module",
   "main": "./dist/index.js",