@opennextjs/aws 3.9.16 → 3.10.1

package/dist/overrides/tagCache/dynamodb-lite.js

@@ -39,12 +39,15 @@ function buildDynamoKey(key) {
     // this could transform some fetch cache key into a valid path
     return path.posix.join(NEXT_BUILD_ID ?? "", key);
 }
-function buildDynamoObject(path, tags, revalidatedAt) {
-    return {
+function buildDynamoObject(path, tags, revalidatedAt, stale, expire) {
+    const obj = {
         path: { S: buildDynamoKey(path) },
         tag: { S: buildDynamoKey(tags) },
         revalidatedAt: { N: `${revalidatedAt ?? Date.now()}` },
+        ...(stale !== undefined ? { stale: { N: `${stale}` } } : {}),
+        ...(expire !== undefined ? { expire: { N: `${expire}` } } : {}),
     };
+    return obj;
 }
 const tagCache = {
     mode: "original",
@@ -54,6 +57,11 @@ const tagCache = {
                 return [];
             }
             const { CACHE_DYNAMO_TABLE, NEXT_BUILD_ID } = process.env;
+            const store = globalThis.__openNextAls.getStore();
+            const cache = store?.requestCache.getOrCreate("dynamoDb:getByPath");
+            if (cache?.has(path)) {
+                return cache.get(path);
+            }
             const result = await awsFetch(JSON.stringify({
                 TableName: CACHE_DYNAMO_TABLE,
                 IndexName: "revalidate",
@@ -72,7 +80,9 @@ const tagCache = {
             const tags = Items?.map((item) => item.tag.S ?? "") ?? [];
             debug("tags for path", path, tags);
             // We need to remove the buildId from the path
-            return tags.map((tag) => tag.replace(`${NEXT_BUILD_ID}/`, ""));
+            const resultTags = tags.map((tag) => tag.replace(`${NEXT_BUILD_ID}/`, ""));
+            cache?.set(path, resultTags);
+            return resultTags;
         }
         catch (e) {
             error("Failed to get tags by path", e);
@@ -85,6 +95,11 @@ const tagCache = {
                 return [];
             }
             const { CACHE_DYNAMO_TABLE, NEXT_BUILD_ID } = process.env;
+            const store = globalThis.__openNextAls.getStore();
+            const cache = store?.requestCache.getOrCreate("dynamoDb:getByTag");
+            if (cache?.has(tag)) {
+                return cache.get(tag);
+            }
             const result = await awsFetch(JSON.stringify({
                 TableName: CACHE_DYNAMO_TABLE,
                 KeyConditionExpression: "#tag = :tag",
@@ -99,9 +114,10 @@ const tagCache = {
                 throw new RecoverableError(`Failed to get by tag: ${result.status}`);
             }
             const { Items } = (await result.json());
-            return (
             // We need to remove the buildId from the path
-            Items?.map(({ path: { S: key } }) => key?.replace(`${NEXT_BUILD_ID}/`, "") ?? "") ?? []);
+            const paths = Items?.map(({ path: { S: key } }) => key?.replace(`${NEXT_BUILD_ID}/`, "") ?? "") ?? [];
+            cache?.set(tag, paths);
+            return paths;
         }
         catch (e) {
             error("Failed to get by tag", e);
@@ -114,6 +130,12 @@ const tagCache = {
                 return lastModified ?? Date.now();
             }
             const { CACHE_DYNAMO_TABLE } = process.env;
+            const store = globalThis.__openNextAls.getStore();
+            const cache = store?.requestCache.getOrCreate("dynamoDb:getLastModified");
+            const cacheKey = `${key}:${lastModified ?? 0}`;
+            if (cache?.has(cacheKey)) {
+                return cache.get(cacheKey);
+            }
             const result = await awsFetch(JSON.stringify({
                 TableName: CACHE_DYNAMO_TABLE,
                 IndexName: "revalidate",
@@ -132,14 +154,78 @@ const tagCache = {
             }
             const revalidatedTags = (await result.json()).Items ?? [];
             debug("revalidatedTags", revalidatedTags);
-            // If we have revalidated tags we return -1 to force revalidation
-            return revalidatedTags.length > 0 ? -1 : (lastModified ?? Date.now());
+            // Check if any tag has expired
+            const now = Date.now();
+            const hasExpiredTag = revalidatedTags.some((item) => {
+                if (item.expire?.N) {
+                    const expiry = Number.parseInt(item.expire.N);
+                    return expiry <= now && expiry > (lastModified ?? 0);
+                }
+                return false;
+            });
+            // Exclude expired tags from the revalidated count — they are handled
+            // separately via hasExpiredTag above.
+            const nonExpiredRevalidatedTags = revalidatedTags.filter((item) => {
+                if (item.expire?.N) {
+                    return (Number.parseInt(item.expire.N) ===
+                        Number.parseInt(item.revalidatedAt.N));
+                }
+                return true;
+            });
+            // If we have revalidated tags or expired tags we return -1 to force revalidation
+            const resultValue = nonExpiredRevalidatedTags.length > 0 || hasExpiredTag
+                ? -1
+                : (lastModified ?? Date.now());
+            cache?.set(cacheKey, resultValue);
+            return resultValue;
         }
         catch (e) {
             error("Failed to get revalidated tags", e);
             return lastModified ?? Date.now();
         }
     },
+    async isStale(key, lastModified) {
+        try {
+            if (globalThis.openNextConfig.dangerous?.disableTagCache) {
+                return false;
+            }
+            const { CACHE_DYNAMO_TABLE } = process.env;
+            const store = globalThis.__openNextAls.getStore();
+            const itemsCache = store?.requestCache.getOrCreate("dynamoDb:revalidateQueryItems");
+            const cacheKey = `${key}:${lastModified ?? 0}`;
+            let items;
+            if (itemsCache?.has(cacheKey)) {
+                items = itemsCache.get(cacheKey);
+            }
+            else {
+                // We can reuse the same query as getLastModified since it already checks for revalidatedAt > lastModified as revalidatedAt and stale have the same value
+                const result = await awsFetch(JSON.stringify({
+                    TableName: CACHE_DYNAMO_TABLE,
+                    IndexName: "revalidate",
+                    KeyConditionExpression: "#key = :key AND #revalidatedAt > :lastModified",
+                    ExpressionAttributeNames: {
+                        "#key": "path",
+                        "#revalidatedAt": "revalidatedAt",
+                    },
+                    ExpressionAttributeValues: {
+                        ":key": { S: buildDynamoKey(key) },
+                        ":lastModified": { N: String(lastModified ?? 0) },
+                    },
+                }));
+                if (result.status !== 200) {
+                    throw new RecoverableError(`Failed to check stale tags: ${result.status}`);
+                }
+                items = (await result.json()).Items ?? [];
+                itemsCache?.set(cacheKey, items);
+            }
+            debug("isStale items", key, items);
+            return items.length > 0;
+        }
+        catch (e) {
+            error("Failed to check stale tags", e);
+            return false;
+        }
+    },
     async writeTags(tags) {
         try {
             const { CACHE_DYNAMO_TABLE } = process.env;
@@ -151,7 +237,7 @@ const tagCache = {
                     [CACHE_DYNAMO_TABLE ?? ""]: Items.map((Item) => ({
                         PutRequest: {
                             Item: {
-                                ...buildDynamoObject(Item.path, Item.tag, Item.revalidatedAt),
+                                ...buildDynamoObject(Item.path, Item.tag, Item.revalidatedAt, Item.stale, Item.expire),
                             },
                         },
                     })),

package/dist/overrides/tagCache/dynamodb-nextMode.d.ts

@@ -3,6 +3,7 @@ declare const _default: {
     mode: "nextMode";
     getLastRevalidated: (tags: string[]) => Promise<number>;
     hasBeenRevalidated: (tags: string[], lastModified?: number) => Promise<boolean>;
-    writeTags: (tags: string[]) => Promise<void>;
+    isStale: (tags: string[], lastModified?: number) => Promise<boolean>;
+    writeTags: (tags: import("../../types/overrides").NextModeTagCacheWriteInput[]) => Promise<void>;
 };
 export default _default;

package/dist/overrides/tagCache/dynamodb-nextMode.js

@@ -41,14 +41,70 @@ function buildDynamoKey(key) {
 // We use the same key for both path and tag
 // That's mostly for compatibility reason so that it's easier to use this with existing infra
 // FIXME: Allow a simpler object without an unnecessary path key
-function buildDynamoObject(tag, revalidatedAt) {
-    return {
+function buildDynamoObject(tag, revalidatedAt, stale, expire) {
+    const obj = {
         path: { S: buildDynamoKey(tag) },
         tag: { S: buildDynamoKey(tag) },
         revalidatedAt: { N: `${revalidatedAt ?? Date.now()}` },
+        ...(stale !== undefined ? { stale: { N: `${stale}` } } : {}),
+        ...(expire !== undefined ? { expire: { N: `${expire}` } } : {}),
     };
+    return obj;
 }
 // This implementation does not support automatic invalidation of paths by the cdn
+/**
+ * Checks the items cache for each tag. Returns tags not yet cached and whether
+ * a positive result was already found among the cached ones.
+ */
+function checkItemsCache(tags, itemsCache, compute) {
+    const uncachedTags = [];
+    let hasMatch = false;
+    for (const tag of tags) {
+        if (itemsCache?.has(tag)) {
+            if (compute(itemsCache.get(tag)))
+                hasMatch = true;
+        }
+        else {
+            uncachedTags.push(tag);
+        }
+    }
+    return { uncachedTags, hasMatch };
+}
+/**
+ * Fetches uncached tags from DynamoDB via BatchGetItem, populates the items
+ * cache (storing null for absent tags), and returns whether any tag matched.
+ */
+async function fetchAndCacheItems(uncachedTags, itemsCache, compute) {
+    const { CACHE_DYNAMO_TABLE } = process.env;
+    const response = await awsFetch(JSON.stringify({
+        RequestItems: {
+            [CACHE_DYNAMO_TABLE ?? ""]: {
+                Keys: uncachedTags.map((tag) => ({
+                    path: { S: buildDynamoKey(tag) },
+                    tag: { S: buildDynamoKey(tag) },
+                })),
+            },
+        },
+    }), "query");
+    if (response.status !== 200) {
+        throw new RecoverableError(`Failed to query dynamo item: ${response.status}`);
+    }
+    const { Responses } = await response.json();
+    const responseItems = Responses?.[CACHE_DYNAMO_TABLE ?? ""] ?? [];
+    // Build a lookup map: DynamoDB key → item
+    const responseByKey = new Map();
+    for (const item of responseItems) {
+        responseByKey.set(item.tag.S, item);
+    }
+    let hasMatch = false;
+    for (const tag of uncachedTags) {
+        const item = responseByKey.get(buildDynamoKey(tag)) ?? null;
+        itemsCache?.set(tag, item);
+        if (compute(item))
+            hasMatch = true;
+    }
+    return hasMatch;
+}
 export default {
     name: "ddb-nextMode",
     mode: "nextMode",
@@ -63,30 +119,54 @@ export default {
         if (tags.length > 100) {
             throw new RecoverableError("Cannot query more than 100 tags at once. You should not be using this tagCache implementation for this amount of tags");
         }
-        const { CACHE_DYNAMO_TABLE } = process.env;
+        const store = globalThis.__openNextAls.getStore();
+        const itemsCache = store?.requestCache.getOrCreate("ddb-nextMode:tagItems");
+        const now = Date.now();
+        const compute = (item) => {
+            if (!item)
+                return false;
+            if (item.expire?.N) {
+                const expiry = Number.parseInt(item.expire.N);
+                if (expiry <= now && expiry > (lastModified ?? 0))
+                    return true;
+            }
+            return Number.parseInt(item.revalidatedAt.N) > (lastModified ?? 0);
+        };
+        const { uncachedTags, hasMatch } = checkItemsCache(tags, itemsCache, compute);
+        if (hasMatch)
+            return true;
+        if (uncachedTags.length === 0)
+            return false;
         // It's unlikely that we will have more than 100 items to query
         // If that's the case, you should not use this tagCache implementation
-        const response = await awsFetch(JSON.stringify({
-            RequestItems: {
-                [CACHE_DYNAMO_TABLE ?? ""]: {
-                    Keys: tags.map((tag) => ({
-                        path: { S: buildDynamoKey(tag) },
-                        tag: { S: buildDynamoKey(tag) },
-                    })),
-                },
-            },
-        }), "query");
-        if (response.status !== 200) {
-            throw new RecoverableError(`Failed to query dynamo item: ${response.status}`);
+        const result = await fetchAndCacheItems(uncachedTags, itemsCache, compute);
+        debug("retrieved tags for hasBeenRevalidated", tags);
+        return result;
+    },
+    isStale: async (tags, lastModified) => {
+        if (globalThis.openNextConfig.dangerous?.disableTagCache) {
+            return false;
         }
-        // Now we need to check for every item if lastModified is greater than the revalidatedAt
-        const { Responses } = await response.json();
-        if (!Responses) {
+        if (tags.length === 0)
             return false;
+        if (tags.length > 100) {
+            throw new RecoverableError("Cannot query more than 100 tags at once. You should not be using this tagCache implementation for this amount of tags");
         }
-        const revalidatedTags = Responses[CACHE_DYNAMO_TABLE ?? ""].filter((item) => Number.parseInt(item.revalidatedAt.N) > (lastModified ?? 0));
-        debug("retrieved tags", revalidatedTags);
-        return revalidatedTags.length > 0;
+        const store = globalThis.__openNextAls.getStore();
+        const itemsCache = store?.requestCache.getOrCreate("ddb-nextMode:tagItems");
+        const compute = (item) => {
+            if (!item?.stale?.N)
+                return false;
+            return Number.parseInt(item.stale.N) > (lastModified ?? 0);
+        };
+        const { uncachedTags, hasMatch } = checkItemsCache(tags, itemsCache, compute);
+        if (hasMatch)
+            return true;
+        if (uncachedTags.length === 0)
+            return false;
+        const result = await fetchAndCacheItems(uncachedTags, itemsCache, compute);
+        debug("isStale result:", result);
+        return result;
     },
     writeTags: async (tags) => {
         try {
@@ -96,13 +176,18 @@ export default {
             }
             const dataChunks = chunk(tags, MAX_DYNAMO_BATCH_WRITE_ITEM_COUNT).map((Items) => ({
                 RequestItems: {
-                    [CACHE_DYNAMO_TABLE ?? ""]: Items.map((tag) => ({
-                        PutRequest: {
-                            Item: {
-                                ...buildDynamoObject(tag),
+                    [CACHE_DYNAMO_TABLE ?? ""]: Items.map((tag) => {
+                        const tagStr = typeof tag === "string" ? tag : tag.tag;
+                        const stale = typeof tag === "string" ? undefined : tag.stale;
+                        const expiry = typeof tag === "string" ? undefined : tag.expire;
+                        return {
+                            PutRequest: {
+                                Item: {
+                                    ...buildDynamoObject(tagStr, undefined, stale, expiry),
+                                },
                             },
-                        },
-                    })),
+                        };
+                    }),
                 },
             }));
             const toInsert = chunk(dataChunks, getDynamoBatchWriteCommandConcurrency());

package/dist/overrides/tagCache/dynamodb.js

@@ -17,12 +17,15 @@ function buildDynamoKey(key) {
     // this could transform some fetch cache key into a valid path
     return path.posix.join(NEXT_BUILD_ID ?? "", key);
 }
-function buildDynamoObject(path, tags, revalidatedAt) {
-    return {
+function buildDynamoObject(path, tags, revalidatedAt, stale, expire) {
+    const obj = {
         path: { S: buildDynamoKey(path) },
         tag: { S: buildDynamoKey(tags) },
         revalidatedAt: { N: `${revalidatedAt ?? Date.now()}` },
+        ...(stale !== undefined ? { stale: { N: `${stale}` } } : {}),
+        ...(expire !== undefined ? { expire: { N: `${expire}` } } : {}),
     };
+    return obj;
 }
 const tagCache = {
     mode: "original",
@@ -31,6 +34,11 @@ const tagCache = {
             if (globalThis.openNextConfig.dangerous?.disableTagCache) {
                 return [];
             }
+            const store = globalThis.__openNextAls.getStore();
+            const cache = store?.requestCache.getOrCreate("dynamoDb:getByPath");
+            if (cache?.has(path)) {
+                return cache.get(path);
+            }
             const result = await dynamoClient.send(new QueryCommand({
                 TableName: CACHE_DYNAMO_TABLE,
                 IndexName: "revalidate",
@@ -45,7 +53,9 @@ const tagCache = {
             const tags = result.Items?.map((item) => item.tag.S ?? "") ?? [];
             debug("tags for path", path, tags);
             // We need to remove the buildId from the path
-            return tags.map((tag) => tag.replace(`${NEXT_BUILD_ID}/`, ""));
+            const resultTags = tags.map((tag) => tag.replace(`${NEXT_BUILD_ID}/`, ""));
+            cache?.set(path, resultTags);
+            return resultTags;
         }
         catch (e) {
             error("Failed to get tags by path", e);
@@ -57,6 +67,11 @@ const tagCache = {
             if (globalThis.openNextConfig.dangerous?.disableTagCache) {
                 return [];
             }
+            const store = globalThis.__openNextAls.getStore();
+            const cache = store?.requestCache.getOrCreate("dynamoDb:getByTag");
+            if (cache?.has(tag)) {
+                return cache.get(tag);
+            }
             const { Items } = await dynamoClient.send(new QueryCommand({
                 TableName: CACHE_DYNAMO_TABLE,
                 KeyConditionExpression: "#tag = :tag",
@@ -67,9 +82,10 @@ const tagCache = {
                     ":tag": { S: buildDynamoKey(tag) },
                 },
             }));
-            return (
             // We need to remove the buildId from the path
-            Items?.map(({ path: { S: key } }) => key?.replace(`${NEXT_BUILD_ID}/`, "") ?? "") ?? []);
+            const paths = Items?.map(({ path: { S: key } }) => key?.replace(`${NEXT_BUILD_ID}/`, "") ?? "") ?? [];
+            cache?.set(tag, paths);
+            return paths;
         }
         catch (e) {
             error("Failed to get by tag", e);
@@ -81,29 +97,95 @@ const tagCache = {
             if (globalThis.openNextConfig.dangerous?.disableTagCache) {
                 return lastModified ?? Date.now();
             }
-            const result = await dynamoClient.send(new QueryCommand({
-                TableName: CACHE_DYNAMO_TABLE,
-                IndexName: "revalidate",
-                KeyConditionExpression: "#key = :key AND #revalidatedAt > :lastModified",
-                ExpressionAttributeNames: {
-                    "#key": "path",
-                    "#revalidatedAt": "revalidatedAt",
-                },
-                ExpressionAttributeValues: {
-                    ":key": { S: buildDynamoKey(key) },
-                    ":lastModified": { N: String(lastModified ?? 0) },
-                },
-            }));
-            const revalidatedTags = result.Items ?? [];
+            const store = globalThis.__openNextAls.getStore();
+            const itemsCache = store?.requestCache.getOrCreate("dynamoDb:revalidateQueryItems");
+            const cacheKey = `${key}:${lastModified ?? 0}`;
+            let revalidatedTags;
+            if (itemsCache?.has(cacheKey)) {
+                revalidatedTags = itemsCache.get(cacheKey);
+            }
+            else {
+                const result = await dynamoClient.send(new QueryCommand({
+                    TableName: CACHE_DYNAMO_TABLE,
+                    IndexName: "revalidate",
+                    KeyConditionExpression: "#key = :key AND #revalidatedAt > :lastModified",
+                    ExpressionAttributeNames: {
+                        "#key": "path",
+                        "#revalidatedAt": "revalidatedAt",
+                    },
+                    ExpressionAttributeValues: {
+                        ":key": { S: buildDynamoKey(key) },
+                        ":lastModified": { N: String(lastModified ?? 0) },
+                    },
+                }));
+                revalidatedTags = result.Items ?? [];
+                itemsCache?.set(cacheKey, revalidatedTags);
+            }
             debug("revalidatedTags", revalidatedTags);
-            // If we have revalidated tags we return -1 to force revalidation
-            return revalidatedTags.length > 0 ? -1 : (lastModified ?? Date.now());
+            // Check if any tag has expired
+            const now = Date.now();
+            const hasExpiredTag = revalidatedTags.some((item) => {
+                if (item.expire?.N) {
+                    const expiry = Number.parseInt(item.expire.N);
+                    return expiry <= now && expiry > (lastModified ?? 0);
+                }
+                return false;
+            });
+            // Exclude expired tags from the revalidated count — they are handled
+            // separately via hasExpiredTag above.
+            const nonExpiredRevalidatedTags = revalidatedTags.filter((item) => {
+                if (item.expire?.N) {
+                    return Number.parseInt(item.expire.N) > now;
+                }
+                return true;
+            });
+            // If we have revalidated tags or expired tags we return -1 to force revalidation
+            return nonExpiredRevalidatedTags.length > 0 || hasExpiredTag
+                ? -1
+                : (lastModified ?? Date.now());
         }
         catch (e) {
             error("Failed to get revalidated tags", e);
             return lastModified ?? Date.now();
         }
     },
+    async isStale(key, lastModified) {
+        try {
+            if (globalThis.openNextConfig.dangerous?.disableTagCache) {
+                return false;
+            }
+            const store = globalThis.__openNextAls.getStore();
+            const itemsCache = store?.requestCache.getOrCreate("dynamoDb:revalidateQueryItems");
+            const cacheKey = `${key}:${lastModified ?? 0}`;
+            let items;
+            if (itemsCache?.has(cacheKey)) {
+                items = itemsCache.get(cacheKey);
+            }
+            else {
+                const result = await dynamoClient.send(new QueryCommand({
+                    TableName: CACHE_DYNAMO_TABLE,
+                    IndexName: "revalidate",
+                    KeyConditionExpression: "#key = :key AND #revalidatedAt > :lastModified",
+                    ExpressionAttributeNames: {
+                        "#key": "path",
+                        "#revalidatedAt": "revalidatedAt",
+                    },
+                    ExpressionAttributeValues: {
+                        ":key": { S: buildDynamoKey(key) },
+                        ":lastModified": { N: String(lastModified ?? 0) },
+                    },
+                }));
+                items = result.Items ?? [];
+                itemsCache?.set(cacheKey, items);
+            }
+            debug("isStale items", key, items);
+            return items.length > 0;
+        }
+        catch (e) {
+            error("Failed to check stale tags", e);
+            return false;
+        }
+    },
     async writeTags(tags) {
         try {
             if (globalThis.openNextConfig.dangerous?.disableTagCache) {
@@ -114,7 +196,7 @@ const tagCache = {
                     [CACHE_DYNAMO_TABLE ?? ""]: Items.map((Item) => ({
                         PutRequest: {
                             Item: {
-                                ...buildDynamoObject(Item.path, Item.tag, Item.revalidatedAt),
+                                ...buildDynamoObject(Item.path, Item.tag, Item.revalidatedAt, Item.stale, Item.expire),
                             },
                         },
                     })),

package/dist/overrides/tagCache/fs-dev-nextMode.d.ts

@@ -3,6 +3,7 @@ declare const _default: {
     mode: "nextMode";
     getLastRevalidated: (tags: string[]) => Promise<number>;
     hasBeenRevalidated: (tags: string[], lastModified?: number) => Promise<boolean>;
-    writeTags: (tags: string[]) => Promise<void>;
+    isStale: (tags: string[], lastModified?: number) => Promise<boolean>;
+    writeTags: (tags: import("../../types/overrides").NextModeTagCacheWriteInput[]) => Promise<void>;
 };
 export default _default;

package/dist/overrides/tagCache/fs-dev-nextMode.js

@@ -9,9 +9,9 @@ export default {
         }
         let lastRevalidated = 0;
         tags.forEach((tag) => {
-            const tagTime = tagsMap.get(tag);
-            if (tagTime && tagTime > lastRevalidated) {
-                lastRevalidated = tagTime;
+            const tagData = tagsMap.get(tag);
+            if (tagData && tagData.revalidatedAt > lastRevalidated) {
+                lastRevalidated = tagData.revalidatedAt;
             }
         });
         debug("getLastRevalidated result:", lastRevalidated);
@@ -21,13 +21,37 @@ export default {
         if (globalThis.openNextConfig.dangerous?.disableTagCache) {
             return false;
         }
+        const now = Date.now();
         const hasRevalidatedTag = tags.some((tag) => {
-            const tagRevalidatedAt = tagsMap.get(tag);
-            return tagRevalidatedAt ? tagRevalidatedAt > (lastModified ?? 0) : false;
+            const tagData = tagsMap.get(tag);
+            if (!tagData) {
+                return false;
+            }
+            // Check if tag has expired
+            if (typeof tagData.expire === "number") {
+                const isExpired = tagData.expire <= now && tagData.expire > (lastModified ?? 0);
+                return isExpired;
+            }
+            // Check if tag has been revalidated
+            return tagData.revalidatedAt > (lastModified ?? 0);
         });
         debug("hasBeenRevalidated result:", hasRevalidatedTag);
         return hasRevalidatedTag;
     },
+    isStale: async (tags, lastModified) => {
+        if (globalThis.openNextConfig.dangerous?.disableTagCache) {
+            return false;
+        }
+        const hasStaleTag = tags.some((tag) => {
+            const tagData = tagsMap.get(tag);
+            if (!tagData || typeof tagData.stale !== "number") {
+                return false;
+            }
+            return tagData.stale > (lastModified ?? 0);
+        });
+        debug("isStale result:", hasStaleTag);
+        return hasStaleTag;
+    },
     writeTags: async (tags) => {
         if (globalThis.openNextConfig.dangerous?.disableTagCache ||
             tags.length === 0) {
@@ -35,7 +59,14 @@ export default {
         }
         debug("writeTags", { tags: tags });
         tags.forEach((tag) => {
-            tagsMap.set(tag, Date.now());
+            const tagStr = typeof tag === "string" ? tag : tag.tag;
+            const stale = typeof tag === "string" ? undefined : tag.stale;
+            const expire = typeof tag === "string" ? undefined : tag.expire;
+            tagsMap.set(tagStr, {
+                revalidatedAt: Date.now(),
+                stale,
+                expire,
+            });
         });
         debug("writeTags completed, written", tags.length, "tags");
     },