Goals

1. Allow developers to specify which parameters should be excluded from cache key generation
2. Maintain the simplicity of the use cache directive while adding more control
3. Improve caching effectiveness for authentication scenarios and other cases with frequently changing but non-essential parameters

My specific use case:

I'm using Clerk for authentication and have an external backend service that requires a token in API calls. Since I can't use Clerk's getToken() inside a method marked with use cache, I need to:

1. Get the token before calling my API method
2. Pass the token to the API method to include it in the request header

Problem: Even when the token isn't expired, Clerk's getToken() returns a new token string each time it's called. This means my cache key changes with every request, effectively breaking caching altogether.

Non-Goals

Background

The new caching model in Next.js 15 with dynamicIO and use cache is a significant improvement for simplifying data fetching and caching. However, it lacks granular control over the parameters affecting the cache key.

For example, right now, I have a wrapper around my API call method to get the token and user from the clerk:

export const withBaseHeaders = async <T>(
  apiCallFn: (authRequest: AuthRequest) => Promise<T>,
  options: AuthOptions = {
    redirectToLogin: true,
    adminRequired: false,
  }
): Promise<T> => {
  const { token, userId } = await getRequestAuth(options);
  return apiCallFn({ token, userId });
};

export const withAccessToken = async <T>(
  apiCallFn: (token: string) => Promise<T>,
  options: AuthOptions = {
    redirectToLogin: true,
    adminRequired: false,
  }
): Promise<T> => {
  const token = await getAccessToken(options);
  return apiCallFn(token);
};

Then this is the place I'm using it:

  const result = await withBaseHeaders((authRequest) => {
    return getNucleiScans(authRequest, {
      ...filterParams,
      status: status,
    });
  });

And this is the API call file:

export const getNucleiScans = async (
  authRequest: AuthRequest,
  params?: NucleiScanParams
) => {
  "use cache";
  cacheTag(getNucleiGlobalTag());
  cacheLife("default");

  const searchParams = new URLSearchParams();
  if (params) {
    addAllFilterParams(searchParams, params);

    if (params.status.length > 0) {
      searchParams.set("Status", params.status.join(","));
    }
  }

  return await readData<PaginatedResult<NucleiScan>>(
    `${ASSESS_MODULE_BASE_PATH}/nuclei?${searchParams.toString()}`,
    {
      token: authRequest.token
    }
  );
};

And readData is actually a helper method that is using the fetch under the hood

Proposal

I propose adding a way to specify which parameters should be excluded from the cache key generation when using the use cache directive. This could be implemented in several ways:

1. A new directive parameter: "use cache { exclude: ['token'] }"
2. A separate directive: "use cache-exclude token"
3. A decorator pattern: "use cache" // @exclude-from-cache token

I'm interested in contributing to discussions around this feature and potentially helping with implementation if guidance is provided on the preferred approach.

Feature request:

Is there a way to specify that certain parameters (like an authentication token) should be ignored when generating the cache key? This would allow caching methods based only on relevant parameters while still accepting necessary values like authentication tokens.

Something like:

// Hypothetical syntax
"use cache" // with some way to exclude 'token' from cache key generation
async function fetchData(userId: string, token: string) {
  // token would be used in the request, but not affect the cache key
}

This would be extremely helpful for authentication scenarios where tokens need to be passed but shouldn't invalidate caches.