feature request: Add enforceQueryGcTime option to QueryClient configuration, allowing developers to enforce a single garbage collection time across all queries, overriding per-query or global settings.

[Tseian]

https://github.com/Tseian/nextjs-querycache-memory-leak/blob/main/README.md

In the above recurrence demo, it is difficult for users to find out why the memory increases rapidly. Secondly, even if the problem is found and can be solved by setting all useQuery method parameter cacheTime/gcTime to Infinity. There will be many changes. So I hope that when creating QueryClient, I can pass a parameter like enforceQueryGcTime: Infinity to force all Query instances created through the useQuery method to not remain when the component is unmounted, let the large amount of data injected through prefetch heydrate to be released immediately.

/** A set of type-safe react-query hooks for your tRPC API. */
export const api = createTRPCNext<AppRouter>({
  config() {
    return {
      queryClientConfig: {
        enforceQueryGcTime: isServer? Infinity : undefined,
        defaultOptions: {
          queries: {},
        },
      },
    }
  },
ssr: false
})

api.xx.xx.useQuery({
    gcTime: 3 * 60 * 60 * 1000,  // gcTime will be replace by  enforceQueryGcTime if enforceQueryGcTime has a value
})

I have created a PR for this, PR. If there is any other better solution, pls just write down in the comment.

Query2 will be store in memory until setTimeout callback be invoked when cacheTime/gcTime expires. Prefetch hydrated Query1's gcTime/cacheTime is default value infinity. Both Query1 and Query2 are held by the same QueryCache, so Query1 cannot be released until Query2 is released.

[TkDodo]

There will be many changes

If you want a single gcTime, set it globally and don’t set it again on the hooks level.

You can also use our timeoutManager to handle timeouts differently on the server: https://tanstack.com/query/v5/docs/reference/timeoutManager

[Tseian]

If you want a single gcTime, set it globally and don’t set it again on the hooks level.

@TkDodo Thanks for your suggestion. For all I know in the case of nextjs ssr with ssr:false, method useQuery will be executed twice, one time in the server side and it creates an empty Query, another time in the browser and it creates a Query that truly fetch data from the API. Usually developers will set a gcTime according to the api response, if developers forget to set gcTime like isServer? Infinity: 60000, just set gcTime 60000, the empty query will be stored in memory for 60s, and it also makes the prefetch hydrated Query instance that has a lot of data
will be stored in memory until gcTime expires.

[Tseian]

Currently we use the following code to avoid heap memory increases rapidly in server side, but I don't think it is a good solution.

// lib/trpc.ts
const isServer = typeof window === 'undefined'

class ServerSafeQueryCache extends QueryCache {
  build(client: any, options: any, state?: any) {
    return super.build(client, { ...options, cacheTime: Infinity }, state)
  }
}

export const trpc = createTRPCNext<AppRouter>({
  config(opts) {
    const queryClientConfig = { /* ... */ }

    if (isServer) {
      queryClientConfig.queryCache = new ServerSafeQueryCache()
    } else {
      queryClientConfig.queryCache = new QueryCache()
    }

    return { queryClientConfig, links: [/* ... */] }
  },
  ssr: false,
})

[TkDodo]

Usually developers will set a gcTime according to the api response

Why would you do that? gcTime only has an effect when a query is unused. I would usually just keep the defaults unless you have a good reason

[Tseian]

As far as I know, when the query cache enters the destruction countdown, if there is the same API call, the data in this query will be reused. For avoiding to request the api again we cache some query data in browser by setting a cacheTime.

[Tseian]

As far as I know, when the query cache enters the destruction countdown, if there is the same API call, the data in this query will be reused. For avoiding to request the api again we cache some query data in browser by setting a cacheTime.

But after setting a cacheTime, The prefetch data will be accidentally cached in memory until the cacheTime expires.
Of course, we can use 'isServer? cacheTime' to calculate cacheTime on every useQuery call, or manually release it with trpc utils after ssr, but I don't think these are a good solution, so I created this discussion.

Are there some developers encounter the same problem? How do you resolve it?

[TkDodo]

I don’t fully understand what you’re talking about. We don’t have a cacheTime setting (anymore), so please don’t use that terminology, it’s confusing. We have staleTime and gcTime. They both do different things.

when the query cache enters the destruction countdown, if there is the same API call, the data in this query will be reused

if a new observer mounts while you still have cached data that has not been garbage collected, yes, it will be re-used. The “API call” depends on staleTime though. If the data is considered stale, you will get a new refetch.