@opennextjs/cloudflare 1.18.1 → 1.19.0

package/dist/api/durable-objects/sharded-tag-cache.d.ts

@@ -1,9 +1,43 @@
 import { DurableObject } from "cloudflare:workers";
+export type TagData = {
+    revalidatedAt: number;
+    stale: number | null;
+    expire: number | null;
+};
 export declare class DOShardedTagCache extends DurableObject<CloudflareEnv> {
     sql: SqlStorage;
     constructor(state: DurableObjectState, env: CloudflareEnv);
+    getTagData(tags: string[]): Promise<Record<string, TagData>>;
+    /**
+     * @deprecated since v1.19.
+     *
+     * Use `getTagData` instead - no processing should be done in the DO ao allow using the regional cache to cache all the values
+     * for a given tag using a single key.
+     *
+     * Kept for backward compatibility during rolling deploys.
+     */
     getLastRevalidated(tags: string[]): Promise<number>;
+    /**
+     * @deprecated since v1.19.
+     *
+     * Use `getTagData` instead - no processing should be done in the DO ao allow using the regional cache to cache all the values
+     * for a given tag using a single key.
+     *
+     * Kept for backward compatibility during rolling deploys.
+     */
     hasBeenRevalidated(tags: string[], lastModified?: number): Promise<boolean>;
-    writeTags(tags: string[], lastModified: number): Promise<void>;
+    /**
+     * @deprecated since v1.19.
+     *
+     * Use `getTagData` instead - no processing should be done in the DO ao allow using the regional cache to cache all the values
+     * for a given tag using a single key.
+     *
+     * Kept for backward compatibility during rolling deploys.
+     */
     getRevalidationTimes(tags: string[]): Promise<Record<string, number>>;
+    writeTags(tags: Array<string | {
+        tag: string;
+        stale?: number;
+        expire?: number | null;
+    }>, lastModified?: number): Promise<void>;
 }

package/dist/api/durable-objects/sharded-tag-cache.js

@@ -6,41 +6,105 @@ export class DOShardedTagCache extends DurableObject {
         super(state, env);
         this.sql = state.storage.sql;
         state.blockConcurrencyWhile(async () => {
-            this.sql.exec(`CREATE TABLE IF NOT EXISTS revalidations (tag TEXT PRIMARY KEY, revalidatedAt INTEGER)`);
+            // Columns:
+            //   tag           - The cache tag.
+            //   revalidatedAt - Timestamp (ms) when the tag was last revalidated.
+            //   stale         - Timestamp (ms) when the cached entry becomes stale. Added in v1.19.
+            //   expire        - Timestamp (ms) when the cached entry expires. NULL means no expire. Added in v1.19.
+            this.sql.exec(`CREATE TABLE IF NOT EXISTS revalidations (tag TEXT PRIMARY KEY, revalidatedAt INTEGER, stale INTEGER, expire INTEGER DEFAULT NULL)`);
+            // Schema migration: Add `stale` and `expire` columns for existing DO - those have been introduced to support SWR in v1.19
+            try {
+                // SQLite does not support adding multiple columns in a single ALTER TABLE statement.
+                this.sql.exec(`ALTER TABLE revalidations ADD COLUMN stale INTEGER; ALTER TABLE revalidations ADD COLUMN expire INTEGER DEFAULT NULL`);
+            }
+            catch {
+                // The ALTER TABLE statement fails if the columns already exist.
+                // It only means the DO has already been migrated.
+            }
         });
     }
-    async getLastRevalidated(tags) {
+    async getTagData(tags) {
+        if (tags.length === 0)
+            return {};
         try {
             const result = this.sql
-                .exec(`SELECT MAX(revalidatedAt) AS time FROM revalidations WHERE tag IN (${tags.map(() => "?").join(", ")})`, ...tags)
+                .exec(`SELECT tag, revalidatedAt, stale, expire FROM revalidations WHERE tag IN (${tags.map(() => "?").join(", ")})`, ...tags)
                 .toArray();
-            const timeMs = (result[0]?.time ?? 0);
-            debugCache("DOShardedTagCache", `getLastRevalidated tags=${tags} -> time=${timeMs}`);
-            return timeMs;
+            debugCache("DOShardedTagCache", `getTagData tags=${tags} -> ${result.length} results`);
+            return Object.fromEntries(result.map((row) => [
+                row.tag,
+                {
+                    revalidatedAt: (row.revalidatedAt ?? 0),
+                    stale: (row.stale ?? null),
+                    expire: (row.expire ?? null),
+                },
+            ]));
         }
         catch (e) {
             console.error(e);
-            // By default we don't want to crash here, so we return 0
-            return 0;
+            return {};
         }
     }
+    /**
+     * @deprecated since v1.19.
+     *
+     * Use `getTagData` instead - no processing should be done in the DO ao allow using the regional cache to cache all the values
+     * for a given tag using a single key.
+     *
+     * Kept for backward compatibility during rolling deploys.
+     */
+    async getLastRevalidated(tags) {
+        const data = await this.getTagData(tags);
+        const values = Object.values(data);
+        const timeMs = values.length === 0 ? 0 : Math.max(...values.map(({ revalidatedAt }) => revalidatedAt));
+        debugCache("DOShardedTagCache", `getLastRevalidated tags=${tags} -> time=${timeMs}`);
+        return timeMs;
+    }
+    /**
+     * @deprecated since v1.19.
+     *
+     * Use `getTagData` instead - no processing should be done in the DO ao allow using the regional cache to cache all the values
+     * for a given tag using a single key.
+     *
+     * Kept for backward compatibility during rolling deploys.
+     */
     async hasBeenRevalidated(tags, lastModified) {
-        const revalidated = this.sql
-            .exec(`SELECT 1 FROM revalidations WHERE tag IN (${tags.map(() => "?").join(", ")}) AND revalidatedAt > ? LIMIT 1`, ...tags, lastModified ?? Date.now())
-            .toArray().length > 0;
+        const data = await this.getTagData(tags);
+        const lastModifiedOrNowMs = lastModified ?? Date.now();
+        const revalidated = Object.values(data).some(({ revalidatedAt }) => revalidatedAt > lastModifiedOrNowMs);
         debugCache("DOShardedTagCache", `hasBeenRevalidated tags=${tags} -> revalidated=${revalidated}`);
         return revalidated;
     }
-    async writeTags(tags, lastModified) {
-        debugCache("DOShardedTagCache", `writeTags tags=${tags} time=${lastModified}`);
-        tags.forEach((tag) => {
-            this.sql.exec(`INSERT OR REPLACE INTO revalidations (tag, revalidatedAt) VALUES (?, ?)`, tag, lastModified);
-        });
-    }
+    /**
+     * @deprecated since v1.19.
+     *
+     * Use `getTagData` instead - no processing should be done in the DO ao allow using the regional cache to cache all the values
+     * for a given tag using a single key.
+     *
+     * Kept for backward compatibility during rolling deploys.
+     */
     async getRevalidationTimes(tags) {
-        const result = this.sql
-            .exec(`SELECT tag, revalidatedAt FROM revalidations WHERE tag IN (${tags.map(() => "?").join(", ")})`, ...tags)
-            .toArray();
-        return Object.fromEntries(result.map((row) => [row.tag, row.revalidatedAt]));
+        const data = await this.getTagData(tags);
+        return Object.fromEntries(Object.entries(data).map(([tag, { revalidatedAt }]) => [tag, revalidatedAt]));
+    }
+    async writeTags(tags, lastModified) {
+        if (tags.length === 0)
+            return;
+        const nowMs = lastModified ?? Date.now();
+        debugCache("DOShardedTagCache", `writeTags tags=${JSON.stringify(tags)} time=${nowMs}`);
+        if (typeof tags[0] === "string") {
+            // Old call format: writeTags(tags: string[], lastModified: number)
+            for (const tag of tags) {
+                // `expire` defaults to `NULL`
+                this.sql.exec(`INSERT OR REPLACE INTO revalidations (tag, revalidatedAt, stale) VALUES (?, ?, ?)`, tag, nowMs, nowMs);
+            }
+        }
+        else {
+            // New call format: writeTags(tags: Array<{ tag, stale?, expire? }>)
+            for (const entry of tags) {
+                const staleValue = entry.stale ?? nowMs;
+                this.sql.exec(`INSERT OR REPLACE INTO revalidations (tag, revalidatedAt, stale, expire) VALUES (?, ?, ?, ?)`, entry.tag, staleValue, staleValue, entry.expire ?? null);
+            }
+        }
     }
 }

