From 14c2b70eaf3ce57bcff46ae9ae93c16a57b5702a Mon Sep 17 00:00:00 2001
From: Kaustav Paul <paulkaustav0@gmail.com>
Date: Sun, 11 Oct 2026 15:27:30 +0530
Subject: [PATCH] docs: add Request Deduplication section and example to main
 README

---
 README.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/README.md b/README.md
index ba2126b..790f877 100644
--- a/README.md
+++ b/README.md
@@ -118,6 +118,40 @@ Explore production-grade examples in the [`/examples`](./examples) directory:
 - **Request Deduplication:** Merging concurrent API calls.
 - **Chaos Testing:** Testing fault tolerance against the built-in [Express Chaos Server](./sandbox).
 
+### 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 and prevents redundant work during bursts of traffic.
+
+This feature is covered in the TypeScript package documentation at [packages/smooth-api-ts/README.md](./packages/smooth-api-ts/README.md).
+
+```ts
+import { createSmoothFetch } from '@codingaryan/smoothapi';
+
+const fetchWithRetry = createSmoothFetch({
+  deduplication: {} // Empty object activates deduplication
+});
+
+// All three calls share a single network request
+const [a, b, c] = await Promise.all([
+  fetchWithRetry('https://api.example.com/users/1'),
+  fetchWithRetry('https://api.example.com/users/1'),
+  fetchWithRetry('https://api.example.com/users/1'),
+]);
+```
+
+```ts
+const fetchWithRetry = createSmoothFetch({
+  deduplication: {
+    // Deduplicate by method + URL (ignores headers/body)
+    keyFn: (url, options) => `${options?.method ?? 'GET'}:${url.toString()}`
+  }
+});
+```
+
+- **Default behavior:** Deduplicates by URL only (method-agnostic). Concurrent GETs to the same URL are merged.
+- **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.
+
 ---
 
 ## Design Philosophy