feat(svelte-query): add 'mutationOptions' (#10175)

* feat(svelte-query/mutationOptions): add 'mutationOptions' identity function for type-safe mutation configuration

* test(svelte-query/mutationOptions): add type and runtime tests for 'mutationOptions'

* docs(svelte-query/mutationOptions): add reference documentation for 'mutationOptions'

* chore(svelte-query): add changeset for 'mutationOptions'

* ci: apply automated fixes

* test(svelte-query/mutationOptions): use 'Accessor' type for props in BaseExample and wrap test values with arrow functions

* style(svelte-query/mutationOptions): remove blank lines between 'fireEvent' and assertion blocks

* refactor(svelte-query/mutationOptions): split BaseExample into BaseExample and MultiExample for single and multi mutation tests

* ci: apply automated fixes

---------

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

Author: sukvvon

.changeset/smart-spiders-sing.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/svelte-query': minor
+---
+
+feat(svelte-query): add 'mutationOptions'

docs/config.json

@@ -1144,6 +1144,10 @@
             {
               "label": "Functions / infiniteQueryOptions",
               "to": "framework/svelte/reference/functions/infiniteQueryOptions"
+            },
+            {
+              "label": "Functions / mutationOptions",
+              "to": "framework/svelte/reference/functions/mutationOptions"
             }
           ]
         },

docs/framework/svelte/reference/functions/mutationOptions.md