package/dist/api/overrides/tag-cache/d1-next-tag-cache.d.ts

@@ -1,15 +1,33 @@
-import type { NextModeTagCache } from "@opennextjs/aws/types/overrides.js";
+import type { NextModeTagCache, NextModeTagCacheWriteInput } from "@opennextjs/aws/types/overrides.js";
 export declare const NAME = "d1-next-mode-tag-cache";
 export declare const BINDING_NAME = "NEXT_TAG_CACHE_D1";
+/**
+ * Stored value shape for D1 tag entries.
+ *
+ * - revalidatedAt: timestamp in ms of the last revalidation
+ * - stale: timestamp in ms when the tag becomes stale
+ * - expire: timestamp in ms when the tag expires (null means no expiry)
+ */
+type D1TagValue = {
+    revalidatedAt: number;
+    stale: number | null;
+    expire: number | null;
+};
 export declare class D1NextModeTagCache implements NextModeTagCache {
+    #private;
     readonly mode: "nextMode";
     readonly name = "d1-next-mode-tag-cache";
     getLastRevalidated(tags: string[]): Promise<number>;
     hasBeenRevalidated(tags: string[], lastModified?: number): Promise<boolean>;
-    writeTags(tags: string[]): Promise<void>;
+    writeTags(tags: NextModeTagCacheWriteInput[]): Promise<void>;
+    isStale(tags: string[], lastModified?: number): Promise<boolean>;
     private getConfig;
     protected getCacheKey(key: string): string;
     protected getBuildId(): string;
+    /**
+     * @returns request scoped in-memory cache for tag values, or undefined if ALS is not available.
+     */
+    protected getItemsCache(): Map<string, D1TagValue | null> | undefined;
 }
 declare const _default: D1NextModeTagCache;
 export default _default;

package/dist/api/overrides/tag-cache/d1-next-tag-cache.js

@@ -12,17 +12,15 @@ export class D1NextModeTagCache {
             return 0;
         }
         try {
-            const result = await db
-                .prepare(`SELECT MAX(revalidatedAt) AS time FROM revalidations WHERE tag IN (${tags.map(() => "?").join(", ")})`)
-                .bind(...tags.map((tag) => this.getCacheKey(tag)))
-                .run();
-            const timeMs = (result.results[0]?.time ?? 0);
+            const result = await this.#resolveTagValues(tags, db);
+            const revalidations = [...result.values()]
+                .filter((v) => v != null)
+                .map((v) => v.revalidatedAt);
+            const timeMs = revalidations.length === 0 ? 0 : Math.max(...revalidations);
             debugCache("D1NextModeTagCache", `getLastRevalidated tags=${tags} -> ${timeMs}`);
             return timeMs;
         }
         catch (e) {
-            // By default we don't want to crash here, so we return false
-            // We still log the error though so we can debug it
             error(e);
             return 0;
         }
@@ -33,18 +31,21 @@ export class D1NextModeTagCache {
             return false;
         }
         try {
-            const result = await db
-                .prepare(`SELECT 1 FROM revalidations WHERE tag IN (${tags.map(() => "?").join(", ")}) AND revalidatedAt > ? LIMIT 1`)
-                .bind(...tags.map((tag) => this.getCacheKey(tag)), lastModified ?? Date.now())
-                .raw();
-            const revalidated = result.length > 0;
+            const now = Date.now();
+            const result = await this.#resolveTagValues(tags, db);
+            const revalidated = [...result.values()].some((v) => {
+                if (v == null)
+                    return false;
+                const { revalidatedAt, expire } = v;
+                if (expire != null)
+                    return expire <= now && expire > (lastModified ?? 0);
+                return revalidatedAt > (lastModified ?? now);
+            });
             debugCache("D1NextModeTagCache", `hasBeenRevalidated tags=${tags} at=${lastModified} -> ${revalidated}`);
             return revalidated;
         }
         catch (e) {
             error(e);
-            // By default we don't want to crash here, so we return false
-            // We still log the error though so we can debug it
             return false;
         }
     }
