refactor: narrow onSuccess/onError/onMutate/onSettled callback types to Promise<void> | void #9202

braden-w · 2025-05-28T06:31:57Z

Previously, the onSuccess, onError, onMutate, and onSettled callbacks were typed as () => Promise<unknown> | unknown. While unknown is technically valid, it implies that the return value might be used, assigned, or further processed. However, throughout the codebase, these callbacks are invoked solely for their side effects, and their return values are always ignored. Narrowing the type to Promise<void> | void makes this intent explicit, clarifies that any return value will be discarded, and prevents misleading type signatures that suggest otherwise.

This commit narrows their types to () => Promise<void> | void, which more accurately reflects their intended use.

nx-cloud · 2025-05-28T06:32:23Z

View your CI Pipeline Execution ↗ for commit 26a2647.

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

☁️ Nx Cloud last updated this comment at 2025-05-28 07:08:18 UTC

pkg-pr-new · 2025-05-28T06:35:17Z

More templates

@tanstack/angular-query-devtools-experimental

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

@tanstack/angular-query-experimental

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

@tanstack/eslint-plugin-query

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

@tanstack/query-async-storage-persister

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

@tanstack/query-broadcast-client-experimental

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

@tanstack/query-core

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

@tanstack/query-devtools

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

@tanstack/query-persist-client-core

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

@tanstack/query-sync-storage-persister

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

@tanstack/react-query

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

@tanstack/react-query-devtools

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

@tanstack/react-query-next-experimental

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

@tanstack/react-query-persist-client

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

@tanstack/solid-query

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

@tanstack/solid-query-devtools

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

@tanstack/solid-query-persist-client

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

@tanstack/svelte-query

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

@tanstack/svelte-query-devtools

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

@tanstack/svelte-query-persist-client

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

@tanstack/vue-query

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

@tanstack/vue-query-devtools

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

commit: 26a2647

codecov · 2025-05-28T06:41:30Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 59.56%. Comparing base (a1210cb) to head (26a2647).
Report is 6 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #9202       +/-   ##
===========================================
+ Coverage   45.24%   59.56%   +14.32%     
===========================================
  Files         209      138       -71     
  Lines        8247     5485     -2762     
  Branches     1860     1467      -393     
===========================================
- Hits         3731     3267      -464     
+ Misses       4076     1921     -2155     
+ Partials      440      297      -143

Components	Coverage Δ
@tanstack/angular-query-devtools-experimental	`∅ <ø> (∅)`
@tanstack/angular-query-experimental	`85.04% <ø> (ø)`
@tanstack/eslint-plugin-query	`∅ <ø> (∅)`
@tanstack/query-async-storage-persister	`43.85% <ø> (ø)`
@tanstack/query-broadcast-client-experimental	`24.39% <ø> (ø)`
@tanstack/query-codemods	`∅ <ø> (∅)`
@tanstack/query-core	`98.12% <ø> (ø)`
@tanstack/query-devtools	`3.56% <ø> (ø)`
@tanstack/query-persist-client-core	`78.32% <ø> (ø)`
@tanstack/query-sync-storage-persister	`84.61% <ø> (ø)`
@tanstack/query-test-utils	`∅ <ø> (∅)`
@tanstack/react-query	`96.00% <ø> (ø)`
@tanstack/react-query-devtools	`10.00% <ø> (ø)`
@tanstack/react-query-next-experimental	`∅ <ø> (∅)`
@tanstack/react-query-persist-client	`100.00% <ø> (ø)`
@tanstack/solid-query	`78.20% <ø> (ø)`
@tanstack/solid-query-devtools	`∅ <ø> (∅)`
@tanstack/solid-query-persist-client	`100.00% <ø> (ø)`
@tanstack/svelte-query	`88.15% <ø> (ø)`
@tanstack/svelte-query-devtools	`∅ <ø> (∅)`
@tanstack/svelte-query-persist-client	`100.00% <ø> (ø)`
@tanstack/vue-query	`70.85% <ø> (ø)`
@tanstack/vue-query-devtools	`∅ <ø> (∅)`

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

