Mutations

Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects. For this purpose, Svelte Query exports a useMutation hook.

Here's an example of a mutation that adds a new todo to the server:

1 <script>
2   import { useMutation } from '@sveltestack/svelte-query'
3 
4   const mutation = useMutation(newTodo => axios.post('/todos', newTodo))
5 </script>
6 
7 <div>
8   {#if $mutation.isLoading}
9     <p>Adding todo...</p>
10   {:else if $mutation.isError}
11     <div>An error occurred: {$mutation.error.message}</div>
12   {:else if $mutation.isSuccess}
13     <div>Todo added!</div>
14   {:else}
15     <button
16       onClick={() => {
17         $mutation.mutate({ id: new Date(), title: 'Do Laundry' })
18       }}>
19       Create Todo
20     </button>
21   {/if}
22 </div>

A mutation can only be in one of the following states at any given moment:

• isIdle or `status === 'idle' - The mutation is currently idle or in a fresh/reset state
• isLoading or status === 'loading' - The mutation is currently running
• isError or status === 'error' - The mutation encountered an error
• isSuccess or status === 'success' - The mutation was successful and mutation data is available

Beyond those primary state, more information is available depending on the state the mutation:

• error - If the mutation is in an isError state, the error is available via the error property.
• data - If the mutation is in a success state, the data is available via the data property.

In the example above, you also saw that you can pass variables to your mutations function by calling the mutate function with a single variable or object.

Even with just variables, mutations aren't all that special, but when used with the onSuccess option, the Query Client's invalidateQueries method and the Query Client's setQueryData method, mutations become a very powerful tool.

IMPORTANT: The mutate function is an asynchronous function, which means you cannot use it directly in an event callback. If you need to access the event in on:submit you need to wrap mutate in another function.

1 <script>
2   // This will not work
3   const mutation = useMutation(event => {
4     event.preventDefault()
5     return fetch('/api', new FormData(event.target))
6   })
7 </script>
8 
9 <form on:submit={$mutation.mutate}>...</form>
10 
11 
12 <script>
13   // This will work
14   const mutation = useMutation(formData => {
15     return fetch('/api', formData)
16   })
17 
18   const onSubmit = event => {
19     event.preventDefault()
20     $mutation.mutate(new FormData(event.target))
21   }
22 </script>
23 
24 <form on:submit={onSubmit}>...</form>

Resetting Mutation State

It's sometimes the case that you need to clear the error or data of a mutation request. To do this, you can use the reset function to handle this:

1 <script>
2   let title = ''
3   const mutation = useMutation(createTodo)
4 
5   const onCreateTodo = e => {
6     e.preventDefault()
7     mutation.mutate({ title })
8   }
9 </script>
10 
11 <form on:submit={onCreateTodo}>
12   {#if $mutation.error}
13     <h5 on:click={() => mutation.reset()}>{$mutation.error}</h5>
14   {/if}
15   <input type="text" bind:value={title} />
16   <br />
17   <button type="submit">Create Todo</button>
18 </form>

Mutation Side Effects

useMutation comes with some helper options that allow quick and easy side-effects at any stage during the mutation lifecycle. These come in handy for both invalidating and refetching queries after mutations and even optimistic updates

1 useMutation(addTodo, {
2   onMutate: variables => {
3     // A mutation is about to happen!
4 
5     // Optionally return a context containing data to use when for example rolling back
6     return { id: 1 }
7   },
8   onError: (error, variables, context) => {
9     // An error happened!
10     console.log(`rolling back optimistic update with id ${context.id}`)
11   },
12   onSuccess: (data, variables, context) => {
13     // Boom baby!
14   },
15   onSettled: (data, error, variables, context) => {
16     // Error or success... doesn't matter!
17   },
18 })

When returning a promise in any of the callback functions it will first be awaited before the next callback is called:

1 useMutation(addTodo, {
2   onSuccess: async () => {
3     console.log("I'm first!")
4   },
5   onSettled: async () => {
6     console.log("I'm second!")
7   },
8 })

You might find that you want to trigger additional callbacks then the ones defined on useMutation when calling mutate. This can be used to trigger component specific side effects. To do that, you can provide any of the same callback options to the mutate function after your mutation variable. Supported overrides include: onSuccess, onError and onSettled.

1 useMutation(addTodo, {
2   onSuccess: (data, variables, context) => {
3     // I will fire first
4   },
5   onError: (error, variables, context) => {
6     // I will fire first
7   },
8   onSettled: (data, error, variables, context) => {
9     // I will fire first
10   },
11 })
12 
13 mutate(todo, {
14   onSuccess: (data, variables, context) => {
15     // I will fire second!
16   },
17   onError: (error, variables, context) => {
18     // I will fire second!
19   },
20   onSettled: (data, error, variables, context) => {
21     // I will fire second!
22   },
23 })

Promises

Use mutateAsync instead of mutate to get a promise which will resolve on success or throw on an error. This can for example be used to compose side effects.

1 <script>
2   const mutation = useMutation(addTodo)
3   const mutate = $mutation.mutateAsync(todo)
4 </script>
5 
6 {#await mutate}
7     <p>waiting for the promise to resolve...</p>
8 {:then value}
9     <p>done {value}</p>
10 {:catch error}
11     <p>Something went wrong: {error.message}</p>
12 {/await}

Retry

By default Svelte Query will not retry a mutation on error, but it is possible with the retry option:

1 const mutation = useMutation(addTodo, {
2   retry: 3,
3 })

If mutations fail because the device is offline, they will be retried in the same order when the device reconnects.

Persist mutations

Mutations can be persisted to storage if needed and resumed at a later point. This can be done with the hydration functions:

1 const queryClient = new QueryClient()
2 
3 // Define the "addTodo" mutation
4 queryClient.setMutationDefaults('addTodo', {
5   mutationFn: addTodo,
6   onMutate: async (variables) => {
7     // Cancel current queries for the todos list
8     await queryClient.cancelQueries('todos')
9 
10     // Create optimistic todo
11     const optimisticTodo = { id: uuid(), title: variables.title }
12 
13     // Add optimistic todo to todos list
14     queryClient.setQueryData('todos', old => [...old, optimisticTodo])
15 
16     // Return context with the optimistic todo
17     return { optimisticTodo }
18   },
19   onSuccess: (result, variables, context) => {
20     // Replace optimistic todo in the todos list with the result
21     queryClient.setQueryData('todos', old => old.map(todo => todo.id === context.optimisticTodo.id ? result : todo))
22   },
23   onError: (error, variables, context) => {
24     // Remove optimistic todo from the todos list
25     queryClient.setQueryData('todos', old => old.filter(todo => todo.id !== context.optimisticTodo.id))
26   },
27   retry: 3,
28 })
29 
30 // Start mutation in some component:
31 const mutation = useMutation('addTodo')
32 mutation.mutate({ title: 'title' })
33 
34 // If the mutation has been paused because the device is for example offline,
35 // Then the paused mutation can be dehydrated when the application quits:
36 const state = dehydrate(queryClient)
37 
38 // The mutation can then be hydrated again when the application is started:
39 hydrate(queryClient, state)
40 
41 // Resume the paused mutations:
42 queryClient.resumePausedMutations()