Skip to content

feat(core): callback for retryOnMount#10515

Open
TkDodo wants to merge 4 commits intomainfrom
feature/feat/callback-for-retryOnMount
Open

feat(core): callback for retryOnMount#10515
TkDodo wants to merge 4 commits intomainfrom
feature/feat/callback-for-retryOnMount

Conversation

@TkDodo
Copy link
Copy Markdown
Collaborator

@TkDodo TkDodo commented Apr 18, 2026

Summary by CodeRabbit

Release Notes

  • New Features

    • retryOnMount option now supports callback functions that receive the query object to determine retry behavior on mount.
  • Documentation

    • Updated retryOnMount documentation across React, Solid, and Vue frameworks with the new callback function signature.
  • Bug Fixes

    • Refined retryOnMount: false behavior to only prevent retry when the query has an error and no data.

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai bot commented Apr 18, 2026

📝 Walkthrough

Walkthrough

This PR extends the retryOnMount option to accept a callback function (query: Query) => boolean alongside its existing boolean support. The core resolver function resolveEnabled is renamed to resolveQueryBoolean and consistently applied across query logic. The type Enabled is renamed to QueryBooleanOption for semantic clarity. Tests are updated to validate callback behavior.

Changes

Cohort / File(s) Summary
Release & Documentation
.changeset/silver-places-pick.md, docs/framework/react/reference/useQuery.md, docs/framework/solid/reference/useQuery.md
Added changeset for minor version; updated retryOnMount type to boolean | (query: Query) => boolean and clarified behavior (retry on mount only when query has error and no data). Function form is invoked with the query to compute the boolean value.
Core Type System
packages/query-core/src/types.ts, packages/query-core/src/utils.ts
Renamed exported type EnabledQueryBooleanOption<...> to represent boolean | ((query) => boolean). Renamed helper function resolveEnabledresolveQueryBoolean with matching signature updates. Updated QueryObserverOptions.retryOnMount from boolean to QueryBooleanOption.
Core Logic Implementation
packages/query-core/src/query.ts, packages/query-core/src/queryObserver.ts
Replaced all resolveEnabled calls with resolveQueryBoolean for enabled-state computations and mount/fetch decision logic. Updated shouldLoadOnMount to use resolveQueryBoolean for both enabled and retryOnMount when query is in error state.
Vue Query Types
packages/vue-query/src/queryOptions.ts, packages/vue-query/src/useQuery.ts
Updated QueryOptions and UseQueryOptions to import and use QueryBooleanOption instead of Enabled for the enabled option's function overload return type.
Test Updates - React/Preact
packages/react-query/src/__tests__/QueryResetErrorBoundary.test.tsx, packages/react-query/src/__tests__/useQuery.test.tsx, packages/preact-query/src/__tests__/QueryResetErrorBoundary.test.tsx, packages/preact-query/src/__tests__/useQuery.test.tsx
Updated test cases to use retryOnMount: () => true/false callback form instead of boolean literals. Added two new test cases verifying callback behavior: one asserting callback receives error-state query with no data, another asserting callback is skipped when query already has data.
Test Updates - Solid
packages/solid-query/src/__tests__/useQuery.test.tsx
Updated test cases to use retryOnMount: () => false callback form instead of boolean literals in error/key-change scenarios.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A query's retry, now smarter and true,
With callbacks to filter what retry should do!
No more blanket rules—now the query is passed,
So decisions stay nimble, their logic unsurpassed.
hops excitedly

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (2 warnings)

Check name Status Explanation Resolution
Description check ⚠️ Warning No pull request description was provided; the required template sections for explaining changes, checklist items, and release impact are completely missing. Add a description following the template: explain the changes/motivation under '🎯 Changes', complete the '✅ Checklist', and confirm changeset generation under '🚀 Release Impact'.
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (1 passed)
Check name Status Explanation
Title check ✅ Passed The title 'feat(core): callback for retryOnMount' clearly summarizes the main change - adding callback function support for the retryOnMount option in the core package.

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

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feature/feat/callback-for-retryOnMount

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

@nx-cloud
Copy link
Copy Markdown

nx-cloud bot commented Apr 18, 2026

View your CI Pipeline Execution ↗ for commit b40fb96

