Expose the internal cache function used by the "use cache" directive

[sannajammeh]

Goals

1. Allow library authors to better implement automated caching
2. Allow CMS's to expose pre-defined SDKs which automatically manages caching
3. Allow developers with enough experience write more complex caching heuristics

Non-Goals

1. Documentation

Background

The unstable_cache function works great, but as you know it requires the tags and keyparts to be defined ahead of time.

From my understanding the cache function used internally by useCache runs through ALS. Meaning the features exposed by "use cache" like cacheTag & cacheLife are still usable with this.

We author several SDK's and fetch libraries. With "use cache" all caching must be handled by the consumers, but it doesn't have to be this way.

Our current libraries accept a cache function:

import { unstable_cache } from "next/cache";

const sdk = new SDK({
  cacheFn: unstable_cache
})

Meaning each call to sdk.getUser("bob") can be automatically tagged with user:bob and invalidated automatically.

This makes webhook calls a breeze as we also only expose a single revalidate endpoint

import { createRevalidateWebhook } from "my-sdk"

export const { GET } = createRevalidateWebhook();

And thats it. Our consumers now don't have to think about caching, at all.

Proposal

My proposal is simple as the underlying unstable_cache gets deprecated:

Expose the internal ALS powered cache function directly. Either by calling it cache or something more discrete to discourage users createCacheScope.

Our SDK would then look like so:

import {  cache, cacheTag, cacheLife  } from "next/cache" // or createCacheScope

export const sdk = new SDK({
  cache: {
  	scope: cache,
    cacheTag: cacheTag,
    cacheLife: cacheLife,
  }
});

Interally this now happens:

const user = sdk.getUser("bob")

1. SDK internally wraps the API call to someservice.com/users/bob in cache
2. Data is returned and the SDK cache tags this call with user:bob
3. Revalidate endpoint from the background will just work.
4. Consumers of this library does not have to care about cache, at all.

[lubieowoce]

I don't know the details of your SDK, but if you're writing some support for a next.js-specific API anyway (AFAIK nothing else uses an API like cacheTag and cacheLife), couldn't you also just tag the sdk.getUser function with the "use cache" directive and get the same benefit? the directive is a no-op in non-next.js contexts so it wouldn't affect other integrations.

[sannajammeh]

couldn't you also just tag the sdk.getUser function with the "use cache" directive and get the same benefit? the directive is a no-op in non-next.js contexts so it wouldn't affect other integrations.

This is what we ended up doing. We were a bit unsure if your compilers would recognise this in node_modules, but it seems to be working.