This commit builds on the changes introduced in [refactor/narrow-callback-types](TanStack#9202) and replaces all instances of `Promise<T> | T` with the new `MaybePromise<T>` helper type. The `MaybePromise` type, originally defined in `@tanstack/query-persist-client-core/src/createPersister.ts`, is now moved to `query-core` for broader, consistent use. - Moves the `MaybePromise` type definition to `query-core`, making it the canonical utility for representing values that may be returned synchronously or as a promise. - Updates all relevant callback signatures (such as `onSuccess`, `onError`, `onMutate`, `onSettled`, and other callbacks) to use `MaybePromise<T>` instead of `Promise<T> | T`. - Updates documentation to reference `MaybePromise<T>` for clarity and consistency. This builds on the direction set by [refactor/narrow-callback-types](TanStack#9202), further improving type readability and maintainability by using a single, expressive type for all maybe-async callback returns.

…to Promise<void> | void Previously, the `onSuccess`, `onError`, `onMutate`, and `onSettled` callbacks were typed as `() => Promise<unknown> | unknown`. While `unknown` is technically valid, it implies that the return value might be used, assigned, or further processed. However, throughout the codebase, these callbacks are invoked solely for their side effects, and their return values are always ignored. Narrowing the type to `Promise<void> | void` makes this intent explicit, clarifies that any return value will be discarded, and prevents misleading type signatures that suggest otherwise. This commit narrows their types to `() => Promise<void> | void`, which more accurately reflects their intended use.

…n-related documentation This commit refines the documentation for mutation-related callbacks (`onSuccess`, `onError`, `onSettled`, and `onMutate`), changing their return types from `Promise<unknown> | unknown` to `Promise<void> | void`.

This commit builds on the changes introduced in [refactor/narrow-callback-types](TanStack#9202) and replaces all instances of `Promise<T> | T` with the new `MaybePromise<T>` helper type. The `MaybePromise` type, originally defined in `@tanstack/query-persist-client-core/src/createPersister.ts`, is now moved to `query-core` for broader, consistent use. - Moves the `MaybePromise` type definition to `query-core`, making it the canonical utility for representing values that may be returned synchronously or as a promise. - Updates all relevant callback signatures (such as `onSuccess`, `onError`, `onMutate`, `onSettled`, and other callbacks) to use `MaybePromise<T>` instead of `Promise<T> | T`. - Updates documentation to reference `MaybePromise<T>` for clarity and consistency. This builds on the direction set by [refactor/narrow-callback-types](TanStack#9202), further improving type readability and maintainability by using a single, expressive type for all maybe-async callback returns.

Sagie501 · 2025-06-03T10:08:18Z

@braden-w @TkDodo
I have the following code:

export const useCreateProduct = () => {
  const api = useApi();
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (createProductDto: CreateProductDto) =>
      api.products.productControllerCreateProduct(createProductDto).then((res) => res.data),
    onSuccess: (data) =>
      Promise.all([queryClient.invalidateQueries({ queryKey: /* some query key */ }), queryClient.invalidateQueries({ queryKey: /* some other query key */ })]),
  });
};

And with the following change I am getting the following error:

What would you suggest me to do?

jgarplind · 2025-06-03T12:39:58Z

Same issue as @Sagie501 for us. Not trying to start a flood of +1s, but I think it makes sense to clarify that this is a somewhat commonly used pattern, probably impacting many users.

Sagie501 · 2025-06-03T14:10:26Z

Changing the callbacks type to void | Promise<void> | Promise<Array<void>> will solve my case, does that making sense?

github-actions bot added documentation Improvements or additions to documentation package: react-query-persist-client package: query-core package: svelte-query package: svelte-query-devtools package: svelte-query-persist-client labels May 28, 2025

braden-w force-pushed the refactor/narrow-callback-types branch from bc812c6 to bf7af4e Compare May 28, 2025 06:35

github-actions bot removed documentation Improvements or additions to documentation package: svelte-query package: svelte-query-devtools package: svelte-query-persist-client labels May 28, 2025

github-actions bot added the documentation Improvements or additions to documentation label May 28, 2025

braden-w mentioned this pull request May 28, 2025

refactor: standardize use of MaybePromise<T> in place of Promise<T> | T #9203

Open

braden-w added 2 commits May 28, 2025 00:03

braden-w force-pushed the refactor/narrow-callback-types branch from 52de5b7 to 26a2647 Compare May 28, 2025 07:05

braden-w changed the title ~~refactor: narrow onSuccess/onError/onMutate/onSettled callback types to Promise<void> | void in persist-query-client~~ May 29, 2025

TkDodo approved these changes Jun 2, 2025

View reviewed changes

TkDodo merged commit 982f6ca into TanStack:main Jun 2, 2025
7 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

refactor: narrow onSuccess/onError/onMutate/onSettled callback types to Promise<void> | void #9202

refactor: narrow onSuccess/onError/onMutate/onSettled callback types to Promise<void> | void #9202

braden-w commented May 28, 2025

nx-cloud bot commented May 28, 2025 •

edited

Loading

pkg-pr-new bot commented May 28, 2025 •

edited

Loading

codecov bot commented May 28, 2025 •

edited

Loading

Uh oh!

Sagie501 commented Jun 3, 2025 •

edited

Loading

jgarplind commented Jun 3, 2025 •

edited

Loading

Sagie501 commented Jun 3, 2025

Uh oh!

refactor: narrow onSuccess/onError/onMutate/onSettled callback types to Promise<void> | void #9202

refactor: narrow onSuccess/onError/onMutate/onSettled callback types to Promise<void> | void #9202

Conversation

braden-w commented May 28, 2025

nx-cloud bot commented May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

pkg-pr-new bot commented May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

codecov bot commented May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Sagie501 commented Jun 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

jgarplind commented Jun 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Sagie501 commented Jun 3, 2025

nx-cloud bot commented May 28, 2025 •

edited

Loading

pkg-pr-new bot commented May 28, 2025 •

edited

Loading

codecov bot commented May 28, 2025 •

edited

Loading

Sagie501 commented Jun 3, 2025 •

edited

Loading

jgarplind commented Jun 3, 2025 •

edited

Loading