fix: expand callback return types to support Promise<Array<void>> for Promise.all() usage #9241

braden-w · 2025-06-03T15:21:57Z

This PR expands the callback return types from Promise<void> | void to void | Promise<void> | Promise<Array<void>> to address user feedback from #9202.

PR #9202 narrowed callback types from Promise<unknown> | unknown to Promise<void> | void to better reflect the intent that callback return values are ignored. However, this change broke existing user code that was using a common pattern of returning Promise.all() from callbacks.

Problem

The change broke code like this:

const useCreateProduct = () => {
  return useMutation({
    mutationFn: (createProductDto) => api.products.create(createProductDto),
    onSuccess: (data) => 
      Promise.all([
        queryClient.invalidateQueries({ queryKey: ['products'] }),
        queryClient.invalidateQueries({ queryKey: ['categories'] })
      ]),
  });
};

Since Promise.all() returns Promise<Array<void>>, this pattern was no longer type-compatible.

Solution

This PR adds Promise<Array<void>> to the union type, allowing the common Promise.all() pattern while maintaining the intent that individual callback return values are ignored (they're all variations of void).

Updated type signature:

onSuccess?: (...) => void | Promise<void> | Promise<Array<void>>
onError?: (...) => void | Promise<void> | Promise<Array<void>>
onSettled?: (...) => void | Promise<void> | Promise<Array<void>>

Changes Made

✅ Updated callback return types in MutationOptions interface
✅ Updated callback return types in MutationCacheConfig interface
✅ Updated callback return types in persist client packages
✅ Updated documentation to reflect new types
✅ Fixed Promise chain handling in persist clients to support new return types

Addresses

Feedback from @Sagie501 in refactor: narrow onSuccess/onError/onMutate/onSettled callback types to Promise<void> | void #9202
Feedback from @jgarplind in refactor: narrow onSuccess/onError/onMutate/onSettled callback types to Promise<void> | void #9202
Common Promise.all() usage pattern in mutation callbacks

Fixes #9202 (user feedback)

…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`.

…lback-types

… Promise.all() usage

…e<Array<void>> for improved handling in onSuccess and onError

nx-cloud · 2025-06-03T16:03:34Z

View your CI Pipeline Execution ↗ for commit fce255f.

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

☁️ Nx Cloud last updated this comment at 2025-06-03 16:07:13 UTC

pkg-pr-new · 2025-06-03T16:06:32Z

More templates

@tanstack/angular-query-devtools-experimental

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

@tanstack/angular-query-experimental

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

@tanstack/eslint-plugin-query

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

@tanstack/query-async-storage-persister

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

@tanstack/query-broadcast-client-experimental

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

@tanstack/query-core

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

@tanstack/query-devtools

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

@tanstack/query-persist-client-core

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

@tanstack/query-sync-storage-persister

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

@tanstack/react-query

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

@tanstack/react-query-devtools

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

@tanstack/react-query-next-experimental

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

@tanstack/react-query-persist-client

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

@tanstack/solid-query

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

@tanstack/solid-query-devtools

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

@tanstack/solid-query-persist-client

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

@tanstack/svelte-query

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

@tanstack/svelte-query-devtools

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

@tanstack/svelte-query-persist-client

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

@tanstack/vue-query

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

@tanstack/vue-query-devtools

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

commit: fce255f

braden-w · 2025-06-03T17:23:36Z

Actually, scratch this PR: we should instead change the return types to just be void. Consider #9245 instead.

Replace callback return type unions with unions of complete function signatures to improve type safety and clarity. This change addresses the issues raised in TanStack#9241 and TanStack#9245 by: - Preventing mixed sync/async behavior within single callbacks - Maintaining support for Promise.all() patterns

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

Merge remote-tracking branch 'upstream/main' into refactor/narrow-cal…

ca482b1

…lback-types

fix: expand callback return types to support Promise<Array<void>> for…

3a8841e

… Promise.all() usage

github-actions bot added documentation Improvements or additions to documentation package: react-query-persist-client package: query-core labels Jun 3, 2025

braden-w added 2 commits June 3, 2025 08:26

fix: update callback return types in persist client to support Promis…

0d1294b

…e<Array<void>> for improved handling in onSuccess and onError

Merge branch 'main' into refactor/narrow-callback-types

fce255f

This was referenced Jun 3, 2025

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

Merged

refactor: simplify callback return types to void #9245

Closed

braden-w closed this Jun 3, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix: expand callback return types to support Promise<Array<void>> for Promise.all() usage #9241

fix: expand callback return types to support Promise<Array<void>> for Promise.all() usage #9241

Uh oh!

braden-w commented Jun 3, 2025

Uh oh!

nx-cloud bot commented Jun 3, 2025 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Jun 3, 2025

Uh oh!

braden-w commented Jun 3, 2025

Uh oh!

Uh oh!

Uh oh!

fix: expand callback return types to support Promise<Array<void>> for Promise.all() usage #9241

fix: expand callback return types to support Promise<Array<void>> for Promise.all() usage #9241

Uh oh!

Conversation

braden-w commented Jun 3, 2025

Problem

Solution

Changes Made

Addresses

Uh oh!

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

Uh oh!

Uh oh!

pkg-pr-new bot commented Jun 3, 2025

Uh oh!

braden-w commented Jun 3, 2025

Uh oh!

Uh oh!

nx-cloud bot commented Jun 3, 2025 •

edited

Loading