Add support for swr with revalidateTag

.changeset/slick-crabs-hear.md

@@ -0,0 +1,13 @@
+---
+"@opennextjs/aws": minor
+---
+
+Add support for stale-while-revalidate in revalidateTag
+
+Introduces a new methods in the tag cache (hasBeenStale, optional), both for the original and the next mode tag cache, mandatory to make swr work.
+
+It also introduces a RequestCache utils that can be used to cache things scoped to a request (stored in the OpenNext internal AsyncLocalStorage context)
+
+### BREAKING CHANGE
+
+`writeTags` for the tag cache signature has changed to `writeTags(tags: NextModeTagCacheWriteInput[]): Promise<void>;` for Next mode, and `writeTags(tags: OriginalTagCacheWriteInput[]): Promise<void>;` for the original mode.

examples/app-router/app/api/revalidate-tag-stale/route.ts

@@ -0,0 +1,10 @@
+import { revalidateTag } from "next/cache";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  // Revalidate with expire:10 to mark the tag as stale immediately and set expiry to 10 seconds later
+  revalidateTag("revalidate-stale", { expire: 10 });
+
+  return new Response("ok");
+}

examples/app-router/app/revalidate-tag/stale/page.tsx

@@ -0,0 +1,20 @@
+import { unstable_cache } from "next/cache";
+
+const getCachedTime = unstable_cache(
+  async () => new Date().toISOString(),
+  ["stale-revalidate-time"],
+  {
+    tags: ["revalidate-stale"],
+    // Long revalidate time so the cache only expires via revalidateTag
+    revalidate: 3600,
+  },
+);
+
+export default async function StaleRevalidateTag() {
+  const cachedTime = await getCachedTime();
+  return (
+    <div>
+      <p data-testid="cached-time">Cached time: {cachedTime}</p>
+    </div>
+  );
+}

packages/open-next/src/adapters/cache.ts

@@ -3,7 +3,12 @@ import type {
   IncrementalCacheContext,
   IncrementalCacheValue,
 } from "types/cache";
-import { getTagsFromValue, hasBeenRevalidated, writeTags } from "utils/cache";
+import {
+  getTagsFromValue,
+  hasBeenRevalidated,
+  hasBeenStale,
+  writeTags,
+} from "utils/cache";
 import { isBinaryContentType } from "../utils/binary";
 import { debug, error, warn } from "./logger";
 
@@ -96,8 +101,12 @@ export default class Cache {
         }
       }
 