Command Status Duration Result
nx affected --targets=test:sherif,test:knip,tes... ✅ Succeeded 4m 3s View ↗
nx run-many --target=build --exclude=examples/*... ✅ Succeeded 2s View ↗

☁️ Nx Cloud last updated this comment at 2026-04-20 06:48:16 UTC

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 18, 2026

🚀 Changeset Version Preview

1 package(s) bumped directly, 23 bumped as dependents.

🟨 Minor bumps

Package Version Reason
@tanstack/query-core 5.99.2 → 5.100.0 Changeset
@tanstack/angular-query-experimental 5.99.2 → 5.100.0 Dependent
@tanstack/angular-query-persist-client 5.99.2 → 5.100.0 Dependent
@tanstack/eslint-plugin-query 5.99.2 → 5.100.0 Dependent
@tanstack/preact-query 5.99.2 → 5.100.0 Dependent
@tanstack/preact-query-devtools 5.99.2 → 5.100.0 Dependent
@tanstack/preact-query-persist-client 5.99.2 → 5.100.0 Dependent
@tanstack/query-async-storage-persister 5.99.2 → 5.100.0 Dependent
@tanstack/query-broadcast-client-experimental 5.99.2 → 5.100.0 Dependent
@tanstack/query-devtools 5.99.2 → 5.100.0 Dependent
@tanstack/query-persist-client-core 5.99.2 → 5.100.0 Dependent
@tanstack/query-sync-storage-persister 5.99.2 → 5.100.0 Dependent
@tanstack/react-query 5.99.2 → 5.100.0 Dependent
@tanstack/react-query-devtools 5.99.2 → 5.100.0 Dependent
@tanstack/react-query-next-experimental 5.99.2 → 5.100.0 Dependent
@tanstack/react-query-persist-client 5.99.2 → 5.100.0 Dependent
@tanstack/solid-query 5.99.2 → 5.100.0 Dependent
@tanstack/solid-query-devtools 5.99.2 → 5.100.0 Dependent
@tanstack/solid-query-persist-client 5.99.2 → 5.100.0 Dependent
@tanstack/vue-query 5.99.2 → 5.100.0 Dependent

🟩 Patch bumps

Package Version Reason
@tanstack/svelte-query 6.1.18 → 6.1.19 Dependent
@tanstack/svelte-query-devtools 6.1.18 → 6.1.19 Dependent
@tanstack/svelte-query-persist-client 6.1.18 → 6.1.19 Dependent
@tanstack/vue-query-devtools 6.1.18 → 6.1.19 Dependent

@pkg-pr-new
Copy link
Copy Markdown

pkg-pr-new bot commented Apr 18, 2026

More templates

@tanstack/angular-query-experimental

npm i https://pkg.pr.new/@tanstack/angular-query-experimental@10515

@tanstack/eslint-plugin-query

npm i https://pkg.pr.new/@tanstack/eslint-plugin-query@10515

@tanstack/preact-query

npm i https://pkg.pr.new/@tanstack/preact-query@10515

@tanstack/preact-query-devtools

npm i https://pkg.pr.new/@tanstack/preact-query-devtools@10515

@tanstack/preact-query-persist-client

npm i https://pkg.pr.new/@tanstack/preact-query-persist-client@10515

@tanstack/query-async-storage-persister

npm i https://pkg.pr.new/@tanstack/query-async-storage-persister@10515

@tanstack/query-broadcast-client-experimental

npm i https://pkg.pr.new/@tanstack/query-broadcast-client-experimental@10515

@tanstack/query-core

npm i https://pkg.pr.new/@tanstack/query-core@10515

@tanstack/query-devtools

npm i https://pkg.pr.new/@tanstack/query-devtools@10515

@tanstack/query-persist-client-core

npm i https://pkg.pr.new/@tanstack/query-persist-client-core@10515

@tanstack/query-sync-storage-persister

npm i https://pkg.pr.new/@tanstack/query-sync-storage-persister@10515

@tanstack/react-query

npm i https://pkg.pr.new/@tanstack/react-query@10515

@tanstack/react-query-devtools

npm i https://pkg.pr.new/@tanstack/react-query-devtools@10515

@tanstack/react-query-next-experimental

npm i https://pkg.pr.new/@tanstack/react-query-next-experimental@10515

@tanstack/react-query-persist-client

npm i https://pkg.pr.new/@tanstack/react-query-persist-client@10515

@tanstack/solid-query

npm i https://pkg.pr.new/@tanstack/solid-query@10515

@tanstack/solid-query-devtools

npm i https://pkg.pr.new/@tanstack/solid-query-devtools@10515

@tanstack/solid-query-persist-client

npm i https://pkg.pr.new/@tanstack/solid-query-persist-client@10515

@tanstack/svelte-query

npm i https://pkg.pr.new/@tanstack/svelte-query@10515

@tanstack/svelte-query-devtools

npm i https://pkg.pr.new/@tanstack/svelte-query-devtools@10515

@tanstack/svelte-query-persist-client

npm i https://pkg.pr.new/@tanstack/svelte-query-persist-client@10515

@tanstack/vue-query

npm i https://pkg.pr.new/@tanstack/vue-query@10515

@tanstack/vue-query-devtools

npm i https://pkg.pr.new/@tanstack/vue-query-devtools@10515

commit: b40fb96

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 18, 2026

size-limit report 📦

Path Size
react full 11.99 KB (-0.02% 🔽)
react minimal 9.02 KB (+0.07% 🔺)

# Conflicts:
#	packages/vue-query/src/queryOptions.ts
@TkDodo TkDodo marked this pull request as ready for review April 20, 2026 06:58
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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/types.ts (1)

113-121: ⚠️ Potential issue | 🟠 Major

Avoid a type-level breaking change by keeping Enabled as a deprecated alias.

Renaming the exported alias to QueryBooleanOption can break consumers importing Enabled from query-core. Please keep a compatibility alias.

🔧 Backward-compatible type alias
 export type QueryBooleanOption<
   TQueryFnData = unknown,
   TError = DefaultError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 > =
   | boolean
   | ((query: Query<TQueryFnData, TError, TData, TQueryKey>) => boolean)
+
+/** `@deprecated` Use `QueryBooleanOption` instead. */
+export type Enabled<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> = QueryBooleanOption<TQueryFnData, TError, TData, TQueryKey>
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@packages/query-core/src/types.ts` around lines 113 - 121, Keep a
backward-compatible deprecated alias by exporting Enabled as an alias of
QueryBooleanOption so existing consumers don't break; locate the type
QueryBooleanOption and add an exported type alias named Enabled that points to
QueryBooleanOption and mark it deprecated in a comment or JSDoc so downstream
code can still import Enabled while signalling it will be removed later.
🧹 Nitpick comments (1)
packages/react-query/src/__tests__/useQuery.test.tsx (1)

6910-6912: Tighten callback assertion to avoid false positives.

This test currently allows extra callback invocations. Since it verifies invocation semantics, asserting exact count makes it stricter.

♻️ Suggested test hardening
-    expect(retryOnMount).toHaveBeenCalled()
+    expect(retryOnMount).toHaveBeenCalledTimes(1)
     const query = retryOnMount.mock.calls.at(-1)![0]
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@packages/react-query/src/__tests__/useQuery.test.tsx` around lines 6910 -
6912, The test currently allows extra invocations of the mock retryOnMount which
can mask incorrect behavior; tighten the assertion by explicitly checking the
exact number of calls (e.g., expect(retryOnMount).toHaveBeenCalledTimes(1))
before inspecting the last call, then continue to grab the single call
(retryOnMount.mock.calls[0] or .at(0)) and assert query.state.status ===
'error'; update the useQuery.test.tsx assertion around the retryOnMount mock to
enforce exact call count and use the specific call index when creating the query
variable.
🤖 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/types.ts`:
- Around line 113-121: Keep a backward-compatible deprecated alias by exporting
Enabled as an alias of QueryBooleanOption so existing consumers don't break;
locate the type QueryBooleanOption and add an exported type alias named Enabled
that points to QueryBooleanOption and mark it deprecated in a comment or JSDoc
so downstream code can still import Enabled while signalling it will be removed
later.

---

Nitpick comments:
In `@packages/react-query/src/__tests__/useQuery.test.tsx`:
- Around line 6910-6912: The test currently allows extra invocations of the mock
retryOnMount which can mask incorrect behavior; tighten the assertion by
explicitly checking the exact number of calls (e.g.,
expect(retryOnMount).toHaveBeenCalledTimes(1)) before inspecting the last call,
then continue to grab the single call (retryOnMount.mock.calls[0] or .at(0)) and
assert query.state.status === 'error'; update the useQuery.test.tsx assertion
around the retryOnMount mock to enforce exact call count and use the specific
call index when creating the query variable.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2a7bf7f7-810e-4787-93e1-3f308f5094c4

📥 Commits

Reviewing files that changed from the base of the PR and between 599e51d and b40fb96.

📒 Files selected for processing (14)
  • .changeset/silver-places-pick.md
  • docs/framework/react/reference/useQuery.md
  • docs/framework/solid/reference/useQuery.md
  • packages/preact-query/src/__tests__/QueryResetErrorBoundary.test.tsx
  • packages/preact-query/src/__tests__/useQuery.test.tsx
  • packages/query-core/src/query.ts
  • packages/query-core/src/queryObserver.ts
  • packages/query-core/src/types.ts
  • packages/query-core/src/utils.ts
  • packages/react-query/src/__tests__/QueryResetErrorBoundary.test.tsx
  • packages/react-query/src/__tests__/useQuery.test.tsx
  • packages/solid-query/src/__tests__/useQuery.test.tsx
  • packages/vue-query/src/queryOptions.ts
  • packages/vue-query/src/useQuery.ts

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant