What is the point of maxAge in PersistQueryClientProvider?

[lisherwin]

Hi!

I've started using PersistQueryClientProvider in my application to persist query data across app sessions. I'm a bit confused why maxAge exists. It seems like it should always be the maximum of:

1. the default cache time and
2. the cacheTime of all dehydrated/hydrated queries in the application.

yet React Query allows us to declare any maxAge. For instance, if we set maxAge to 14 days:

<PersistQueryClientProvider
  client={queryClient}
  persistOptions={{ persister, dehydrateOptions, buster: CACHE_BUSTING_KEY, maxAge: 7*1000*60*60*24 // 7 days.
  ...

and we instantiated our QueryClient to default cacheTime to 7 days:

export const queryClient = new QueryClient({
  defaultOptions: {
    mutations: {
      retry: false,
      networkMode: "offlineFirst",
    },
    queries: {
      staleTime: Infinity,
      cacheTime: 7*1000*60*60*24 // 7 days.
      retry: false,
      refetchOnWindowFocus: false,
      networkMode: "offlineFirst",
    },
  },
});

with a query that we're enabling dehydration on as:

  return useQuery({
    enabled: true,
    queryKey: ["somequerykey"],
    cacheTime: 5*1000*60*60*24 // 5 days

maxAge should always be equal to 7 days.

If we decrease maxAge to 4 days (less than the individual query cacheTime of 5 days), then the query corresponding to query key ["somequerykey"] would get its cacheTime "clipped" to 4 days (instead of the 5 it was declared with). (Correct me if I'm wrong i.e. maxAge is not related at all to cacheTime of individual queries)

If we increase maxAge to 10 days (greater than the default of 7 days), then the queries that default to our QueryClient default cacheTime of 7 days would just use 7 days for its cacheTime since 7 < 10.

So the question is: Shouldn't maxAge always be 7 days in the above example? The maximum of the default query client cacheTime and cacheTimes of all dehydrated queries? Note that I used cacheTimes that I use in my app, but the default cacheTime on the QueryClient could be Infinity, in which case our maxAge would have to increase to be Infinity.

It seem error prone to define a maxAge on our PersistQueryClientProvider and have someone else declare individual queries with cacheTime greater than that maxAge not realizing that their cacheTime would be clipped to the maxAge declared on the PersistQueryClientProvider.

Thank you in advance!

[louis-young]

Hi 👋

This is explained to some degree here: https://tanstack.com/query/v4/docs/react/plugins/persistQueryClient#how-it-works

IMPORTANT - for persist to work properly, you probably want to pass QueryClient a cacheTime value to override the default during hydration (as shown above).

If it is not set when creating the QueryClient instance, it will default to 300000 (5 minutes) for hydration, and the stored cache will be discarded after 5 minutes of inactivity. This is the default garbage collection behavior.

It should be set as the same value or higher than persistQueryClient's maxAge option. E.g. if maxAge is 24 hours (the default) then cacheTime should be 24 hours or higher. If lower than maxAge, garbage collection will kick in and discard the stored cache earlier than expected.

You can also pass it Infinity to disable garbage collection behavior entirely.

To answer your question:

So the question is: Shouldn't maxAge always be 7 days in the above example?

I think it should be seven days. Queries should have a cache time that is equal to or greater than the persisted cache's max-age. If this isn't the case, the persisted cache will be discarded before the query becomes stale. The cache shouldn't live longer than the time that the query is considered fresh.

Hopefully this helps 🙂

[lisherwin]

Thanks @louis-young! Does that mean that if we set a 'maxAge' on our persisted query client, that we should check that every individual query's 'cacheTime' in the app (not just our query client default 'cacheTime') must have a 'cacheTime' > 'maxAge?'

[louis-young]

No worries 🙂

If you're specifying the cache time at query level and you want said query to hydrate from the persisted cache then I think so, yeah.

[garthendrich]

I don't think the question was answered regarding the purpose of maxAge when cacheTime gcTime as a default option already exists, and I'm still struggling to fully understand it.

Let's say I have gcTime: Infinity as a default option, so the data in my web app stays forever while offline. Given the documentation, I also need to set maxAge: Infinity for the persister, which, to me, seems redundant. How do these two options differ in functionality? If possible, could someone please provide example use cases of having different maxAge and default gcTime?

[TkDodo]

with a default gcTime of 5 minutes, this means data will be removed from memory after 5 minutes where it isn’t used. Now imagine you always use that data, and then close your browser tab. Data is persisted, and you go for a holiday and come back 14 days later. Now you restore data from localstorage, and we need to decide if that data should still be used or not? That’s what we use maxAge for.

Sure, if you set them both to Infinity, it seems like you can just use the same value for both situations. But “deleting unused data from memory” is not the same as “re-using data when the app starts”.

[garthendrich]

But “deleting unused data from memory” is not the same as “re-using data when the app starts”.

I really appreciate the quick and clear response! It’s starting to make much more sense to me now.

Is it accurate to have the following as my mental model?

• The "start time" for gcTime exists only during the app's lifecycle, whereas the "start time" for maxAge lives in the local storage.

If it's that simple, I'd feel dumb for having a very hard time wrapping my head around this. But please let me know if my understanding is incorrect.

Also, to clarify, does setting gcTime > maxAge effectively behave the same as gcTime = maxAge?