Skip to content

feat(core): callback for retryOnMount#10515

Merged
TkDodo merged 5 commits intomainfrom
feature/feat/callback-for-retryOnMount
Apr 23, 2026
Merged

feat(core): callback for retryOnMount#10515
TkDodo merged 5 commits intomainfrom
feature/feat/callback-for-retryOnMount

Conversation

@TkDodo
Copy link
Copy Markdown
Collaborator

@TkDodo TkDodo commented Apr 18, 2026

Summary by CodeRabbit

  • New Features

    • retryOnMount now accepts a callback that receives the query and returns a boolean to determine retry-on-mount behavior.
  • Documentation

    • Updated docs across frameworks to show the new callback signature and clarify behavior when query has data or error.
  • Bug Fixes

    • retryOnMount: false now prevents retries only when a query is errored and has no data.
  • Tests

    • Tests updated and new cases added to validate callback semantics for retryOnMount.

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented Apr 18, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3820c4be-3516-4529-844f-b8254f1431ac

📥 Commits

Reviewing files that changed from the base of the PR and between b40fb96 and 53c954d.

📒 Files selected for processing (3)
  • packages/preact-query/src/__tests__/useQuery.test.tsx
  • packages/react-query/src/__tests__/useQuery.test.tsx
  • packages/solid-query/src/__tests__/useQuery.test.tsx
🚧 Files skipped from review as they are similar to previous changes (3)
  • packages/solid-query/src/tests/useQuery.test.tsx
  • packages/preact-query/src/tests/useQuery.test.tsx
  • packages/react-query/src/tests/useQuery.test.tsx

📝 Walkthrough

Walkthrough

Extends retryOnMount to accept a callback (query: Query) => boolean in addition to boolean. Renames resolveEnabledresolveQueryBoolean and EnabledQueryBooleanOption, and applies the resolver across query logic. Tests and docs updated to reflect and validate callback semantics.

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 release; updated retryOnMount doc/type to `boolean
Core Types & Utils
packages/query-core/src/types.ts, packages/query-core/src/utils.ts
Renamed EnabledQueryBooleanOption<...> and resolveEnabledresolveQueryBoolean(...); widened option type to `boolean
Core Implementation
packages/query-core/src/query.ts, packages/query-core/src/queryObserver.ts
Replaced resolveEnabled usages with resolveQueryBoolean for enabled-state, mount/load, and fetch decision logic; shouldLoadOnMount and related checks now resolve retryOnMount via the new helper.
Framework Integrations (Vue)
packages/vue-query/src/queryOptions.ts, packages/vue-query/src/useQuery.ts
Replaced imports/usages of Enabled with QueryBooleanOption for enabled option function overloads to align callable form with core type change.
Tests — React / Preact / Solid
packages/react-query/src/__tests__/useQuery.test.tsx, packages/react-query/src/__tests__/QueryResetErrorBoundary.test.tsx, packages/preact-query/src/__tests__/useQuery.test.tsx, packages/preact-query/src/__tests__/QueryResetErrorBoundary.test.tsx, packages/solid-query/src/__tests__/useQuery.test.tsx
Updated tests to pass retryOnMount as callbacks (() => true/false) instead of booleans; added tests verifying callback invocation and behavior (called when error + no data; not called when data exists).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 I sniffed the query, gave it a wink,
Now retryOnMount can think and not just blink.
I pass the query, it answers true or false,
Hop, hop — smarter retries without a waltz.
twitches nose and celebrates

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name Status Explanation Resolution
Description check ⚠️ Warning The pull request description is completely missing. The required template specifies sections for Changes, Checklist, and Release Impact, none of which are present. Add a comprehensive description following the template, including what changes were made, motivation, testing confirmation, and changesets documentation.
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 (3 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly describes the main feature being added: support for callback functions in the retryOnMount option.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ 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 53c954d

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

☁️ Nx Cloud last updated this comment at 2026-04-23 12:41:36 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: 53c954d

@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

@TkDodo TkDodo merged commit 6540a41 into main Apr 23, 2026
8 checks passed
@TkDodo TkDodo deleted the feature/feat/callback-for-retryOnMount branch April 23, 2026 12:45
@github-actions github-actions Bot mentioned this pull request Apr 23, 2026
Ephem pushed a commit to Ephem/react-query that referenced this pull request Apr 23, 2026
* feat(core): callback for retryOnMount

* ci: apply automated fixes

* fix: vue

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
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