@netlify/cache 3.3.4 → 3.4.0

package/dist/main.cjs

@@ -29,6 +29,7 @@ __export(main_exports, {
   caches: () => caches,
   fetchWithCache: () => fetchWithCache,
   getCacheStatus: () => getCacheStatus,
+  needsRevalidation: () => needsRevalidation,
   setCacheHeaders: () => setCacheHeaders
 });
 module.exports = __toCommonJS(main_exports);
@@ -266,6 +267,19 @@ var parseCacheStatusValues = (cacheStatusValues) => {
   }
   return cacheStatus;
 };
+var needsRevalidation = (response) => {
+  const header = response.headers.get(CacheStatus);
+  if (!header) {
+    return false;
+  }
+  for (const value of header.split(",")) {
+    const { attributes, name } = parseCacheStatusValue(value);
+    if (name === CACHE_DURABLE && attributes.detail === "client-revalidate") {
+      return true;
+    }
+  }
+  return false;
+};
 var getCacheStatus = (input) => {
   if (typeof input === "string") {
     return parseCacheStatusValues(input);
@@ -336,6 +350,19 @@ var fetchWithCache = async (requestOrURL, optionsOrCacheSettings, cacheOptionsPa
   }
   const cached = await cache.match(request);
   if (cached) {
+    if (needsRevalidation(cached)) {
+      const { fetch: fetchFn = globalThis.fetch } = cacheOptions;
+      const revalidation = performBackgroundRevalidation(request, cache, cacheSettings, fetchFn);
+      if (onCachePut) {
+        await onCachePut(revalidation);
+      } else {
+        const netlifyGlobal = globalThis.Netlify;
+        const requestContext = netlifyGlobal?.context;
+        if (requestContext) {
+          requestContext.waitUntil(revalidation);
+        }
+      }
+    }
     return cached;
   }
   const { fetch = globalThis.fetch } = cacheOptions;
@@ -362,6 +389,19 @@ var fetchWithCache = async (requestOrURL, optionsOrCacheSettings, cacheOptionsPa
   }
   return clientResponse;
 };
+var performBackgroundRevalidation = async (request, cache, cacheSettings, fetchFn) => {
+  try {
+    const fresh = await fetchFn(request);
+    if (!fresh.body) {
+      return;
+    }
+    const cacheResponse = new Response(fresh.body, fresh);
+    applyHeaders(cacheResponse.headers, cacheHeaders(cacheSettings));
+    await cache.put(request, cacheResponse);
+  } catch (error) {
+    console.warn("`fetchWithCache` has failed to revalidate a stale response:", error);
+  }
+};
 
 // src/constants.ts
 var MINUTE = 60;
@@ -380,5 +420,6 @@ var YEAR = 365 * DAY;
   caches,
   fetchWithCache,
   getCacheStatus,
+  needsRevalidation,
   setCacheHeaders
 });

package/dist/main.d.cts

@@ -129,6 +129,15 @@ type ParseCacheStatus = {
     (headers: Headers): CacheStatus | null;
     (response: Response): CacheStatus | null;
 };
+/**
+ * Returns whether a cached response includes a signal that the client should
+ * perform a background revalidation. This may happen when using the Cache API
+ * with the `stale-while-revalidate` directive, since unlike the regular cache,
+ * the client is the one responsible for explicitly inserting new entries into
+ * the cache. So when this returns `true`, the caller should fetch the resource
+ * and write the fresh response back to the cache with `cache.put()`.
+ */
+declare const needsRevalidation: (response: Response) => boolean;
 /**
  * Retrieves information about how a response has interacted with Netlify's
  * global caching infrastructure, including whether the response has been
@@ -193,4 +202,4 @@ declare const WEEK: number;
  */
 declare const YEAR: number;
 
-export { DAY, HOUR, MINUTE, WEEK, YEAR, cacheHeaders, caches, fetchWithCache, getCacheStatus, setCacheHeaders };
+export { DAY, HOUR, MINUTE, WEEK, YEAR, cacheHeaders, caches, fetchWithCache, getCacheStatus, needsRevalidation, setCacheHeaders };

