From aff2f29a09cc9b3f1d6dcae1c441d3d184d87a39 Mon Sep 17 00:00:00 2001
From: tawseefnabi <tawseefnabi9@gamil.com>
Date: Thu, 7 Aug 2025 16:04:50 +0530
Subject: [PATCH 1/2] docs: add Cache Interceptor example to README

Add a comprehensive example showing how to use the Cache Interceptor with Fetch,
including configuration options and usage patterns.

Refs: #4283
---
 README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/README.md b/README.md
index eb69c0ca8f4..0cde31eb9d3 100644
--- a/README.md
+++ b/README.md
@@ -166,6 +166,8 @@ Installing undici as a module allows you to use a newer version than what's bund
 
 ## Quick Start
 
+### Basic Request
+
 ```js
 import { request } from 'undici'
 
@@ -184,6 +186,53 @@ for await (const data of body) { console.log('data', data) }
 console.log('trailers', trailers)
 ```
 
+### Using Cache Interceptor
+
+Undici provides a powerful HTTP caching interceptor that follows HTTP caching best practices. Here's how to use it:
+
+```js
+import { fetch, Agent, interceptors } from 'undici';
+
+// Create a client with cache interceptor
+const client = new Agent().compose(interceptors.cache({
+  // Optional: Configure cache store (defaults to MemoryCacheStore)
+  store: new interceptors.cacheStores.MemoryCacheStore({
+    maxSize: 100 * 1024 * 1024, // 100MB
+    maxCount: 1000,
+    maxEntrySize: 5 * 1024 * 1024 // 5MB
+  }),
+  
+  // Optional: Specify which HTTP methods to cache (default: ['GET', 'HEAD'])
+  methods: ['GET', 'HEAD']
+}));
+
+// Set the global dispatcher to use our caching client
+setGlobalDispatcher(client);
+
+// Now all fetch requests will use the cache
+async function getData() {
+  const response = await fetch('https://api.example.com/data', {
+    // Cache control can be set per-request
+    headers: {
+      'Cache-Control': 'max-age=60' // Cache for 60 seconds
+    }
+  });
+  return response.json();
+}
+
+// First request - fetches from origin
+const data1 = await getData();
+
+// Second request - served from cache if within max-age
+const data2 = await getData();
+```
+
+#### Key Features:
+- **Automatic Caching**: Respects `Cache-Control` and `Expires` headers
+- **Validation**: Supports `ETag` and `Last-Modified` validation
+- **Storage Options**: In-memory or persistent SQLite storage
+- **Flexible**: Configure cache size, TTL, and more
+
 ## Global Installation
 
 Undici provides an `install()` function to add all WHATWG fetch classes to `globalThis`, making them available globally:

From 8441985f2686fcd9524e862d6461e242e47f4bf7 Mon Sep 17 00:00:00 2001
From: tawseefnabi <tawseefnabi9@gamil.com>
Date: Fri, 8 Aug 2025 15:07:05 +0530
Subject: [PATCH 2/2] docs: remove misleading Cache-Control header from request
 example

---
 README.md | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 0cde31eb9d3..406b6618f78 100644
--- a/README.md
+++ b/README.md
@@ -211,12 +211,9 @@ setGlobalDispatcher(client);
 
 // Now all fetch requests will use the cache
 async function getData() {
-  const response = await fetch('https://api.example.com/data', {
-    // Cache control can be set per-request
-    headers: {
-      'Cache-Control': 'max-age=60' // Cache for 60 seconds
-    }
-  });
+  const response = await fetch('https://api.example.com/data');
+  // The server should set appropriate Cache-Control headers in the response
+  // which the cache will respect based on the cache policy
   return response.json();
 }