@@ -53,15 +54,89 @@ export class D1NextModeTagCache {
         if (isDisabled || tags.length === 0)
             return Promise.resolve();
         const nowMs = Date.now();
-        await db.batch(tags.map((tag) => db
-            .prepare(`INSERT INTO revalidations (tag, revalidatedAt) VALUES (?, ?)`)
-            .bind(this.getCacheKey(tag), nowMs)));
-        debugCache("D1NextModeTagCache", `writeTags tags=${tags} time=${nowMs}`);
+        await db.batch(tags.map((tag) => {
+            const tagStr = typeof tag === "string" ? tag : tag.tag;
+            const stale = typeof tag === "string" ? nowMs : (tag.stale ?? nowMs);
+            const expire = typeof tag === "string" ? null : (tag.expire ?? null);
+            return db
+                .prepare(`INSERT INTO revalidations (tag, revalidatedAt, stale, expire) VALUES (?, ?, ?, ?)`)
+                .bind(this.getCacheKey(tagStr), stale, stale, expire);
+        }));
+        const tagStrings = tags.map((t) => (typeof t === "string" ? t : t.tag));
+        debugCache("D1NextModeTagCache", `writeTags tags=${tagStrings} time=${nowMs}`);
         // TODO: See https://github.com/opennextjs/opennextjs-aws/issues/986
         if (isPurgeCacheEnabled()) {
-            await purgeCacheByTags(tags);
+            await purgeCacheByTags(tagStrings);
         }
     }