+      const _isStale = cachedEntry.shouldBypassTagCache
+        ? false
+        : await hasBeenStale(key, _tags, _lastModified);
+
       return {
-        lastModified: _lastModified,
+        lastModified: _isStale ? 1 : _lastModified,
         value: cachedEntry.value,
       } as CacheHandlerValue;
     } catch (e) {
@@ -119,15 +128,20 @@ export default class Cache {
 
       const meta = cacheData.meta;
       const tags = getTagsFromValue(cacheData);
-      const _lastModified = cachedEntry.lastModified ?? Date.now();
+      let _lastModified = cachedEntry.lastModified ?? Date.now();
       const _hasBeenRevalidated = cachedEntry.shouldBypassTagCache
         ? false
         : await hasBeenRevalidated(key, tags, cachedEntry);
       if (_hasBeenRevalidated) return null;
 
+      const _isStale = cachedEntry.shouldBypassTagCache
+        ? false
+        : await hasBeenStale(key, tags, _lastModified);
+
       const store = globalThis.__openNextAls.getStore();
       if (store) {
-        store.lastModified = _lastModified;
+        store.lastModified = _isStale ? 1 : _lastModified;
+        _lastModified = store.lastModified;
       }
 
       if (cacheData?.type === "route") {
@@ -333,7 +347,10 @@ export default class Cache {
     }
   }
 
-  public async revalidateTag(tags: string | string[]) {
+  public async revalidateTag(
+    tags: string | string[],
+    durations?: { expire?: number },
+  ) {
     const config = globalThis.openNextConfig.dangerous;
     if (config?.disableTagCache || config?.disableIncrementalCache) {
       return;
@@ -347,7 +364,27 @@ export default class Cache {
       if (globalThis.tagCache.mode === "nextMode") {
         const paths = (await globalThis.tagCache.getPathsByTags?.(_tags)) ?? [];
 
-        await writeTags(_tags);
+        const now = Date.now();
+        const tagsToWrite = _tags.map((tag) => {
+          if (durations) {
+            // Use provided durations
+            return {
+              tag,
+              stale: now,
+              expiry:
+                durations.expire !== undefined
+                  ? now + durations.expire * 1000
+                  : undefined,
+            };
+          }
+          // Default behavior: immediate expiration
+          return {
+            tag,
+            expiry: now,
+          };
+        });
+
+        await writeTags(tagsToWrite);
         if (paths.length > 0) {
           // TODO: we should introduce a new method in cdnInvalidationHandler to invalidate paths by tags for cdn that supports it
           // It also means that we'll need to provide the tags used in every request to the wrapper or converter.
@@ -373,10 +410,26 @@ export default class Cache {
         // Find all keys with the given tag
         const paths = await globalThis.tagCache.getByTag(tag);
         debug("Items", paths);
-        const toInsert = paths.map((path) => ({
-          path,
-          tag,
-        }));
+        const now = Date.now();
+        const toInsert = paths.map((path) => {
+          const baseEntry = { path, tag };
+          if (durations) {
+            // Use provided durations
+            return {
+              ...baseEntry,
+              stale: now,
+              expiry:
+                durations.expire !== undefined
+                  ? now + durations.expire * 1000
+                  : undefined,
+            };
+          }
+          // Default behavior: immediate expiration
+          return {
+            ...baseEntry,
+            expiry: now,
+          };
+        });
 
         // If the tag is a soft tag, we should also revalidate the hard tags
         if (tag.startsWith(SOFT_TAG_PREFIX)) {
@@ -391,10 +444,23 @@ export default class Cache {
               const _paths = await globalThis.tagCache.getByTag(hardTag);
               debug({ hardTag, _paths });
               toInsert.push(
-                ..._paths.map((path) => ({
-                  path,
-                  tag: hardTag,
-                })),
+                ..._paths.map((path) => {
+                  const baseEntry = { path, tag: hardTag };
+                  if (durations) {
+                    return {
+                      ...baseEntry,
+                      stale: now,
+                      expiry:
+                        durations.expire !== undefined
+                          ? now + durations.expire * 1000
+                          : undefined,
+                    };
+                  }
+                  return {
+                    ...baseEntry,
+                    expiry: now,
+                  };
+                }),
               );
             }
           }

packages/open-next/src/adapters/composable-cache.ts

@@ -1,6 +1,6 @@
 import type { ComposableCacheEntry, ComposableCacheHandler } from "types/cache";
-import type { CacheValue } from "types/overrides";
-import { writeTags } from "utils/cache";
+import type { CacheValue, OriginalTagCache } from "types/overrides";
+import { hasBeenStale, writeTags } from "utils/cache";
 import { fromReadableStream, toReadableStream } from "utils/stream";
 import { debug } from "./logger";
 
@@ -34,6 +34,7 @@ export default {
       debug("composable cache result", result);
 
       // We need to check if the tags associated with this entry has been revalidated
+      let revalidate = result.value.revalidate;
       if (
         globalThis.tagCache.mode === "nextMode" &&
         result.value.tags.length > 0
@@ -45,6 +46,18 @@ export default {
               result.lastModified,
             );
         if (hasBeenRevalidated) return undefined;
+
+        // Check if tags are stale – entry is valid but needs background revalidation
+        const isStale = result.shouldBypassTagCache
+          ? false
+          : await hasBeenStale(
+              cacheKey,
+              result.value.tags,
+              result.lastModified,
+            );
+        if (isStale) {
+          revalidate = -1;
+        }
       } else if (
         globalThis.tagCache.mode === "original" ||
         globalThis.tagCache.mode === undefined
@@ -56,10 +69,23 @@ export default {
               result.lastModified,
             )) === -1;
         if (hasBeenRevalidated) return undefined;
+
+        // Check if tags are stale – entry is valid but needs background revalidation
+        const isStale = result.shouldBypassTagCache
+          ? false
+          : await hasBeenStale(
+              cacheKey,
+              result.value.tags,
+              result.lastModified,
+            );
+        if (isStale) {
+          revalidate = -1;
+        }
       }
 
       return {
         ...result.value,
+        revalidate,
         value: toReadableStream(result.value.value),
       };
     } catch (e) {
@@ -149,4 +175,70 @@ export default {
     // This function does absolutely nothing
     return;
   },
+
+  /**
+   * Added in Next.js 16. Updates tags with optional stale/expire durations.
+   * Mirrors the logic in `Cache.revalidateTag` but without CDN invalidation
+   * since composable cache keys are not URL paths.
+   *
+   * When `durations` is provided, marks tags as stale immediately and optionally
+   * sets an expiry timestamp. When omitted, immediately expires tags (no grace period).
+   */
+  async updateTags(tags: string[], durations?: { expire?: number }) {
+    const config = globalThis.openNextConfig.dangerous;
+    if (config?.disableTagCache || config?.disableIncrementalCache) {
+      return;
+    }
+    if (tags.length === 0) {
+      return;
+    }
+    try {
+      const now = Date.now();
+      if (globalThis.tagCache.mode === "nextMode") {
+        const tagsToWrite = tags.map((tag) => {
+          if (durations) {
+            return {
+              tag,
+              stale: now,
+              expiry:
+                durations.expire !== undefined
+                  ? now + durations.expire * 1000
+                  : undefined,
+            };
+          }
+          // Default: immediate expiry, no grace period
+          return { tag, expiry: now };
+        });
+        await writeTags(tagsToWrite);
+      } else {
+        // Original mode: resolve tag → path mappings first
+        const originalTagCache = globalThis.tagCache as OriginalTagCache;
+        const pathsPerTag = await Promise.all(
+          tags.map(async (tag) => {
+            const paths = await originalTagCache.getByTag(tag);
+            return paths.map((path: string) => {
+              if (durations) {
+                return {
+                  path,
+                  tag,
+                  stale: now,
+                  expiry:
+                    durations.expire !== undefined
+                      ? now + durations.expire * 1000
+                      : undefined,
+                };
+              }
+              return { path, tag, expiry: now };
+            });
+          }),
+        );
+        const toWrite = pathsPerTag.flat();
+        if (toWrite.length > 0) {
+          await writeTags(toWrite);
+        }
+      }
+    } catch (e) {
+      debug("Failed to update tags", e);
+    }
+  },
 } satisfies ComposableCacheHandler;

packages/open-next/src/adapters/dynamo-provider.ts

@@ -16,6 +16,12 @@ type DataType = {
   revalidatedAt: {
     N: string;
   };
+  stale?: {
+    N: string;
+  };
+  expiry?: {
+    N: string;
+  };
 };
 
 export interface InitializationFunctionEvent {
@@ -63,6 +69,8 @@ async function insert(
     tag: item.tag.S,
     path: item.path.S,
     revalidatedAt: Number.parseInt(item.revalidatedAt.N),
+    ...(item.stale && { stale: Number.parseInt(item.stale.N) }),
+    ...(item.expiry && { expiry: Number.parseInt(item.expiry.N) }),
   }));
 
   await tagCache.writeTags(parsedData);

packages/open-next/src/build/compileCache.ts

@@ -23,6 +23,12 @@ export function compileCache(
     "15.0.0",
   );
 
+  const isAfter16 = buildHelper.compareSemver(
+    options.nextVersion,
+    ">=",
+    "16.0.0",
+  );
+
   // Normal cache
   buildHelper.esbuildSync(
     {
@@ -40,6 +46,7 @@ export function compileCache(
             config.dangerous?.disableTagCache ?? false
           };`,
           `globalThis.isNextAfter15 = ${isAfter15};`,
+          `globalThis.isNextAfter16 = ${isAfter16};`,
         ].join(""),
       },
     },
@@ -70,6 +77,7 @@ export function compileCache(
             config.dangerous?.disableTagCache ?? false
           };`,
           `globalThis.isNextAfter15 = ${isAfter15};`,
+          `globalThis.isNextAfter16 = ${isAfter16};`,
         ].join(""),
       },
     },