feat(query-core): make MutateFunction optional undefinable-variables

[unnoq]

Old Behavior:
.mutate, .mutateAsync, ... allowed omitting the variables parameter only when its type was exactly void.

However, in TypeScript, when using union types like unknown | void, the void portion is ignored and treated as unknown, which still requires that variables be provided.

New Behavior:
.mutate, .mutateAsync, ... now allow omitting the variables parameter when its type can be undefined.

This change significantly broadens the optional types, supporting cases such as unknown, any, undefined | ..., void | ..., ...

Another benefit of the new approach is that, for popular schema libraries like Zod and Valibot, it is easier to define an undefinable schema than a void-able one.

[lonelyplanetdev]

bump

[TkDodo]

that’s a good improvement 👍 . I’m missing a test for the use-case where we have a mutation function that doesn’t take anything in, so the variables are void.

Also, I’d prefer if we create the mutation functions not via type assertions, but by whatever a MutationObserver returns. Something like:

const { mutate } = new MutationObserver(new QueryClient(), {
  mutationFn: async (_vars: number | undefined) => {
    return null
  },
})

[unnoq]

I've added the void case as requested. However, I couldn’t create a test using MutationObserver because the mutate function is implemented as a standalone function rather than using MutateFunction. As a result, the changes don’t impact its behavior. Let me know if you have any suggestions on how to approach testing this scenario.

[TkDodo]

oh interesting. question is if it would also work with the mutate function returned from useMutation, as that is what most users will use. The type is defined here:

query/packages/react-query/src/types.ts

Lines 197 to 204 in 3e3fba9

	export type UseMutateFunction<
	TData = unknown,
	TError = DefaultError,
	TVariables = void,
	TContext = unknown,
	> = (
	...args: Parameters<MutateFunction<TData, TError, TVariables, TContext>>
	) => void

would be great to have a test in useMutation.test-d.tsx in the react-query adapter for this then 🙏

[unnoq]

I've already covered this case. Please check my tests.

https://github.com/TanStack/query/pull/8737/files#diff-fd352cb3d35bea507f0ff667365ff9ab3c51a78c493656207dc3a5291a2491b2R67-R133

[TkDodo]

I've already covered this case

yeah that’s okay for the query-core, but it doesn’t actually test what useMutation in react-query does. It’s great that we cover the functionality that we have in useMutation now, but if we refactor that, it won’t be covered by the test in the core.

That’s why each adapter should have its own tests for the types they are doing. But we can do this in a follow-up.

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 01b77b4.

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

---

☁️ Nx Cloud last updated this comment at 2025-03-05 14:47:53 UTC

[TkDodo]

there are type errors now in other adapters