feat(query-core): add enforceQueryGcTime query client option

[Tseian]

🎯 Changes

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested this code locally with pnpm run test:pr.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

• New Features

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

• Documentation

  • Updated QueryClient reference documentation with the new enforceQueryGcTime configuration option and usage examples.

• Tests

  • Added test coverage for enforceQueryGcTime behavior and precedence rules.

[coderabbitai]

📝 Walkthrough

Walkthrough

A new enforceQueryGcTime configuration option is introduced to QueryClient that forces a uniform garbage collection time for all queries, overriding per-query and default option configurations. The feature includes type definitions, implementation logic, comprehensive tests, and documentation.

Changes

Cohort / File(s)	Summary
Configuration & Type Definitions packages/query-core/src/types.ts, .changeset/warm-windows-kiss.md	Added enforceQueryGcTime?: number optional property to QueryClientConfig interface with documented contract explaining override behavior across all query configuration levels.
Implementation packages/query-core/src/queryClient.ts	Added private #enforceQueryGcTime field to QueryClient initialized from config, with logic in defaultQueryOptions to overwrite defaultedOptions.gcTime when the enforced value is set.
Documentation docs/reference/QueryClient.md	Added documentation for enforceQueryGcTime?: number option with explanation of precedence behavior and example demonstrating override of defaultOptions.queries.gcTime.
Tests packages/query-core/src/__tests__/queryClient.test.tsx	Added three tests verifying enforceQueryGcTime overrides explicit gcTime values in defaultQueryOptions, query defaults via setQueryDefaults, and prefetchQuery operations.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A gcTime to rule them all, we've declared,
No query shall escape its grasp so fair,
From defaults deep to prefetch calls divine,
One enforced value makes the timing align,
The Warren's keeper guards garbage with care! 🗑️✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description consists only of template placeholders with unchecked checklist items. The required 'Changes' section contains only an empty comment with no actual description of what was changed or why.	Fill in the 'Changes' section with details about the enforceQueryGcTime feature, its motivation, and usage. Check relevant checklist items (changeset has been generated; confirm local testing).

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding the enforceQueryGcTime option to the QueryClient, matching the implementation details in the changeset and code modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/query-core/src/queryClient.ts (1)

581-600: ⚠️ Potential issue | 🟠 Major

Apply enforcement before returning already-defaulted options.

Line 581 returns _defaulted options before Line 598 can overwrite gcTime. A defaulted options object produced elsewhere can therefore bypass enforceQueryGcTime and create/cache a query with the original gcTime.

🐛 Proposed fix

     if (options._defaulted) {
+      if (this.#enforceQueryGcTime !== undefined) {
+        options.gcTime = this.#enforceQueryGcTime
+      }
       return options as DefaultedQueryObserverOptions<
         TQueryFnData,
         TError,

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/query-core/src/queryClient.ts` around lines 581 - 600, The early
return when options._defaulted bypasses the enforceQueryGcTime override; before
returning an already-defaulted options object (check options._defaulted), apply
the enforcement by setting options.gcTime = this.#enforceQueryGcTime when
this.#enforceQueryGcTime is not undefined, then return the casted
DefaultedQueryObserverOptions. For the non-_defaulted path, keep the existing
merge that builds defaultedOptions and continue to apply the same
this.#enforceQueryGcTime override to defaultedOptions.gcTime as currently
implemented.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@packages/query-core/src/queryClient.ts`:
- Around line 581-600: The early return when options._defaulted bypasses the
enforceQueryGcTime override; before returning an already-defaulted options
object (check options._defaulted), apply the enforcement by setting
options.gcTime = this.#enforceQueryGcTime when this.#enforceQueryGcTime is not
undefined, then return the casted DefaultedQueryObserverOptions. For the
non-_defaulted path, keep the existing merge that builds defaultedOptions and
continue to apply the same this.#enforceQueryGcTime override to
defaultedOptions.gcTime as currently implemented.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 85aefe41-14a4-4335-aa2e-4d53535c49de

📥 Commits

Reviewing files that changed from the base of the PR and between a3ec7b3 and d63cdad.

📒 Files selected for processing (5)

• .changeset/warm-windows-kiss.md
• docs/reference/QueryClient.md
• packages/query-core/src/__tests__/queryClient.test.tsx
• packages/query-core/src/queryClient.ts
• packages/query-core/src/types.ts