+    async isStale(tags, lastModified) {
+        const { isDisabled, db } = this.getConfig();
+        if (isDisabled || tags.length === 0) {
+            return false;
+        }
+        try {
+            const now = Date.now();
+            const result = await this.#resolveTagValues(tags, db);
+            const isStale = [...result.values()].some((v) => {
+                if (v == null)
+                    return false;
+                const { stale, expire } = v;
+                if (stale == null || stale <= (lastModified ?? now))
+                    return false;
+                return expire == null || expire > now;
+            });
+            debugCache("D1NextModeTagCache", `isStale tags=${tags} at=${lastModified} -> ${isStale}`);
+            return isStale;
+        }
+        catch (e) {
+            error(e);
+            return false;
+        }
+    }
+    /**
+     * Resolves tag values from the per-request in-memory cache, falling back to D1 for any misses.
+     *
+     * Results are stored back into the request cache so repeated calls within the same request
+     * avoid duplicate D1 queries.
+     *
+     * @param tags - The tag names to resolve.
+     * @param db - The D1 database binding.
+     * @returns A map of tag name to its D1TagValue (or null if the tag was not found).
+     */
+    async #resolveTagValues(tags, db) {
+        const result = new Map();
+        const uncachedTags = [];
+        const itemsCache = this.getItemsCache();
+        for (const tag of tags) {
+            if (itemsCache?.has(tag)) {
+                result.set(tag, itemsCache.get(tag) ?? null);
+            }
+            else {
+                uncachedTags.push(tag);
+            }
+        }
+        if (uncachedTags.length > 0) {
+            const rows = await db
+                .prepare(`SELECT tag, revalidatedAt, stale, expire FROM revalidations WHERE tag IN (${uncachedTags.map(() => "?").join(", ")})`)
+                .bind(...uncachedTags.map((tag) => this.getCacheKey(tag)))
+                .raw();
+            // Index rows by cache key for lookup.
+            const rowsByKey = new Map(rows.map((row) => [row[0], row]));
+            for (const tag of uncachedTags) {
+                const row = rowsByKey.get(this.getCacheKey(tag));
+                const value = row
+                    ? {
+                        revalidatedAt: row[1] ?? 0,
+                        stale: row[2] ?? null,
+                        expire: row[3] ?? null,
+                    }
+                    : null;
+                itemsCache?.set(tag, value);
+                result.set(tag, value);
+            }
+        }
+        return result;
+    }
     getConfig() {
         const db = getCloudflareContext().env[BINDING_NAME];
         if (!db)
@@ -80,5 +155,12 @@ export class D1NextModeTagCache {
     getBuildId() {
         return process.env.NEXT_BUILD_ID ?? FALLBACK_BUILD_ID;
     }
+    /**
+     * @returns request scoped in-memory cache for tag values, or undefined if ALS is not available.
+     */
+    getItemsCache() {
+        const store = globalThis.__openNextAls?.getStore();
+        return store?.requestCache.getOrCreate("d1-nextMode:tagItems");
+    }
 }
 export default new D1NextModeTagCache();

package/dist/api/overrides/tag-cache/do-sharded-tag-cache.d.ts

@@ -1,5 +1,14 @@
-import type { NextModeTagCache } from "@opennextjs/aws/types/overrides.js";
+import type { NextModeTagCache, NextModeTagCacheWriteInput } from "@opennextjs/aws/types/overrides.js";
+import type { TagData } from "../../durable-objects/sharded-tag-cache.js";
 import { DOShardedTagCache } from "../../durable-objects/sharded-tag-cache.js";
+type NormalizedTagInput = {
+    tag: string;
+    stale?: number;
+    expire?: number | null;
+};
+type CachedTagValue = {
+    tag: string;
+} & TagData;
 export declare const DEFAULT_WRITE_RETRIES = 3;
 export declare const DEFAULT_NUM_SHARDS = 4;
 export declare const NAME = "do-sharded-tag-cache";
@@ -88,6 +97,7 @@ interface DOIdOptions {
     region?: DurableObjectLocationHint;
 }
 declare class ShardedDOTagCache implements NextModeTagCache {
+    #private;
     private opts;
     readonly mode: "nextMode";
     readonly name = "do-sharded-tag-cache";
@@ -110,17 +120,18 @@ declare class ShardedDOTagCache implements NextModeTagCache {
      * @returns
      */
     hasBeenRevalidated(tags: string[], lastModified?: number): Promise<boolean>;
+    isStale(tags: string[], lastModified?: number): Promise<boolean>;
     /**
      * This function writes the tags to the cache
      * Due to the way shards and regional cache are implemented, the regional cache may not be properly invalidated
      * @param tags
      * @returns
      */
-    writeTags(tags: string[]): Promise<void>;
+    writeTags(tags: NextModeTagCacheWriteInput[]): Promise<void>;
     /**
      * The following methods are public only because they are accessed from the tests
      */
-    performWriteTagsWithRetry(doId: DOId, tags: string[], lastModified: number, retryNumber?: number): Promise<void>;
+    performWriteTagsWithRetry(doId: DOId, tags: NormalizedTagInput[], retryNumber?: number): Promise<void>;
     getCacheUrlKey(doId: DOId, tag: string): string;
     getCacheInstance(): Promise<Cache | undefined>;
     /**
@@ -128,10 +139,7 @@ declare class ShardedDOTagCache implements NextModeTagCache {
      * If the cache is not enabled, it will return an empty array
      * @returns An array of objects with the tag and the last revalidation time
      */
-    getFromRegionalCache(opts: CacheTagKeyOptions): Promise<{
-        tag: string;
-        time: number;
-    }[]>;
+    getFromRegionalCache(opts: CacheTagKeyOptions): Promise<CachedTagValue[]>;
     putToRegionalCache(optsKey: CacheTagKeyOptions, stub: DurableObjectStub<DOShardedTagCache>): Promise<void>;
     /**
      * Deletes the regional cache for the given tags

package/dist/api/overrides/tag-cache/do-sharded-tag-cache.js

@@ -37,26 +37,10 @@ class ShardedDOTagCache {
         }
         const deduplicatedTags = Array.from(new Set(tags)); // We deduplicate the tags to avoid unnecessary requests
         try {
-            const shardedTagGroups = this.groupTagsByDO({ tags: deduplicatedTags });
-            const shardedTagRevalidationOutcomes = await Promise.all(shardedTagGroups.map(async ({ doId, tags }) => {
-                const cachedValue = await this.getFromRegionalCache({ doId, tags });
-                // If all the value were found in the regional cache, we can just return the max value
-                if (cachedValue.length === tags.length) {
-                    const timeMs = Math.max(...cachedValue.map((item) => item.time));
-                    debugCache("ShardedDOTagCache", `getLastRevalidated tags=${tags} -> ${timeMs} (regional cache)`);
-                    return timeMs;
-                }
-                // Otherwise we need to check the durable object on the ones that were not found in the cache
-                const filteredTags = deduplicatedTags.filter((tag) => !cachedValue.some((item) => item.tag === tag));
-                const stub = this.getDurableObjectStub(doId);
-                const lastRevalidated = await stub.getLastRevalidated(filteredTags);
-                const timeMs = Math.max(...cachedValue.map((item) => item.time), lastRevalidated);
-                // We then need to populate the regional cache with the missing tags
-                getCloudflareContext().ctx.waitUntil(this.putToRegionalCache({ doId, tags }, stub));
-                debugCache("ShardedDOTagCache", `getLastRevalidated tags=${tags} -> ${timeMs}`);
-                return timeMs;
-            }));
-            return Math.max(...shardedTagRevalidationOutcomes);
+            const tagData = await this.#resolveTagData(deduplicatedTags);
+            const timeMs = Math.max(0, ...[...tagData.values()].filter((d) => d != null).map((d) => d.revalidatedAt));
+            debugCache("ShardedDOTagCache", `getLastRevalidated tags=${tags} -> ${timeMs}`);
+            return timeMs;
         }
         catch (e) {
             error("Error while checking revalidation", e);
@@ -76,34 +60,48 @@ class ShardedDOTagCache {
             return false;
         }
         try {
-            const shardedTagGroups = this.groupTagsByDO({ tags });
-            const shardedTagRevalidationOutcomes = await Promise.all(shardedTagGroups.map(async ({ doId, tags }) => {
-                const cachedValue = await this.getFromRegionalCache({ doId, tags });
-                // If one of the cached values is newer than the lastModified, we can return true
-                const cacheHasBeenRevalidated = cachedValue.some((cachedValue) => {
-                    return (cachedValue.time ?? 0) > (lastModified ?? Date.now());
-                });
-                if (cacheHasBeenRevalidated) {
-                    debugCache("ShardedDOTagCache", `hasBeenRevalidated tags=${tags} at=${lastModified} -> true (regional cache)`);
-                    return true;
-                }
-                const stub = this.getDurableObjectStub(doId);
-                const _hasBeenRevalidated = await stub.hasBeenRevalidated(tags, lastModified);
-                const remainingTags = tags.filter((tag) => !cachedValue.some((item) => item.tag === tag));
-                if (remainingTags.length > 0) {
-                    // We need to put the missing tags in the regional cache
-                    getCloudflareContext().ctx.waitUntil(this.putToRegionalCache({ doId, tags: remainingTags }, stub));
-                }
-                debugCache("ShardedDOTagCache", `hasBeenRevalidated tags=${tags} at=${lastModified} -> ${_hasBeenRevalidated}`);
-                return _hasBeenRevalidated;
-            }));
-            return shardedTagRevalidationOutcomes.some((result) => result);
+            const now = Date.now();
+            const tagData = await this.#resolveTagData(tags);
+            const result = [...tagData.values()].some((data) => {
+                if (data == null)
+                    return false;
+                const { revalidatedAt, expire } = data;
+                if (expire != null)
+                    return expire <= now && expire > (lastModified ?? 0);
+                return revalidatedAt > (lastModified ?? now);
+            });
+            debugCache("ShardedDOTagCache", `hasBeenRevalidated tags=${tags} at=${lastModified} -> ${result}`);
+            return result;
         }
         catch (e) {
             error("Error while checking revalidation", e);
             return false;
         }
     }
+    async isStale(tags, lastModified) {
+        const { isDisabled } = this.getConfig();
+        if (isDisabled || tags.length === 0) {
+            return false;
+        }
+        try {
+            const now = Date.now();
+            const tagData = await this.#resolveTagData(tags);
+            const result = [...tagData.values()].some((data) => {
+                if (data == null)
+                    return false;
+                const { stale, expire } = data;
+                if (stale == null || stale <= (lastModified ?? now))
+                    return false;
+                return expire == null || expire > now;
+            });
+            debugCache("ShardedDOTagCache", `isStale tags=${tags} at=${lastModified} -> ${result}`);
+            return result;
+        }
+        catch (e) {
+            error("Error while checking stale", e);
+            return false;
+        }
+    }
     /**
      * This function writes the tags to the cache
      * Due to the way shards and regional cache are implemented, the regional cache may not be properly invalidated
@@ -114,28 +112,33 @@ class ShardedDOTagCache {
         const { isDisabled } = this.getConfig();
         if (isDisabled)
             return;
-        // We want to use the same revalidation time for all tags
         const nowMs = Date.now();
-        debugCache("ShardedDOTagCache", `writeTags tags=${tags} time=${nowMs}`);
-        const shardedTagGroups = this.groupTagsByDO({ tags, generateAllReplicas: true });
-        await Promise.all(shardedTagGroups.map(async ({ doId, tags }) => {
-            await this.performWriteTagsWithRetry(doId, tags, nowMs);
+        const normalized = tags.map((tag) => typeof tag === "string"
+            ? { tag, stale: nowMs, expire: undefined }
+            : { tag: tag.tag, stale: tag.stale ?? nowMs, expire: tag.expire });
+        const tagStrings = normalized.map((t) => t.tag);
+        debugCache("ShardedDOTagCache", `writeTags tags=${tagStrings} time=${nowMs}`);
+        const tagMap = new Map(normalized.map((t) => [t.tag, t]));
+        const shardedTagGroups = this.groupTagsByDO({ tags: tagStrings, generateAllReplicas: true });
+        await Promise.all(shardedTagGroups.map(async ({ doId, tags: shardTags }) => {
+            const shardNormalized = shardTags.map((t) => tagMap.get(t));
+            await this.performWriteTagsWithRetry(doId, shardNormalized);
         }));
         // TODO: See https://github.com/opennextjs/opennextjs-aws/issues/986
         if (isPurgeCacheEnabled()) {
-            await purgeCacheByTags(tags);
+            await purgeCacheByTags(tagStrings);
         }
     }
     /**
      * The following methods are public only because they are accessed from the tests
      */
-    async performWriteTagsWithRetry(doId, tags, lastModified, retryNumber = 0) {
+    async performWriteTagsWithRetry(doId, tags, retryNumber = 0) {
         try {
             const stub = this.getDurableObjectStub(doId);
-            await stub.writeTags(tags, lastModified);
+            await stub.writeTags(tags);
             // Depending on the shards and the tags, deleting from the regional cache will not work for every tag
             // We also need to delete both cache
-            await Promise.all([this.deleteRegionalCache({ doId, tags })]);
+            await Promise.all([this.deleteRegionalCache({ doId, tags: tags.map((t) => t.tag) })]);
         }
         catch (e) {
             error("Error while writing tags", e);
@@ -145,11 +148,10 @@ class ShardedDOTagCache {
                 await getCloudflareContext().env.NEXT_TAG_CACHE_DO_SHARDED_DLQ?.send({
                     failingShardId: doId.key,
                     failingTags: tags,
-                    lastModified,
                 });
                 return;
             }
-            await this.performWriteTagsWithRetry(doId, tags, lastModified, retryNumber + 1);
+            await this.performWriteTagsWithRetry(doId, tags, retryNumber + 1);
         }
     }
     getCacheUrlKey(doId, tag) {
@@ -179,7 +181,23 @@ class ShardedDOTagCache {
                     return null;
                 const cachedText = await cachedResponse.text();
                 try {
-                    return { tag, time: parseInt(cachedText, 10) };
+                    const parsed = JSON.parse(cachedText);
+                    if (typeof parsed === "number") {
+                        // Backward compat: old format stored a plain revalidatedAt number
+                        return {
+                            tag,
+                            revalidatedAt: parsed,
+                            stale: parsed,
+                            expire: null,
+                        };
+                    }
+                    const data = parsed;
+                    return {
+                        tag,
+                        revalidatedAt: data.revalidatedAt ?? 0,
+                        stale: data.stale ?? null,
+                        expire: data.expire ?? null,
+                    };
                 }
                 catch (e) {
                     debugCache("Error while parsing cached value", e);
@@ -200,21 +218,22 @@ class ShardedDOTagCache {
         if (!cache)
             return;
         const tags = optsKey.tags;
-        const tagsLastRevalidated = await stub.getRevalidationTimes(tags);
+        const tagData = await stub.getTagData(tags);
         await Promise.all(tags.map(async (tag) => {
-            let lastRevalidated = tagsLastRevalidated[tag];
-            if (lastRevalidated === undefined) {
+            let data = tagData[tag];
+            if (data === undefined) {
                 if (this.opts.regionalCacheDangerouslyPersistMissingTags) {
-                    lastRevalidated = 0; // If the tag is not found, we set it to 0 as it means it has never been revalidated before.
+                    // Tag not found: store a sentinel (never revalidated)
+                    data = { revalidatedAt: 0, stale: null, expire: null };
                 }
                 else {
-                    debugCache("Tag not found in revalidation times", { tag, optsKey });
-                    return; // If the tag is not found, we skip it
+                    debugCache("Tag not found in tag data", { tag, optsKey });
+                    return;
                 }
             }
             const cacheKey = this.getCacheUrlKey(optsKey.doId, tag);
-            debugCache("Putting to regional cache", { cacheKey, lastRevalidated });
-            await cache.put(cacheKey, new Response(lastRevalidated.toString(), {
+            debugCache("Putting to regional cache", { cacheKey, data });
+            await cache.put(cacheKey, new Response(JSON.stringify(data), {
                 status: 200,
                 headers: {
                     "cache-control": `max-age=${this.opts.regionalCacheTtlSec ?? 5}`,
@@ -276,6 +295,59 @@ class ShardedDOTagCache {
         return result;
     }
     // Private methods
+    /**
+     * Fetches tag data for the given tags by consulting the regional cache first and falling back
+     * to Durable Object stubs for any misses. Returns a map of tag → TagData (null for tags not found).
+     */
+    async #fetchTagDataFromShards(tags) {
+        const result = new Map();
+        const shardedTagGroups = this.groupTagsByDO({ tags });
+        await Promise.all(shardedTagGroups.map(async ({ doId, tags: shardTags }) => {
+            const cachedValues = await this.getFromRegionalCache({ doId, tags: shardTags });
+            for (const { tag, revalidatedAt, stale, expire } of cachedValues) {
+                result.set(tag, { revalidatedAt, stale, expire });
+            }
+            const cachedTagNames = new Set(cachedValues.map(({ tag }) => tag));
+            const remainingTags = shardTags.filter((tag) => !cachedTagNames.has(tag));
+            if (remainingTags.length === 0)
+                return;
+            const stub = this.getDurableObjectStub(doId);
+            const tagData = await stub.getTagData(remainingTags);
+            for (const tag of remainingTags) {
+                result.set(tag, tagData[tag] ?? null);
+            }
+            getCloudflareContext().ctx.waitUntil(this.putToRegionalCache({ doId, tags: remainingTags }, stub));
+        }));
+        return result;
+    }
+    /**
+     * Resolves tag data from the per-request in-memory cache, falling back to
+     * `#fetchTagDataFromShards` for any misses. Results are stored back so repeated
+     * calls within the same request avoid duplicate shard fetches.
+     */
+    async #resolveTagData(tags) {
+        const store = globalThis.__openNextAls?.getStore();
+        const itemsCache = store?.requestCache.getOrCreate("do-sharded:tagItems");
+        const result = new Map();
+        const uncachedTags = [];
+        for (const tag of tags) {
+            if (itemsCache?.has(tag)) {
+                result.set(tag, itemsCache.get(tag) ?? null);
+            }
+            else {
+                uncachedTags.push(tag);
+            }
+        }
+        if (uncachedTags.length > 0) {
+            const fetched = await this.#fetchTagDataFromShards(uncachedTags);
+            for (const tag of uncachedTags) {
+                const value = fetched.get(tag) ?? null;
+                itemsCache?.set(tag, value);
+                result.set(tag, value);
+            }
+        }
+        return result;
+    }
     getDurableObjectStub(doId) {
         const durableObject = getCloudflareContext().env.NEXT_TAG_CACHE_DO_SHARDED;
         if (!durableObject)

package/dist/api/overrides/tag-cache/kv-next-tag-cache.d.ts

@@ -1,6 +1,14 @@
-import type { NextModeTagCache } from "@opennextjs/aws/types/overrides.js";
+import type { NextModeTagCache, NextModeTagCacheWriteInput } from "@opennextjs/aws/types/overrides.js";
 export declare const NAME = "kv-next-mode-tag-cache";
 export declare const BINDING_NAME = "NEXT_TAG_CACHE_KV";
+/**
+ * Stored value shape for KV entries.
+ */
+type KVTagValue = number | {
+    revalidatedAt: number;
+    stale?: number | null;
+    expire?: number | null;
+};
 /**
  * Tag Cache based on a KV namespace
  *
@@ -19,7 +27,8 @@ export declare class KVNextModeTagCache implements NextModeTagCache {
     readonly name = "kv-next-mode-tag-cache";
     getLastRevalidated(tags: string[]): Promise<number>;
     hasBeenRevalidated(tags: string[], lastModified?: number): Promise<boolean>;
-    writeTags(tags: string[]): Promise<void>;
+    writeTags(tags: NextModeTagCacheWriteInput[]): Promise<void>;
+    isStale(tags: string[], lastModified?: number): Promise<boolean>;
     /**
      * Returns the KV namespace when it exists and tag cache is not disabled.
      *
@@ -28,6 +37,10 @@ export declare class KVNextModeTagCache implements NextModeTagCache {
     private getKv;
     protected getCacheKey(key: string): string;
     protected getBuildId(): string;
+    /**
+     * @returns request scoped in-memory cache for tag values, or undefined if ALS is not available.
+     */
+    protected getItemsCache(): Map<string, KVTagValue | null> | undefined;
 }
 declare const _default: KVNextModeTagCache;
 export default _default;

package/dist/api/overrides/tag-cache/kv-next-tag-cache.js

@@ -3,6 +3,16 @@ import { getCloudflareContext } from "../../cloudflare-context.js";
 import { debugCache, FALLBACK_BUILD_ID, isPurgeCacheEnabled, purgeCacheByTags } from "../internal.js";
 export const NAME = "kv-next-mode-tag-cache";
 export const BINDING_NAME = "NEXT_TAG_CACHE_KV";
+function getRevalidatedAt(value) {
+    return typeof value === "number" ? value : (value.revalidatedAt ?? 0);
+}
+function getStale(value) {
+    // Backward compat: old format stored a plain number meaning revalidatedAt = stale
+    return typeof value === "number" ? value : (value.stale ?? null);
+}
+function getExpire(value) {
+    return typeof value === "number" ? null : (value.expire ?? null);
+}
 /**
  * Tag Cache based on a KV namespace
  *
@@ -34,10 +44,10 @@ export class KVNextModeTagCache {
             return 0;
         }
         try {
-            const keys = tags.map((tag) => this.getCacheKey(tag));
-            // Use the `json` type to get back numbers/null
-            const result = await kv.get(keys, { type: "json" });
-            const revalidations = [...result.values()].filter((v) => v != null);
+            const result = await this.#resolveTagValues(tags, kv);
+            const revalidations = [...result.values()]
+                .filter((v) => v != null)
+                .map(getRevalidatedAt);
             return revalidations.length === 0 ? 0 : Math.max(...revalidations);
         }
         catch (e) {
@@ -47,10 +57,57 @@ export class KVNextModeTagCache {
             return 0;
         }
     }
+    /**
+     * Resolves tag values from the per-request in-memory cache, falling back to KV for any misses.
+     * Results are stored back into the request cache so repeated calls within the same request
+     * avoid duplicate KV fetches.
+     */
+    async #resolveTagValues(tags, kv) {
+        const result = new Map();
+        const uncachedTags = [];
+        const itemsCache = this.getItemsCache();
+        for (const tag of tags) {
+            if (itemsCache?.has(tag)) {
+                result.set(tag, itemsCache.get(tag) ?? null);
+            }
+            else {
+                uncachedTags.push(tag);
+            }
+        }
+        if (uncachedTags.length > 0) {
+            const kvKeys = uncachedTags.map((tag) => this.getCacheKey(tag));
+            const fetched = await kv.get(kvKeys, { type: "json" });
+            for (const tag of uncachedTags) {
+                const value = fetched.get(this.getCacheKey(tag)) ?? null;
+                itemsCache?.set(tag, value);
+                result.set(tag, value);
+            }
+        }
+        return result;
+    }
     async hasBeenRevalidated(tags, lastModified) {
-        const revalidated = (await this.#getLastRevalidated(tags)) > (lastModified ?? Date.now());
-        debugCache("KVNextModeTagCache", `hasBeenRevalidated tags=${tags} lastModified=${lastModified} -> ${revalidated}`);
-        return revalidated;
+        const kv = this.getKv();
+        if (!kv || tags.length === 0) {
+            return false;
+        }
+        try {
+            const now = Date.now();
+            const result = await this.#resolveTagValues(tags, kv);
+            const revalidated = [...result.values()].some((v) => {
+                if (v == null)
+                    return false;
+                const expire = getExpire(v);
+                if (expire != null)
+                    return expire <= now && expire > (lastModified ?? 0);
+                return getRevalidatedAt(v) > (lastModified ?? now);
+            });
+            debugCache("KVNextModeTagCache", `hasBeenRevalidated tags=${tags} lastModified=${lastModified} -> ${revalidated}`);
+            return revalidated;
+        }
+        catch (e) {
+            error(e);
+            return false;
+        }
     }
     async writeTags(tags) {
         const kv = this.getKv();
@@ -59,12 +116,45 @@ export class KVNextModeTagCache {
         }
         const nowMs = Date.now();
         await Promise.all(tags.map(async (tag) => {
-            await kv.put(this.getCacheKey(tag), String(nowMs));
+            if (typeof tag === "string") {
+                // Old format: store plain number string for backward compat
+                await kv.put(this.getCacheKey(tag), String(nowMs));
+            }
+            else {
+                const stale = tag.stale ?? nowMs;
+                const value = { revalidatedAt: stale, stale, expire: tag.expire ?? null };
+                await kv.put(this.getCacheKey(tag.tag), JSON.stringify(value));
+            }
         }));
-        debugCache("KVNextModeTagCache", `writeTags tags=${tags} time=${nowMs}`);
+        const tagStrings = tags.map((t) => (typeof t === "string" ? t : t.tag));
+        debugCache("KVNextModeTagCache", `writeTags tags=${tagStrings} time=${nowMs}`);
         // TODO: See https://github.com/opennextjs/opennextjs-aws/issues/986
         if (isPurgeCacheEnabled()) {
-            await purgeCacheByTags(tags);
+            await purgeCacheByTags(tagStrings);
+        }
+    }
+    async isStale(tags, lastModified) {
+        const kv = this.getKv();
+        if (!kv || tags.length === 0)
+            return false;
+        try {
+            const now = Date.now();
+            const result = await this.#resolveTagValues(tags, kv);
+            const isStale = [...result.values()].some((v) => {
+                if (v == null)
+                    return false;
+                const stale = getStale(v);
+                if (stale == null || stale <= (lastModified ?? now))
+                    return false;
+                const expire = getExpire(v);
+                return expire == null || expire > now;
+            });
+            debugCache("KVNextModeTagCache", `isStale tags=${tags} lastModified=${lastModified} -> ${isStale}`);
+            return isStale;
+        }
+        catch (e) {
+            error(e);
+            return false;
         }
     }
     /**
@@ -87,5 +177,12 @@ export class KVNextModeTagCache {
     getBuildId() {
         return process.env.NEXT_BUILD_ID ?? FALLBACK_BUILD_ID;
     }
+    /**
+     * @returns request scoped in-memory cache for tag values, or undefined if ALS is not available.
+     */
+    getItemsCache() {
+        const store = globalThis.__openNextAls?.getStore();
+        return store?.requestCache.getOrCreate("kv-nextMode:tagItems");
+    }
 }
 export default new KVNextModeTagCache();

package/dist/api/overrides/tag-cache/tag-cache-filter.d.ts

@@ -1,4 +1,4 @@
-import { NextModeTagCache } from "@opennextjs/aws/types/overrides.js";
+import type { NextModeTagCache, NextModeTagCacheWriteInput } from "@opennextjs/aws/types/overrides.js";
 interface WithFilterOptions {
     /**
      * The original tag cache.
@@ -10,7 +10,7 @@ interface WithFilterOptions {
      * @param tag The tag to filter.
      * @returns true if the tag should be forwarded, false otherwise.
      */
-    filterFn: (tag: string) => boolean;
+    filterFn: (tag: string | NextModeTagCacheWriteInput) => boolean;
 }
 /**
  * Creates a new tag cache that filters tags based on the provided filter function.
@@ -22,5 +22,5 @@ export declare function withFilter({ tagCache, filterFn }: WithFilterOptions): N
  * This is used to filter out internal soft tags.
  * Can be used if `revalidatePath` is not used.
  */
-export declare function softTagFilter(tag: string): boolean;
+export declare function softTagFilter(tag: string | NextModeTagCacheWriteInput): boolean;
 export {};

package/dist/api/overrides/tag-cache/tag-cache-filter.js

@@ -44,5 +44,8 @@ export function withFilter({ tagCache, filterFn }) {
  * Can be used if `revalidatePath` is not used.
  */
 export function softTagFilter(tag) {
-    return !tag.startsWith("_N_T_");
+    if (typeof tag === "string") {
+        return !tag.startsWith("_N_T_");
+    }
+    return !tag.tag.startsWith("_N_T_");
 }

package/dist/cli/build/patches/plugins/next-server.js

@@ -102,6 +102,7 @@ fix: |-
   const handlersSetSymbol = Symbol.for('@next/cache-handlers-set');
   globalThis[handlersMapSymbol] = new Map();
   globalThis[handlersMapSymbol].set("default", require('${normalizePath(handlerPath)}').default);
+  globalThis[handlersMapSymbol].set("remote", require('${normalizePath(handlerPath)}').default);
   globalThis[handlersSetSymbol] = new Set(globalThis[handlersMapSymbol].values());
 `;
 }

package/dist/cli/build/patches/plugins/route-module.js

@@ -10,6 +10,7 @@ import { getPackagePath } from "@opennextjs/aws/build/helper.js";
 import { patchCode } from "@opennextjs/aws/build/patch/astCodePatcher.js";
 import { getCrossPlatformPathRegex } from "@opennextjs/aws/utils/regex.js";
 import { normalizePath } from "../../../utils/normalize-path.js";
+import { createComposableCacheHandlersRule } from "./next-server.js";
 export function patchRouteModules(updater, buildOpts) {
     return updater.updateContent("route-module", [
         {
@@ -17,13 +18,15 @@ export function patchRouteModules(updater, buildOpts) {
                 escape: false,
             }),
             versions: ">=15.4.0",
-            contentFilter: /getIncrementalCache\(/,
+            // app route doesn't have getIncrementalCache, but we still need to patch the composable cache handlers there
+            contentFilter: /(getIncrementalCache\(|loadCustomCacheHandlers\()/,
             callback: async ({ contents }) => {
                 const { outputDir } = buildOpts;
                 const outputPath = path.join(outputDir, "server-functions/default");
                 const cacheHandler = path.join(outputPath, getPackagePath(buildOpts), "cache.cjs");
                 contents = patchCode(contents, getIncrementalCacheRule(cacheHandler));
                 contents = patchCode(contents, forceTrustHostHeader);
+                contents = patchCode(contents, createComposableCacheHandlersRule(path.join(outputPath, getPackagePath(buildOpts), "composable-cache.cjs")));
                 return contents;
             },
         },

package/dist/cli/commands/populate-cache.js

@@ -373,7 +373,12 @@ function populateD1TagCache(buildOpts, config, populateCacheOptions) {
     const result = runWrangler(buildOpts, [
         "d1 execute",
         D1_TAG_BINDING_NAME,
-        `--command "CREATE TABLE IF NOT EXISTS revalidations (tag TEXT NOT NULL, revalidatedAt INTEGER NOT NULL, UNIQUE(tag) ON CONFLICT REPLACE);"`,
+        // Columns:
+        //   tag           - The cache tag.
+        //   revalidatedAt - Timestamp (ms) when the tag was last revalidated.
+        //   stale         - Timestamp (ms) when the cached entry becomes stale. Added in v1.19.
+        //   expire        - Timestamp (ms) when the cached entry expires. NULL means no expire. Added in v1.19.
+        `--command "CREATE TABLE IF NOT EXISTS revalidations (tag TEXT NOT NULL, revalidatedAt INTEGER NOT NULL, stale INTEGER, expire INTEGER default NULL, UNIQUE(tag) ON CONFLICT REPLACE);"`,
         `--preview ${populateCacheOptions.shouldUsePreviewId}`,
     ], {
         target: populateCacheOptions.target,
@@ -384,6 +389,20 @@ function populateD1TagCache(buildOpts, config, populateCacheOptions) {
     if (!result.success) {
         throw new Error(`Wrangler d1 execute command failed${result.stderr ? `:\n${result.stderr}` : ""}`);
     }
+    // Schema migration: add `stale` and `expire` columns (idempotent, safe for existing deployments).
+    // The columns were added in v1.19 to support SWR.
+    // These commands are intentionally non-throwing — they fail harmlessly if the columns already exist.
+    runWrangler(buildOpts, [
+        "d1 execute",
+        D1_TAG_BINDING_NAME,
+        `--command "ALTER TABLE revalidations ADD COLUMN stale INTEGER; ALTER TABLE revalidations ADD COLUMN expire INTEGER default NULL"`,
+        `--preview ${populateCacheOptions.shouldUsePreviewId}`,
+    ], {
+        target: populateCacheOptions.target,
+        environment: populateCacheOptions.environment,
+        configPath: populateCacheOptions.wranglerConfigPath,
+        logging: "error",
+    });
     logger.info("\nSuccessfully created D1 table");
 }
 function populateStaticAssetsIncrementalCache(options) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@opennextjs/cloudflare",
   "description": "Cloudflare builder for next apps",
-  "version": "1.18.1",
+  "version": "1.19.0",
   "type": "module",
   "bin": {
     "opennextjs-cloudflare": "dist/cli/index.js"
@@ -44,11 +44,11 @@
   "dependencies": {
     "@ast-grep/napi": "^0.40.5",
     "@dotenvx/dotenvx": "1.31.0",
-    "@opennextjs/aws": "3.9.16",
+    "@opennextjs/aws": "3.10.1",
     "cloudflare": "^4.4.1",
+    "comment-json": "^4.5.1",
     "enquirer": "^2.4.1",
     "glob": "^12.0.0",
-    "comment-json": "^4.5.1",
     "ts-tqdm": "^0.8.6",
     "yargs": "^18.0.0"
   },
@@ -68,7 +68,7 @@
     "eslint-plugin-unicorn": "^55.0.0",
     "globals": "^15.9.0",
     "mock-fs": "^5.4.1",
-    "next": "~15.5.9",
+    "next": "~15.5.15",
     "picomatch": "^4.0.2",
     "rimraf": "^6.0.1",
     "typescript": "^5.9.3",
@@ -76,8 +76,8 @@
     "vitest": "^2.1.1"
   },
   "peerDependencies": {
-    "wrangler": "^4.65.0",
-    "next": "~15.0.8 || ~15.1.12 || ~15.2.9 || ~15.3.9 || ~15.4.11 || ~15.5.10 || ~16.0.11 || ^16.1.5"
+    "next": ">=15.5.15 || >=16.2.3",
+    "wrangler": "^4.65.0"
   },
   "scripts": {
     "clean": "rimraf dist",