unstable_cache behavior with stale data is unclear

[TreeOfSelf]

Summary

So, as far as the documentation, what I have been told by people in the unofficial next.js discord, it would seem that when unstable_cache is queried and the cache is stale, it would provide you with stale data and then run the revalidation function in the background.

However, even when running my application in production mode, this is not at all the behavior I see. When the revalidate time is up, the function will wait until the new data from the function arrives and if the browser is relying on it, it will just sit there waiting til it arrives rather than showing the stale data (which I would much prefer).

Is there something I am doing wrong/misunderstanding/additionally needing to get this to work?

Additional information

No response

Example

No response

[sunnypatell]

Try ensuring your function includes:

import { unstable_cache } from 'next/cache';

const fetchData = async () => {
  const data = await fetch('https://api.example.com/data').then(res => res.json());
  return data;
};

export const getCachedData = unstable_cache(fetchData, ['my-cache-key'], { revalidate: 60 });

Then in your component:

const data = await getCachedData();

Run in production mode with logging:

const fetchData = async () => {
  console.log('Fetching fresh data...');
  const data = await fetch('https://api.example.com/data').then(res => res.json());
  return data;
};

export const getCachedData = unstable_cache(fetchData, ['my-cache-key'], { revalidate: 60 });

Then check if fresh data is fetched immediately or only after a delay.

Workaround: Manually Implementing Stale-While-Revalidate

If unstable_cache isn't working as expected, you can manually structure it like this:

const cachedData = cache.get('my-cache-key');

if (cachedData) {
  // Serve stale data immediately
  return cachedData;
}

// Fetch fresh data in the background
const freshData = await fetchData();
cache.set('my-cache-key', freshData, { revalidate: 60 });

return freshData;

• unstable_cache should return stale data, but misconfigurations can cause blocking.
• If necessary, implement manual stale-while-revalidate logic.
• Ensure requests occur before cache expiry to avoid a full re-fetch block.

[TreeOfSelf]

Hey, thanks for the detailed answer.

So, the issue is I would like it so that it is never blocking except for on the first load. The first load, obviously it has to be blocking, but subsequent loads I would always like to display what is cached. If revalidation period is over, I do not want it blocked, I would like it to display what is in cache, then run the revalidation in the background.

Is this possible? My processMapData is very computationally expensive, runs on another thread. So, it would very nice to have this functionality.

Thanks.

const getCachedMapData = (filePath: string) =>
    unstable_cache(
      async (filePath: string) => {
        const mapData = await processMapData(filePath);
        return {
            compressedVolume : Array.from(mapData.compressedVolume),
            dims : mapData.dims
        };
      },
      [],
      { revalidate: 120, tags: [`voxel_${filePath}`] },
)(filePath);

export default async function GetMapData(filePath: string) {
    const cachedMapData = await getCachedMapData(filePath);
    return {
        compressedVolume : new Uint8Array(cachedMapData.compressedVolume),
        dims: cachedMapData.dims
    };
}

[sunnypatell]

I see what you're asking now.. you want unstable_cache to always return cached data immediately, even after the revalidate period, and only update in the background.

Try this:

const cache = new Map(); // Replace with a more persistent cache if needed

const getCachedMapData = async (filePath) => {
  const cacheKey = `voxel_${filePath}`;
  const cachedEntry = cache.get(cacheKey);

  if (cachedEntry) {
    // If cache exists, return immediately & revalidate in the background
    if (Date.now() < cachedEntry.expiry) {
      return cachedEntry.data;
    } else {
      revalidateInBackground(filePath, cacheKey);
      return cachedEntry.data; // Serve stale data
    }
  }

  // First load: Block and store result
  const freshData = await processMapData(filePath);
  cache.set(cacheKey, { data: formatData(freshData), expiry: Date.now() + 120 * 1000 });
  return freshData;
};

const revalidateInBackground = async (filePath, cacheKey) => {
  const freshData = await processMapData(filePath);
  cache.set(cacheKey, { data: formatData(freshData), expiry: Date.now() + 120 * 1000 });
};

const formatData = (mapData) => ({
  compressedVolume: Array.from(mapData.compressedVolume),
  dims: mapData.dims,
});

export default async function GetMapData(filePath) {
  const cachedMapData = await getCachedMapData(filePath);
  return {
    compressedVolume: new Uint8Array(cachedMapData.compressedVolume),
    dims: cachedMapData.dims,
  };
}

Hopefully it fixes it, it should

• First load blocks (as required).
• Subsequent loads always return cached data immediately, even if expired.
• Revalidation happens in the background without blocking.

lmk!

[TreeOfSelf]

Thanks, I will give something like that a shot. Good to know unstable_cache does not support anything like that.
I think manually handling caching is what I will end up having to do for
#75461
as well.

Cheers.

[sengirab]

Very curious to what you ended up doing @TreeOfSelf - i'm currently facing the same kind of issues and choices.

[TreeOfSelf]

Very curious to what you ended up doing @TreeOfSelf - i'm currently facing the same kind of issues and choices.

https://www.npmjs.com/package/next-quick-cache

Ended up making this.