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

.changeset/optional-mutate-parameters.md

@@ -0,0 +1,12 @@
+---
+'@tanstack/angular-query-experimental': patch
+'@tanstack/lit-query': patch
+'@tanstack/preact-query': patch
+'@tanstack/query-core': patch
+'@tanstack/react-query': patch
+'@tanstack/solid-query': patch
+'@tanstack/svelte-query': patch
+'@tanstack/vue-query': patch
+---
+
+fix: make mutation variables optional when `undefined extends TVariables`

packages/angular-query-experimental/src/inject-mutation.ts

@@ -86,8 +86,12 @@ export function injectMutation<
     CreateMutateFunction<TData, TError, TVariables, TOnMutateResult>
   >(() => {
     const observer = observerSignal()
-    return (variables, mutateOptions) => {
-      observer.mutate(variables, mutateOptions).catch(noop)
+    return (
+      ...args: Parameters<
+        CreateMutateFunction<TData, TError, TVariables, TOnMutateResult>
+      >
+    ) => {
+      observer.mutate(args[0] as TVariables, args[1]).catch(noop)
     }
   })
 

packages/lit-query/src/createMutationController.ts

@@ -1,7 +1,7 @@
 import {
   MutationObserver,
   type DefaultError,
-  type MutateOptions,
+  type MutateFunction,
   type MutationObserverOptions,
   type MutationObserverResult,
 } from '@tanstack/query-core'
@@ -45,8 +45,9 @@ export type MutationResultAccessor<TData, TError, TVariables, TOnMutateResult> =
      * Throws synchronously if no `QueryClient` can be resolved.
      */
     mutate: (
-      variables: TVariables,
-      options?: MutateOptions<TData, TError, TVariables, TOnMutateResult>,
+      ...args: Parameters<
+        MutateFunction<TData, TError, TVariables, TOnMutateResult>
+      >
     ) => void
     /**
      * Starts the mutation and returns the observer promise.
@@ -190,14 +191,15 @@ class MutationController<
   }
 
   mutate = (
-    variables: TVariables,
-    mutateOptions?: MutateOptions<TData, TError, TVariables, TOnMutateResult>,
+    ...args: Parameters<
+      MutateFunction<TData, TError, TVariables, TOnMutateResult>
+    >
   ): void => {
     if (!this.syncClient() || !this.observer) {
       throw createMissingQueryClientError()
     }
 
-    void this.observer.mutate(variables, mutateOptions).catch(() => {
+    void this.observer.mutate(args[0] as TVariables, args[1]).catch(() => {
       // Intentionally swallow in sync mutate path.
     })
   }
@@ -212,7 +214,7 @@ class MutationController<
       return Promise.reject(createMissingQueryClientError())
     }
 
-    return this.observer.mutate(...args)
+    return this.observer.mutate(args[0] as TVariables, args[1])
   }
 
   reset: MutationObserverResult<

packages/preact-query/src/useMutation.ts

@@ -52,8 +52,12 @@ export function useMutation<
   const mutate = useCallback<
     UseMutateFunction<TData, TError, TVariables, TOnMutateResult>
   >(
-    (variables, mutateOptions) => {
-      observer.mutate(variables, mutateOptions).catch(noop)
+    (
+      ...args: Parameters<
+        UseMutateFunction<TData, TError, TVariables, TOnMutateResult>
+      >
+    ) => {
+      observer.mutate(args[0] as TVariables, args[1]).catch(noop)
     },
     [observer],
   )

packages/query-core/src/__tests__/mutations.test-d.tsx

@@ -0,0 +1,229 @@
+import { describe, expectTypeOf, it } from 'vitest'
+
+import type { DefaultError, MutateFunction, MutateOptions } from '../types'
+
+describe('MutateFunction', () => {
+  it('void variables', () => {
+    const mutate = {} as MutateFunction
+
+    expectTypeOf<Parameters<typeof mutate>[0]>().toEqualTypeOf<
+      undefined | void
+    >()
+
+    expectTypeOf<Parameters<typeof mutate>[1]>().toEqualTypeOf<
+      undefined | MutateOptions<unknown, DefaultError, void, unknown>
+    >()
+
+    mutate() // can be called with no arguments
+    mutate(undefined, {
+      onError: (e) => {
+        expectTypeOf(e).toEqualTypeOf<DefaultError>()
+      },
+    })
+  })
+
+  it('optional undefinable variables', () => {
+    const mutate = {} as MutateFunction<
+      unknown,
+      DefaultError,
+      number | undefined,
+      unknown
+    >
+
+    expectTypeOf<Parameters<typeof mutate>[0]>().toEqualTypeOf<
+      number | undefined
+    >()
+
+    expectTypeOf<Parameters<typeof mutate>[1]>().toEqualTypeOf<
+      | undefined
+      | MutateOptions<unknown, DefaultError, number | undefined, unknown>
+    >()
+
+    mutate() // can be called with no arguments
+    mutate(undefined, {
+      onError: (e) => {
+        expectTypeOf(e).toEqualTypeOf<DefaultError>()
+      },
+    })
+  })
+
+  it('unknown variables', () => {
+    const mutate = {} as MutateFunction<unknown, DefaultError, unknown, unknown>
+
+    expectTypeOf<Parameters<typeof mutate>[0]>().toEqualTypeOf<unknown>()
+
+    expectTypeOf<Parameters<typeof mutate>[1]>().toEqualTypeOf<
+      undefined | MutateOptions<unknown, DefaultError, unknown, unknown>
+    >()
+
+    mutate() // can be called with no arguments
+  })
+
+  it('any variables', () => {
+    const mutate = {} as MutateFunction<unknown, DefaultError, any, unknown>
+
+    expectTypeOf<Parameters<typeof mutate>[0]>().toEqualTypeOf<any>()
+
+    expectTypeOf<Parameters<typeof mutate>[1]>().toEqualTypeOf<
+      undefined | MutateOptions<unknown, DefaultError, any, unknown>
+    >()
+
+    mutate() // can be called with no arguments
+  })
+
+  it('void union variables', () => {
+    const mutate = {} as MutateFunction<
+      unknown,
+      DefaultError,
+      void | string,
+      unknown
+    >
+
+    expectTypeOf<Parameters<typeof mutate>[0]>().toEqualTypeOf<
+      void | string | undefined
+    >()
+
+    expectTypeOf<Parameters<typeof mutate>[1]>().toEqualTypeOf<
+      undefined | MutateOptions<unknown, DefaultError, void | string, unknown>
+    >()
+
+    mutate() // can be called with no arguments
+  })
+
+  it('required non-undefinable variables', () => {
+    const mutate = {} as MutateFunction<unknown, DefaultError, number, unknown>
+
+    expectTypeOf<Parameters<typeof mutate>[0]>().toEqualTypeOf<number>()
+
+    expectTypeOf<Parameters<typeof mutate>[1]>().toEqualTypeOf<
+      undefined | MutateOptions<unknown, DefaultError, number, unknown>
+    >()
+
+    // @ts-expect-error --- required variables
+    mutate()
+    mutate(123, {
+      onError: (e) => {
+        expectTypeOf(e).toEqualTypeOf<DefaultError>()
+      },
+    })
+  })
+
+  describe('compatible with spread arguments pattern', () => {
+    // this is common pattern used internal so we need make sure it still works
+
+    it('void variables', () => {
+      const mutate = {} as (...options: Parameters<MutateFunction>) => void
+
+      expectTypeOf<Parameters<typeof mutate>[0]>().toEqualTypeOf<
+        undefined | void
+      >()
+
+      expectTypeOf<Parameters<typeof mutate>[1]>().toEqualTypeOf<
+        undefined | MutateOptions<unknown, DefaultError, void, unknown>
+      >()
+
+      mutate() // can be called with no arguments
+      mutate(undefined, {
+        onError: (e) => {
+          expectTypeOf(e).toEqualTypeOf<DefaultError>()
+        },
+      })
+    })
+
+    it('optional undefinable variables', () => {
+      const mutate = {} as (
+        ...options: Parameters<
+          MutateFunction<unknown, DefaultError, number | undefined, unknown>
+        >
+      ) => void
+
+      expectTypeOf<Parameters<typeof mutate>[0]>().toEqualTypeOf<
+        number | undefined
+      >()
+
+      expectTypeOf<Parameters<typeof mutate>[1]>().toEqualTypeOf<
+        | undefined
+        | MutateOptions<unknown, DefaultError, number | undefined, unknown>
+      >()
+
+      mutate() // can be called with no arguments
+      mutate(undefined, {
+        onError: (e) => {
+          expectTypeOf(e).toEqualTypeOf<DefaultError>()
+        },
+      })
+    })
+
+    it('unknown variables', () => {
+      const mutate = {} as (
+        ...options: Parameters<
+          MutateFunction<unknown, DefaultError, unknown, unknown>
+        >
+      ) => void
+
+      expectTypeOf<Parameters<typeof mutate>[0]>().toEqualTypeOf<unknown>()
+
+      expectTypeOf<Parameters<typeof mutate>[1]>().toEqualTypeOf<
+        undefined | MutateOptions<unknown, DefaultError, unknown, unknown>
+      >()
+
+      mutate() // can be called with no arguments
+    })
+
+    it('any variables', () => {
+      const mutate = {} as (
+        ...options: Parameters<
+          MutateFunction<unknown, DefaultError, any, unknown>
+        >
+      ) => void
+
+      expectTypeOf<Parameters<typeof mutate>[0]>().toEqualTypeOf<any>()
+
+      expectTypeOf<Parameters<typeof mutate>[1]>().toEqualTypeOf<
+        undefined | MutateOptions<unknown, DefaultError, any, unknown>
+      >()
+
+      mutate() // can be called with no arguments
+    })
+
+    it('void union variables', () => {
+      const mutate = {} as (
+        ...options: Parameters<
+          MutateFunction<unknown, DefaultError, void | string, unknown>
+        >
+      ) => void
+
+      expectTypeOf<Parameters<typeof mutate>[0]>().toEqualTypeOf<
+        void | string | undefined
+      >()
+
+      expectTypeOf<Parameters<typeof mutate>[1]>().toEqualTypeOf<
+        undefined | MutateOptions<unknown, DefaultError, void | string, unknown>
+      >()
+
+      mutate() // can be called with no arguments
+    })
+
+    it('required non-undefinable variables', () => {
+      const mutate = {} as (
+        ...options: Parameters<
+          MutateFunction<unknown, DefaultError, number, unknown>
+        >
+      ) => void
+
+      expectTypeOf<Parameters<typeof mutate>[0]>().toEqualTypeOf<number>()
+
+      expectTypeOf<Parameters<typeof mutate>[1]>().toEqualTypeOf<
+        undefined | MutateOptions<unknown, DefaultError, number, unknown>
+      >()
+
+      // @ts-expect-error --- required variables
+      mutate()
+      mutate(123, {
+        onError: (e) => {
+          expectTypeOf(e).toEqualTypeOf<DefaultError>()
+        },
+      })
+    })
+  })
+})

packages/query-core/src/types.ts

@@ -1176,14 +1176,28 @@ export interface MutateOptions<
   ) => void
 }
 
+export type MutateFunctionRest<
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TOnMutateResult = unknown,
+> = undefined extends TVariables
+  ? [
+      variables?: TVariables,
+      options?: MutateOptions<TData, TError, TVariables, TOnMutateResult>,
+    ]
+  : [
+      variables: TVariables,
+      options?: MutateOptions<TData, TError, TVariables, TOnMutateResult>,
+    ]
+
 export type MutateFunction<
   TData = unknown,
   TError = DefaultError,
   TVariables = void,
   TOnMutateResult = unknown,
 > = (
-  variables: TVariables,
-  options?: MutateOptions<TData, TError, TVariables, TOnMutateResult>,
+  ...rest: MutateFunctionRest<TData, TError, TVariables, TOnMutateResult>
 ) => Promise<TData>
 
 export interface MutationObserverBaseResult<

packages/react-query/src/useMutation.ts

@@ -52,8 +52,12 @@ export function useMutation<
   const mutate = React.useCallback<
     UseMutateFunction<TData, TError, TVariables, TOnMutateResult>
   >(
-    (variables, mutateOptions) => {
-      observer.mutate(variables, mutateOptions).catch(noop)
+    (
+      ...args: Parameters<
+        UseMutateFunction<TData, TError, TVariables, TOnMutateResult>
+      >
+    ) => {
+      observer.mutate(args[0] as TVariables, args[1]).catch(noop)
     },
     [observer],
   )

packages/solid-query/src/useMutation.ts

@@ -36,8 +36,8 @@ export function useMutation<
     TError,
     TVariables,
     TOnMutateResult
-  > = (variables, mutateOptions) => {
-    observer.mutate(variables, mutateOptions).catch(noop)
+  > = (...args) => {
+    observer.mutate(args[0] as TVariables, args[1]).catch(noop)
   }
 
   const [state, setState] = createStore<

packages/svelte-query/src/createMutation.svelte.ts

@@ -46,12 +46,11 @@ export function createMutation<
     observer.setOptions(options())
   })
 
-  const mutate = <CreateMutateFunction<TData, TError, TVariables, TContext>>((
-    variables,
-    mutateOptions,
+  const mutate: CreateMutateFunction<TData, TError, TVariables, TContext> = (
+    ...args
   ) => {
-    observer.mutate(variables, mutateOptions).catch(noop)
-  })
+    observer.mutate(args[0] as TVariables, args[1]).catch(noop)
+  }
 
   let result = $state(observer.getCurrentResult())
   watchChanges(