@@ -0,0 +1,78 @@
+---
+id: mutationOptions
+title: mutationOptions
+---
+
+# Function: mutationOptions()
+
+## Call Signature
+
+```ts
+function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options): WithRequired<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>, 'mutationKey'>
+```
+
+Defined in: [packages/svelte-query/src/mutationOptions.ts](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/mutationOptions.ts)
+
+### Type Parameters
+
+#### TData
+
+`TData` = `unknown`
+
+#### TError
+
+`TError` = `Error`
+
+#### TVariables
+
+`TVariables` = `void`
+
+#### TOnMutateResult
+
+`TOnMutateResult` = `unknown`
+
+### Parameters
+
+#### options
+
+`WithRequired`\<[`CreateMutationOptions`](../type-aliases/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `'mutationKey'`\>
+
+### Returns
+
+`WithRequired`\<[`CreateMutationOptions`](../type-aliases/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `'mutationKey'`\>
+
+## Call Signature
+
+```ts
+function mutationOptions<TData, TError, TVariables, TOnMutateResult>(options): Omit<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>, 'mutationKey'>
+```
+
+Defined in: [packages/svelte-query/src/mutationOptions.ts](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/mutationOptions.ts)
+
+### Type Parameters
+
+#### TData
+
+`TData` = `unknown`
+
+#### TError
+
+`TError` = `Error`
+
+#### TVariables
+
+`TVariables` = `void`
+
+#### TOnMutateResult
+
+`TOnMutateResult` = `unknown`
+
+### Parameters
+
+#### options
+
+`Omit`\<[`CreateMutationOptions`](../type-aliases/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `'mutationKey'`\>
+
+### Returns
+
+`Omit`\<[`CreateMutationOptions`](../type-aliases/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `'mutationKey'`\>

packages/svelte-query/src/index.ts

@@ -17,6 +17,7 @@ export { queryOptions } from './queryOptions.js'
 export { createQueries } from './createQueries.svelte.js'
 export { createInfiniteQuery } from './createInfiniteQuery.js'
 export { infiniteQueryOptions } from './infiniteQueryOptions.js'
+export { mutationOptions } from './mutationOptions.js'
 export { createMutation } from './createMutation.svelte.js'
 export { useMutationState } from './useMutationState.svelte.js'
 export { useQueryClient } from './useQueryClient.js'

packages/svelte-query/src/mutationOptions.ts

@@ -0,0 +1,41 @@
+import type { DefaultError, WithRequired } from '@tanstack/query-core'
+import type { CreateMutationOptions } from './types.js'
+
+export function mutationOptions<
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TOnMutateResult = unknown,
+>(
+  options: WithRequired<
+    CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>,
+    'mutationKey'
+  >,
+): WithRequired<
+  CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>,
+  'mutationKey'
+>
+export function mutationOptions<
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TOnMutateResult = unknown,
+>(
+  options: Omit<
+    CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>,
+    'mutationKey'
+  >,
+): Omit<
+  CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>,
+  'mutationKey'
+>
+export function mutationOptions<
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TOnMutateResult = unknown,
+>(
+  options: CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>,
+): CreateMutationOptions<TData, TError, TVariables, TOnMutateResult> {
+  return options
+}

packages/svelte-query/tests/mutationOptions/BaseExample.svelte

@@ -0,0 +1,57 @@
+<script lang="ts">
+  import { QueryClient } from '@tanstack/query-core'
+  import {
+    createMutation,
+    setQueryClientContext,
+    useIsMutating,
+    useMutationState,
+  } from '../../src/index.js'
+  import type {
+    Accessor,
+    CreateMutationOptions,
+    MutationStateOptions,
+  } from '../../src/index.js'
+  import type { MutationFilters } from '@tanstack/query-core'
+
+  let {
+    mutationOpts,
+    isMutatingFilters,
+    mutationStateOpts,
+  }: {
+    mutationOpts: Accessor<CreateMutationOptions<string, Error, void, unknown>>
+    isMutatingFilters?: MutationFilters
+    mutationStateOpts?: MutationStateOptions
+  } = $props()
+
+  const queryClient = new QueryClient()
+  setQueryClientContext(queryClient)
+
+  const mutation = createMutation(mutationOpts)
+  const isMutating = useIsMutating(isMutatingFilters)
+  const mutationState = useMutationState(mutationStateOpts)
+
+  let clientIsMutating = $state(0)
+
+  $effect(() => {
+    const mutationCache = queryClient.getMutationCache()
+    clientIsMutating = isMutatingFilters
+      ? queryClient.isMutating(isMutatingFilters)
+      : queryClient.isMutating()
+
+    const unsubscribe = mutationCache.subscribe(() => {
+      clientIsMutating = isMutatingFilters
+        ? queryClient.isMutating(isMutatingFilters)
+        : queryClient.isMutating()
+    })
+
+    return unsubscribe
+  })
+</script>
+
+<button onclick={() => mutation.mutate()}>mutate</button>
+
+<div>isMutating: {isMutating.current}</div>
+<div>clientIsMutating: {clientIsMutating}</div>
+<div>
+  mutationState: {JSON.stringify(mutationState.map((state) => state.data))}
+</div>

packages/svelte-query/tests/mutationOptions/MultiExample.svelte

@@ -0,0 +1,61 @@
+<script lang="ts">
+  import { QueryClient } from '@tanstack/query-core'
+  import {
+    createMutation,
+    setQueryClientContext,
+    useIsMutating,
+    useMutationState,
+  } from '../../src/index.js'
+  import type {
+    Accessor,
+    CreateMutationOptions,
+    MutationStateOptions,
+  } from '../../src/index.js'
+  import type { MutationFilters } from '@tanstack/query-core'
+
+  let {
+    mutationOpts1,
+    mutationOpts2,
+    isMutatingFilters,
+    mutationStateOpts,
+  }: {
+    mutationOpts1: Accessor<CreateMutationOptions<string, Error, void, unknown>>
+    mutationOpts2: Accessor<CreateMutationOptions<string, Error, void, unknown>>
+    isMutatingFilters?: MutationFilters
+    mutationStateOpts?: MutationStateOptions
+  } = $props()
+
+  const queryClient = new QueryClient()
+  setQueryClientContext(queryClient)
+
+  const mutation1 = createMutation(mutationOpts1)
+  const mutation2 = createMutation(mutationOpts2)
+  const isMutating = useIsMutating(isMutatingFilters)
+  const mutationState = useMutationState(mutationStateOpts)
+
+  let clientIsMutating = $state(0)
+
+  $effect(() => {
+    const mutationCache = queryClient.getMutationCache()
+    clientIsMutating = isMutatingFilters
+      ? queryClient.isMutating(isMutatingFilters)
+      : queryClient.isMutating()
+
+    const unsubscribe = mutationCache.subscribe(() => {
+      clientIsMutating = isMutatingFilters
+        ? queryClient.isMutating(isMutatingFilters)
+        : queryClient.isMutating()
+    })
+
+    return unsubscribe
+  })
+</script>
+
+<button onclick={() => mutation1.mutate()}>mutate1</button>
+<button onclick={() => mutation2.mutate()}>mutate2</button>
+
+<div>isMutating: {isMutating.current}</div>
+<div>clientIsMutating: {clientIsMutating}</div>
+<div>
+  mutationState: {JSON.stringify(mutationState.map((state) => state.data))}
+</div>