package/dist/main.d.ts

@@ -129,6 +129,15 @@ type ParseCacheStatus = {
     (headers: Headers): CacheStatus | null;
     (response: Response): CacheStatus | null;
 };
+/**
+ * Returns whether a cached response includes a signal that the client should
+ * perform a background revalidation. This may happen when using the Cache API
+ * with the `stale-while-revalidate` directive, since unlike the regular cache,
+ * the client is the one responsible for explicitly inserting new entries into
+ * the cache. So when this returns `true`, the caller should fetch the resource
+ * and write the fresh response back to the cache with `cache.put()`.
+ */
+declare const needsRevalidation: (response: Response) => boolean;
 /**
  * Retrieves information about how a response has interacted with Netlify's
  * global caching infrastructure, including whether the response has been
@@ -193,4 +202,4 @@ declare const WEEK: number;
  */
 declare const YEAR: number;
 
-export { DAY, HOUR, MINUTE, WEEK, YEAR, cacheHeaders, caches, fetchWithCache, getCacheStatus, setCacheHeaders };
+export { DAY, HOUR, MINUTE, WEEK, YEAR, cacheHeaders, caches, fetchWithCache, getCacheStatus, needsRevalidation, setCacheHeaders };

package/dist/main.js

@@ -231,6 +231,19 @@ var parseCacheStatusValues = (cacheStatusValues) => {
   }
   return cacheStatus;
 };
+var needsRevalidation = (response) => {
+  const header = response.headers.get(CacheStatus);
+  if (!header) {
+    return false;
+  }
+  for (const value of header.split(",")) {
+    const { attributes, name } = parseCacheStatusValue(value);
+    if (name === CACHE_DURABLE && attributes.detail === "client-revalidate") {
+      return true;
+    }
+  }
+  return false;
+};
 var getCacheStatus = (input) => {
   if (typeof input === "string") {
     return parseCacheStatusValues(input);
@@ -301,6 +314,19 @@ var fetchWithCache = async (requestOrURL, optionsOrCacheSettings, cacheOptionsPa
   }
   const cached = await cache.match(request);
   if (cached) {
+    if (needsRevalidation(cached)) {
+      const { fetch: fetchFn = globalThis.fetch } = cacheOptions;
+      const revalidation = performBackgroundRevalidation(request, cache, cacheSettings, fetchFn);
+      if (onCachePut) {
+        await onCachePut(revalidation);
+      } else {
+        const netlifyGlobal = globalThis.Netlify;
+        const requestContext = netlifyGlobal?.context;
+        if (requestContext) {
+          requestContext.waitUntil(revalidation);
+        }
+      }
+    }
     return cached;
   }
   const { fetch = globalThis.fetch } = cacheOptions;
@@ -327,6 +353,19 @@ var fetchWithCache = async (requestOrURL, optionsOrCacheSettings, cacheOptionsPa
   }
   return clientResponse;
 };
+var performBackgroundRevalidation = async (request, cache, cacheSettings, fetchFn) => {
+  try {
+    const fresh = await fetchFn(request);
+    if (!fresh.body) {
+      return;
+    }
+    const cacheResponse = new Response(fresh.body, fresh);
+    applyHeaders(cacheResponse.headers, cacheHeaders(cacheSettings));
+    await cache.put(request, cacheResponse);
+  } catch (error) {
+    console.warn("`fetchWithCache` has failed to revalidate a stale response:", error);
+  }
+};
 
 // src/constants.ts
 var MINUTE = 60;
@@ -344,5 +383,6 @@ export {
   caches,
   fetchWithCache,
   getCacheStatus,
+  needsRevalidation,
   setCacheHeaders
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netlify/cache",
-  "version": "3.3.4",
+  "version": "3.4.0",
   "description": "TypeScript utilities for interacting with the Netlify cache",
   "type": "module",
   "engines": {
@@ -79,6 +79,6 @@
     "vitest": "^3.0.0"
   },
   "dependencies": {
-    "@netlify/runtime-utils": "2.2.1"
+    "@netlify/runtime-utils": "2.3.0"
   }
 }