fix: implement proper stale-while-revalidate behavior per RFC 5861 (#4492)

* fix: implement proper stale-while-revalidate behavior per RFC 5861

The stale-while-revalidate cache directive was not working as intended.
Instead of returning stale content immediately and revalidating in the
background, it was performing synchronous revalidation, defeating the
primary purpose of reducing latency.

This fix:
- Returns stale content immediately when within the stale-while-revalidate window
- Performs background revalidation asynchronously to update the cache
- Updates tests to reflect the correct RFC 5861 behavior

Fixes #4471

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: Matteo Collina <hello@matteocollina.com>

* test: use timers/promises for sleep instead of creating promises

Replace manual Promise creation with setTimeout from timers/promises
for cleaner and more idiomatic async delays in tests.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: Matteo Collina <hello@matteocollina.com>

* fix: use process.nextTick instead of setImmediate for background revalidation

setImmediate doesn't work properly with fake timers in tests, causing
background revalidation to not trigger. process.nextTick works correctly
with both real time and fake timers.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: Matteo Collina <hello@matteocollina.com>

* Update cache.js

Co-authored-by: Aras Abbasi <aras.abbasi@googlemail.com>

---------

Signed-off-by: Matteo Collina <hello@matteocollina.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Aras Abbasi <aras.abbasi@googlemail.com>

Author: 3 people

lib/interceptor/cache.js

@@ -56,6 +56,22 @@ function needsRevalidation (result, cacheControlDirectives) {
   return false
 }
 
+/**
+ * Check if we're within the stale-while-revalidate window for a stale response
+ * @param {import('../../types/cache-interceptor.d.ts').default.GetResult} result
+ * @returns {boolean}
+ */
+function withinStaleWhileRevalidateWindow (result) {
+  const staleWhileRevalidate = result.cacheControlDirectives?.['stale-while-revalidate']
+  if (!staleWhileRevalidate) {
+    return false
+  }
+
+  const now = Date.now()
+  const staleWhileRevalidateExpiry = result.staleAt + (staleWhileRevalidate * 1000)
+  return now <= staleWhileRevalidateExpiry
+}
+
 /**
  * @param {DispatchFn} dispatch
  * @param {import('../../types/cache-interceptor.d.ts').default.CacheHandlerOptions} globalOpts
@@ -231,6 +247,51 @@ function handleResult (
       return dispatch(opts, new CacheHandler(globalOpts, cacheKey, handler))
     }
 
+    // RFC 5861: If we're within stale-while-revalidate window, serve stale immediately
+    // and revalidate in background
+    if (withinStaleWhileRevalidateWindow(result)) {
+      // Serve stale response immediately
+      sendCachedValue(handler, opts, result, age, null, true)
+
+      // Start background revalidation (fire-and-forget)
+      queueMicrotask(() => {
+        let headers = {
+          ...opts.headers,
+          'if-modified-since': new Date(result.cachedAt).toUTCString()
+        }
+
+        if (result.etag) {
+          headers['if-none-match'] = result.etag
+        }
+
+        if (result.vary) {
+          headers = {
+            ...headers,
+            ...result.vary
+          }
+        }
+
+        // Background revalidation - update cache if we get new data
+        dispatch(
+          {
+            ...opts,
+            headers
+          },
+          new CacheHandler(globalOpts, cacheKey, {
+            // Silent handler that just updates the cache
+            onRequestStart () {},
+            onRequestUpgrade () {},
+            onResponseStart () {},
+            onResponseData () {},
+            onResponseEnd () {},
+            onResponseError () {}
+          })
+        )
+      })
+
+      return true
+    }
+
     let withinStaleIfErrorThreshold = false
     const staleIfErrorExpiry = result.cacheControlDirectives['stale-if-error'] ?? reqCacheControl?.['stale-if-error']
     if (staleIfErrorExpiry) {