Undeprecate revalidate APIs and rename expire APIs (#73193)

As discussed we are removing the deprecated field from `revalidateTag`
and `revalidatePath` as they aren't going away anytime soon and the new
`expire` APIs will have slightly different semantics so not a 1-1 rename
with no arguments change anymore. We are also adding the `unstable_`
prefix for `expireTag`/`expirePath` while we iterate on them so it's
clear they will change.

---------

Co-authored-by: Zack Tanner <1939140+ztanner@users.noreply.github.com>

docs/01-app/03-api-reference/04-functions/revalidatePath.mdx

@@ -3,8 +3,6 @@ title: revalidatePath
 description: API Reference for the revalidatePath function.
 ---
 
-**Warning**: `revalidatePath` has been deprecated in favor of `expirePath` and will be removed in a future version.
-
 `revalidatePath` allows you to purge [cached data](/docs/app/building-your-application/caching) on-demand for a specific path.
 
 > **Good to know**:

docs/01-app/03-api-reference/04-functions/revalidateTag.mdx

@@ -3,8 +3,6 @@ title: revalidateTag
 description: API Reference for the revalidateTag function.
 ---
 
-**Warning**: `revalidateTag` has been deprecated in favor of `expireTag` and will be removed in a future version.
-
 `revalidateTag` allows you to purge [cached data](/docs/app/building-your-application/caching) on-demand for a specific cache tag.
 
 > **Good to know**:

docs/01-app/03-api-reference/04-functions/expirePath.mdx → docs/01-app/03-api-reference/04-functions/unstable_expirePath.mdx

@@ -1,104 +1,104 @@
 ---
-title: expirePath
-description: API Reference for the expirePath function.
-version: canary
+title: unstable_expirePath
+description: API Reference for the unstable_expirePath function.
+version: unstable
 ---
 
-`expirePath` allows you to purge [cached data](/docs/app/building-your-application/caching) on-demand for a specific path.
+`unstable_expirePath` allows you to purge [cached data](/docs/app/building-your-application/caching) on-demand for a specific path.
 
 > **Good to know**:
 >
-> - `expirePath` is available in both [Node.js and Edge runtimes](/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes).
-> - `expirePath` only invalidates the cache when the included path is next visited. This means calling `expirePath` with a dynamic route segment will not immediately trigger many expirations at once. The invalidation only happens when the path is next visited.
-> - Currently, `expirePath` invalidates all the routes in the [client-side Router Cache](/docs/app/building-your-application/caching#client-side-router-cache) when used in a server action. This behavior is temporary and will be updated in the future to apply only to the specific path.
-> - Using `expirePath` invalidates **only the specific path** in the [server-side Route Cache](/docs/app/building-your-application/caching#full-route-cache).
+> - `unstable_expirePath` is available in both [Node.js and Edge runtimes](/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes).
+> - `unstable_expirePath` only invalidates the cache when the included path is next visited. This means calling `unstable_expirePath` with a dynamic route segment will not immediately trigger many expirations at once. The invalidation only happens when the path is next visited.
+> - Currently, `unstable_expirePath` invalidates all the routes in the [client-side Router Cache](/docs/app/building-your-application/caching#client-side-router-cache) when used in a server action. This behavior is temporary and will be updated in the future to apply only to the specific path.
+> - Using `unstable_expirePath` invalidates **only the specific path** in the [server-side Route Cache](/docs/app/building-your-application/caching#full-route-cache).
 
 ## Reference
 
 ### Parameters
 
 ```tsx
-expirePath(path: string, type?: 'page' | 'layout'): void;
+unstable_expirePath(path: string, type?: 'page' | 'layout'): void;
 ```
 
 - `path`: Either a string representing the filesystem path associated with the data you want to expire (for example, `/product/[slug]/page`), or the literal route segment (for example, `/product/123`). Must be less than 1024 characters. This value is case-sensitive.
 - `type`: (optional) `'page'` or `'layout'` string to change the type of path to expire. If `path` contains a dynamic segment (for example, `/product/[slug]/page`), this parameter is required. If path refers to the literal route segment, e.g., `/product/1` for a dynamic page (e.g., `/product/[slug]/page`), you should not provide `type`.
 
 ### Returns
 
-`expirePath` does not return a value.
+`unstable_expirePath` does not return a value.
 
 ## Examples
 
 ### Expiring a specific URL
 
 ```ts
-import { expirePath } from 'next/cache'
-expirePath('/blog/post-1')
+import { unstable_expirePath } from 'next/cache'
+unstable_expirePath('/blog/post-1')
 ```
 
 This will purge the cache for one specific URL on the next page visit.
 
 ### Expiring a page path
 
 ```ts
-import { expirePath } from 'next/cache'
-expirePath('/blog/[slug]', 'page')
+import { unstable_expirePath } from 'next/cache'
+unstable_expirePath('/blog/[slug]', 'page')
 // or with route groups
-expirePath('/(main)/blog/[slug]', 'page')
+unstable_expirePath('/(main)/blog/[slug]', 'page')
 ```
 
 This will purge the cache any URL that matches the provided `page` file on the next page visit. This will _not_ invalidate pages beneath the specific page. For example, `/blog/[slug]` won't invalidate `/blog/[slug]/[author]`.
 
 ### Expiring a layout path
 
 ```ts
-import { expirePath } from 'next/cache'
-expirePath('/blog/[slug]', 'layout')
+import { unstable_expirePath } from 'next/cache'
+unstable_expirePath('/blog/[slug]', 'layout')
 // or with route groups
-expirePath('/(main)/post/[slug]', 'layout')
+unstable_expirePath('/(main)/post/[slug]', 'layout')
 ```
 
 This will purge the cache on any URL that matches the provided `layout` file on the next page visit. This will cause pages beneath with the same layout to revalidate on the next visit. For example, in the above case, `/blog/[slug]/[another]` would also revalidate on the next visit.
 
 ### Expiring all data
 
 ```ts
-import { expirePath } from 'next/cache'
+import { unstable_expirePath } from 'next/cache'
 
-expirePath('/', 'layout')
+unstable_expirePath('/', 'layout')
 ```
 
 This will purge the Data Cache on the next page visit.
 
 ### Server Action
 
-You can call `expirePath` in a Server Action:
+You can call `unstable_expirePath` in a Server Action:
 
 ```ts filename="app/actions.ts" switcher
 'use server'
 
-import { expirePath } from 'next/cache'
+import { unstable_expirePath } from 'next/cache'
 
 export default async function submit() {
   await submitForm()
-  expirePath('/')
+  unstable_expirePath('/')
 }
 ```
 
 ### Route Handler
 
-You can call `expirePath` in a Route Handler:
+You can call `unstable_expirePath` in a Route Handler:
 
 ```ts filename="app/api/expire/route.ts" switcher
-import { expirePath } from 'next/cache'
+import { unstable_expirePath } from 'next/cache'
 import type { NextRequest } from 'next/server'
 
 export async function GET(request: NextRequest) {
   const path = request.nextUrl.searchParams.get('path')
 
   if (path) {
-    expirePath(path)
+    unstable_expirePath(path)
     return Response.json({ revalidated: true, now: Date.now() })
   }
 
@@ -111,13 +111,13 @@ export async function GET(request: NextRequest) {
 ```
 
 ```js filename="app/api/expire/route.js" switcher
-import { expirePath } from 'next/cache'
+import { unstable_expirePath } from 'next/cache'
 
 export async function GET(request) {
   const path = request.nextUrl.searchParams.get('path')
 
   if (path) {
-    expirePath(path)
+    unstable_expirePath(path)
     return Response.json({ expired: true, now: Date.now() })
   }
 

docs/01-app/03-api-reference/04-functions/unstable_expireTag.mdx

@@ -0,0 +1,85 @@
+---
+title: unstable_expireTag
+description: API Reference for the unstable_expireTag function.
+version: unstable
+---
+
+`unstable_expireTag` allows you to purge [cached data](/docs/app/building-your-application/caching) on-demand for a specific cache tag.
+
+> **Good to know**:
+>
+> - `unstable_expireTag` is available in both [Node.js and Edge runtimes](/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes).
+> - `unstable_expireTag` only invalidates the cache when the path is next visited. This means calling `unstable_expireTag` with a dynamic route segment will not immediately trigger many expirations at once. The invalidation only happens when the path is next visited.
+
+## Reference
+
+### Parameters
+
+```tsx
+unstable_expireTag(...tags: string[]): void;
+```
+
+- `tags`: String arguments representing the cache tags associated with the data you want to revalidate. Must be less than or equal to 256 characters each. This value is case-sensitive.
+
+You can add tags to `fetch` as follows:
+
+```tsx
+fetch(url, { next: { tags: [...] } });
+```
+
+### Returns
+
+`unstable_expireTag` does not return a value.
+
+## Examples
+
+### Server Action
+
+You can invoke `unstable_expireTag` in a Server Action:
+
+```ts filename="app/actions.ts" switcher
+'use server'
+
+import { unstable_expireTag } from 'next/cache'
+
+export default async function submit() {
+  await addPost()
+  unstable_expireTag('posts', 'blog')
+}
+```
+
+```js filename="app/actions.js" switcher
+'use server'
+
+import { unstable_expireTag } from 'next/cache'
+
+export default async function submit() {
+  await addPost()
+  unstable_expireTag('posts', 'blog')
+}
+```
+
+### Route Handler
+
+You can invoke `unstable_expireTag` in a Route Handler:
+
+```ts filename="app/api/revalidate/route.ts" switcher
+import type { NextRequest } from 'next/server'
+import { unstable_expireTag } from 'next/cache'
+
+export async function GET(request: NextRequest) {
+  const tag = request.nextUrl.searchParams.get('tag')
+  unstable_expireTag(tag)
+  return Response.json({ revalidated: true, now: Date.now() })
+}
+```
+
+```js filename="app/api/revalidate/route.js" switcher
+import { unstable_expireTag } from 'next/cache'
+
+export async function GET(request) {
+  const tag = request.nextUrl.searchParams.get('tag')
+  unstable_expireTag(tag)
+  return Response.json({ revalidated: true, now: Date.now() })
+}
+```

packages/next/cache.d.ts

@@ -3,8 +3,8 @@ export { unstable_cache } from 'next/dist/server/web/spec-extension/unstable-cac
 export {
   revalidatePath,
   revalidateTag,
-  expirePath,
-  expireTag,
+  unstable_expirePath,
+  unstable_expireTag,
 } from 'next/dist/server/web/spec-extension/revalidate'
 
 export { unstable_noStore } from 'next/dist/server/web/spec-extension/unstable-no-store'

packages/next/cache.js

@@ -7,10 +7,10 @@ const cacheExports = {
   revalidatePath: require('next/dist/server/web/spec-extension/revalidate')
     .revalidatePath,
 
-  expireTag: require('next/dist/server/web/spec-extension/revalidate')
-    .expireTag,
-  expirePath: require('next/dist/server/web/spec-extension/revalidate')
-    .expirePath,
+  unstable_expireTag: require('next/dist/server/web/spec-extension/revalidate')
+    .unstable_expireTag,
+  unstable_expirePath: require('next/dist/server/web/spec-extension/revalidate')
+    .unstable_expirePath,
 
   unstable_noStore:
     require('next/dist/server/web/spec-extension/unstable-no-store')
@@ -28,8 +28,8 @@ module.exports = cacheExports
 exports.unstable_cache = cacheExports.unstable_cache
 exports.revalidatePath = cacheExports.revalidatePath
 exports.revalidateTag = cacheExports.revalidateTag
-exports.expireTag = cacheExports.expireTag
-exports.expirePath = cacheExports.expirePath
+exports.unstable_expireTag = cacheExports.unstable_expireTag
+exports.unstable_expirePath = cacheExports.unstable_expirePath
 exports.unstable_noStore = cacheExports.unstable_noStore
 exports.unstable_cacheLife = cacheExports.unstable_cacheLife
 exports.unstable_cacheTag = cacheExports.unstable_cacheTag

packages/next/src/build/webpack/plugins/next-types-plugin/index.ts

@@ -689,8 +689,8 @@ declare module 'next/cache' {
   export {
     revalidateTag,
     revalidatePath,
-    expireTag,
-    expirePath,
+    unstable_expireTag,
+    unstable_expirePath,
   } from 'next/dist/server/web/spec-extension/revalidate'
   export { unstable_noStore } from 'next/dist/server/web/spec-extension/unstable-no-store'