Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .changeset/warm-windows-kiss.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
'@tanstack/query-core': minor
---

Add `enforceQueryGcTime` to `QueryClientConfig` to force `gcTime` for all queries created by a client.

When provided, this value overrides `gcTime` from:
- `defaultOptions.queries`
- `setQueryDefaults`
- per-query options passed to query methods
15 changes: 15 additions & 0 deletions docs/reference/QueryClient.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,21 @@ Its available methods are:
- Optional
- Define defaults for all queries and mutations using this queryClient.
- You can also define defaults to be used for [hydration](../framework/react/reference/hydration.md)
- `enforceQueryGcTime?: number`
- Optional
- Forces `gcTime` for every query created by this client, including calls that provide `gcTime` per-query or via `setQueryDefaults`.
- Useful when you need a strict retention policy, for example to keep all query data in cache with `Infinity`.

```tsx
const queryClient = new QueryClient({
enforceQueryGcTime: Infinity,
defaultOptions: {
queries: {
gcTime: 60 * 1000, // ignored because enforceQueryGcTime takes precedence
},
},
})
```

## `queryClient.fetchQuery`

Expand Down
41 changes: 41 additions & 0 deletions packages/query-core/src/__tests__/queryClient.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,47 @@ describe('queryClient', () => {
})

describe('defaultQueryOptions', () => {
test('should enforce gcTime from QueryClient config', () => {
const key = queryKey()
const testClient = new QueryClient({
enforceQueryGcTime: Infinity,
})

expect(
testClient.defaultQueryOptions({ queryKey: key, gcTime: 10 }).gcTime,
).toBe(Infinity)
})

test('should enforce gcTime over matching query defaults', () => {
const key = queryKey()
const testClient = new QueryClient({
enforceQueryGcTime: Infinity,
})

testClient.setQueryDefaults(key, { gcTime: 10 })

expect(testClient.defaultQueryOptions({ queryKey: key }).gcTime).toBe(
Infinity,
)
})

test('should enforce gcTime when query is added to cache', async () => {
const key = queryKey()
const testClient = new QueryClient({
enforceQueryGcTime: Infinity,
})

await testClient.prefetchQuery({
queryKey: key,
queryFn: () => Promise.resolve('data'),
gcTime: 10,
})

expect(
testClient.getQueryCache().find({ queryKey: key })?.options.gcTime,
).toBe(Infinity)
})

test('should default networkMode when persister is present', () => {
expect(
new QueryClient({
Expand Down
6 changes: 6 additions & 0 deletions packages/query-core/src/queryClient.ts
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ export class QueryClient {
#queryCache: QueryCache
#mutationCache: MutationCache
#defaultOptions: DefaultOptions
#enforceQueryGcTime: number | undefined
#queryDefaults: Map<string, QueryDefaults>
#mutationDefaults: Map<string, MutationDefaults>
#mountCount: number
Expand All @@ -72,6 +73,7 @@ export class QueryClient {
this.#queryCache = config.queryCache || new QueryCache()
this.#mutationCache = config.mutationCache || new MutationCache()
this.#defaultOptions = config.defaultOptions || {}
this.#enforceQueryGcTime = config.enforceQueryGcTime
this.#queryDefaults = new Map()
this.#mutationDefaults = new Map()
this.#mountCount = 0
Expand Down Expand Up @@ -593,6 +595,10 @@ export class QueryClient {
_defaulted: true,
}

if (this.#enforceQueryGcTime !== undefined) {
defaultedOptions.gcTime = this.#enforceQueryGcTime
}

if (!defaultedOptions.queryHash) {
defaultedOptions.queryHash = hashQueryKeyByOptions(
defaultedOptions.queryKey,
Expand Down
5 changes: 5 additions & 0 deletions packages/query-core/src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1356,6 +1356,11 @@ export interface QueryClientConfig {
queryCache?: QueryCache
mutationCache?: MutationCache
defaultOptions?: DefaultOptions
/**
* Force all queries created by this client to use the same gcTime.
* This overrides gcTime set globally, per key or per query call.
*/
enforceQueryGcTime?: number
}

export interface DefaultOptions<TError = DefaultError> {
Expand Down
Loading