Expose callback parameters when specifying tags in unstable_cache

[s-fletcher]

Goals

1. Provide ability to have more targeted tags in unstable_cache
2. Decrease number of unnecessary invalidations from revalidateTag

Non-Goals

No response

Background

Take the below example.

import { getUser } from './data';
import { unstable_cache } from 'next/cache';
 
const getCachedUser = unstable_cache(
  async (userId) => getUser(userId),
  ['my-app-user'],
  { tags: ['my-app-user'] }
);

Say we have many users with a unique userId on our website that use getCachedUser.

A single user updates their profile. We need to invalidate getCachedUser now that our cache is stale.

At first glance, you may want to call revalidateTag('my-app-user') to invalidate the cache. However, by doing this you are now unnecessarily invalidating the cache for every userId instead of just the single user's id.

The solution (right now) is to wrap the unstable_cache in another function where you can access the parameters to use inside of tags.

import { getUser } from './data';
import { unstable_cache } from 'next/cache';
 
const getCachedUser = (userId) => unstable_cache(
  async (userId) => getUser(userId),
  ['my-app-user'],
  { tags: [`my-app-user-${userId}`] }
)(userId);

Proposal

Let's give the developer access to the callback's parameters inside of tags. This will incentivize developers to use more targeted tags to prevent unnecessary invalidations.

Proposed API:

function unstable_cache<T extends Callback>(cb: T, keyParts?: string[], options?: {
    revalidate?: number | false | undefined;
    tags?: string[] | ((parameters: Parameters<T>) => string[]);
}): T

Proposed usage:

import { getUser } from './data';
import { unstable_cache } from 'next/cache';
 
const getCachedUser = unstable_cache(
  async (userId) => getUser(userId),
  ['my-app-user'],
  { tags: (userId) => [`my-app-user-${userId}`] }
);

[kronick]

I like this idea and would propose that it could be taken one step further by providing the result of the callback function to generate cache tags. The specific use case I have in mind for this is when trying to cache the results of a database query that performs joins across multiple entities and needing to revalidate the cache whenever any of those joined objects are modified.

Here's an example using Prisma client as the ORM to perform the join / nested query:

function _getUsersAndPosts(userId: string) {
  return prisma.user.findUniqueOrThrow({
    include: {
      posts: true
    }
  })
}

// Cached version of the above query
const getUsersAndPostsCached = unstable_cache(
  async (userId: string) => _getUsersAndPosts(userId),
  ['getUsersAndPosts'],
  { tags: (params: {userId: string}, result: Awaited<ReturnType<typeof _getUsersAndPosts>>}) => [
      `USER-${result.id}`,
      `USER-${result.id}-POSTS`,
      ...result.posts.map(p => `POST-${p.id}`),
    ]
  }

// Below are some pseudo-code server actions that perform mutations which somehow impact the results of the cached query
async function editUserDetails(...options) {
  // Perform some mutation on the user here...
  await prisma.user.update(...options);

  // Then revalidate the user data directly
  revalidateTag(`USER-${options.userId}`)
}

async function editPost(...options) {
  // Perform some mutation on the post
  await prisma.post.update(...options);

  // This should revalidate the relevant user queries, too, without this server action needing to know which queries those are
  revalidateTag(`POST-${options.postId}`)
}

async function createPost(...options) {
  // Create the post and associate it with the user
  await prisma.post.create(...options);
  
  // Any query listing posts for that user needs to be revalidated since there is a new entry in the list
  revalidateTag(`USER-${options.authorId}-POSTS`);

Ideally this could be combined with a feature like Prisma Client Extensions (or the equivalent in other data access libraries) to automatically cache and revalidate queries as data is muated.