feat: Update cache key generation to include a whitelist of headers affecting response content

Author: MattCCC

README.md

@@ -1336,14 +1336,52 @@ By default, `fetchff` generates a cache key automatically using a combination of
 | ----------------- | ----------------------------------------------------------------------------------------- | --------------- |
 | `method`          | The HTTP method used for the request (e.g., GET, POST).                                   | `'GET'`         |
 | `url`             | The full request URL, including the base URL and endpoint path.                           | `''`            |
-| `headers`         | Request headers, included as a stringified object.                                        |                 |
+| `headers`         | Request headers, **filtered to include only cache-relevant headers** (see below).         |                 |
 | `body`            | The request payload (for POST, PUT, PATCH, etc.), stringified if it's an object or array. |                 |
 | `credentials`     | Indicates whether credentials (cookies) are included in the request.                      | `'same-origin'` |
 | `params`          | Query parameters serialized into the URL (objects, arrays, etc. are stringified).         |                 |
 | `urlPathParams`   | Dynamic URL path parameters (e.g., `/user/:id`), stringified and encoded.                 |                 |
 | `withCredentials` | Whether credentials (cookies) are included in the request.                                |                 |
 
-These properties are combined and hashed to create a unique cache key for each request. This ensures that requests with different parameters, bodies, or headers are cached separately.
+#### Header Filtering for Cache Keys
+
+To ensure stable cache keys and prevent unnecessary cache misses, `fetchff` only includes headers that affect response content in cache key generation. The following headers are included:
+
+**Content Negotiation:**
+
+- `accept` - Affects response format (JSON, HTML, etc.)
+- `accept-language` - Affects localization of response
+- `accept-encoding` - Affects response compression
+
+**Authentication & Authorization:**
+
+- `authorization` - Affects access to protected resources
+- `x-api-key` - Token-based access control
+- `cookie` - Session-based authentication
+
+**Request Context:**
+
+- `content-type` - Affects how request body is interpreted
+- `origin` - Relevant for CORS or tenant-specific APIs
+- `referer` - May influence API behavior
+- `user-agent` - Only if server returns client-specific content
+
+**Custom Headers:**
+
+- `x-requested-with` - Distinguishes AJAX requests
+- `x-client-id` - Per-client/partner identity
+- `x-tenant-id` - Multi-tenant segmentation
+- `x-user-id` - Explicit user context
+- `x-app-version` - Version-specific behavior
+- `x-feature-flag` - Feature rollout controls
+- `x-device-id` - Device-specific responses
+- `x-platform` - Platform-specific content (iOS, Android, web)
+- `x-session-id` - Session-specific responses
+- `x-locale` - Locale-specific content
+
+Headers like `user-agent`, `accept-encoding`, `connection`, `cache-control`, tracking IDs, and proxy-related headers are **excluded** from cache key generation as they don't affect the actual response content.
+
+These properties are combined and hashed to create a unique cache key for each request. This ensures that requests with different parameters, bodies, or cache-relevant headers are cached separately while maintaining stable cache keys across requests that only differ in non-essential headers. If that does not suffice, you can always use `cacheKey` (string | function) and supply it to particular requests. You can also build your own `cacheKey` function and simply update defaults to reflect it in all requests. Auto key generation would be entirely skipped in such scenarios.
 
 </details>
 

package.json

@@ -73,7 +73,7 @@
     },
     {
       "path": "dist/browser/index.global.js",
-      "limit": "5.5 KB"
+      "limit": "5.6 KB"
     },
     {
       "path": "dist/node/index.js",

src/cache-manager.ts

@@ -25,6 +25,49 @@ const DELIMITER = '|';
 const MIN_LENGTH_TO_HASH = 64;
 const CACHE_KEY_SANITIZE_PATTERN = new RegExp('[^\\w\\-_|]', 'g');
 
+/**
+ * Headers that may affect HTTP response content and should be included in cache key generation.
+ * All header names must be lowercase to match normalized request headers.
+ */
+const CACHE_KEY_HEADER_WHITELIST = new Set([
+  // Content negotiation
+  'accept', // Affects response format (e.g. JSON, HTML)
+  'accept-language', // Affects localization of the response
+  'accept-encoding', // Affects response compression (e.g. gzip, br)
+
+  // Authentication
+  'authorization', // Affects access to protected resources
+
+  // Request body metadata
+  'content-type', // Affects how the request body is interpreted
+
+  // Request context hints
+  'x-requested-with', // Commonly used to distinguish AJAX requests
+
+  // Optional headers
+  'referer', // May influence behavior in some APIs
+  'origin', // Relevant in CORS or tenant-specific APIs
+  'user-agent', // Included only for reason if server returns client-specific content
+
+  // Cookies — only if server uses session-based responses
+  'cookie', // Can fragment cache heavily; use only if necessary
+
+  // Custom headers that may affect response content
+  'x-api-key', // Token-based access, often affects authorization
+  'x-requested-with', // AJAX requests (used historically for distinguishing frontend calls)
+  'x-client-id', // Per-client/partner identity; often used in multi-tenant APIs
+  'x-tenant-id', // Multi-tenant segmentation; often changes response per tenant
+  'x-user-id', // Explicit user context (less common, but may exist)
+
+  'x-app-version', // Used for version-specific behavior (e.g. mobile apps)
+  'x-feature-flag', // Controls feature rollout behavior server-side
+  'x-device-id', // Used when response varies per device/app instance
+  'x-platform', // e.g. 'ios', 'android', 'web' — used in apps that serve different content
+
+  'x-session-id', // Only if backend uses it to affect the response directly (rare)
+  'x-locale', // Sometimes used in addition to or instead of `accept-language`
+]);
+
 /**
  * Generates a unique cache key for a given URL and fetch options, ensuring that key factors
  * like method, headers, body, and other options are included in the cache key.
@@ -83,6 +126,8 @@ export function generateCacheKey(
       obj = headers as Record<string, string>;
     }
 
+    // Filter headers to only include those that affect request identity
+    // Include only headers that affect request identity, not execution behavior
     const keys = Object.keys(obj);
     const len = keys.length;
 
@@ -93,7 +138,9 @@ export function generateCacheKey(
 
     let str = '';
     for (let i = 0; i < len; ++i) {
-      str += keys[i] + ':' + obj[keys[i]] + ';';
+      if (CACHE_KEY_HEADER_WHITELIST.has(keys[i].toLowerCase())) {
+        str += keys[i] + ':' + obj[keys[i]] + ';';
+      }
     }
 
     if (str.length > MIN_LENGTH_TO_HASH) {

test/cache-manager.spec.ts

@@ -85,7 +85,7 @@ describe('Cache Manager', () => {
       } as never);
 
       expect(key).toContain(
-        'GET|httpsapiexamplecomdata|same-origin|1530632817',
+        'GET|httpsapiexamplecomdata|same-origin|accept-encodinggzipdeflatebrcontent-typeapplicationjson',
       );
     });