Creating Mutations

Learn how to mutate cached queries in React.

source

Usage

createMutation allows you define a way to trigger a query-like function in response to an action that can perform mutations to the data.

For the most part, if you have a signal-based query, there is no need for a mutation unless you are performing unique actions like form submissions.

Additionally, mutations allow you to define a list of querys to invalidate after the mutation has been called.

Creating Mutations

Mutations take a Promise to call when run and an optional options Object.

Using Mutations

createMutation only defines a mutation and does not actually call it. To use the mutation you must pass the returned value into the useMutation hook.

The value returned is an Obect containing the mutate method and the state of the mutation defined.

API

createMutation accepts the following options:

Params	Required	Description
mutator	`true`	The Promise-based function to call when the `mutate` is called.
options

Mutation Options

The options Objecct contains the following optional properties:

Property	Type	Description
`invalidate`	`'all' \| ((data: T, variables: V) => unknown[])`	A list of `query.key` to invalidate once the mutation has completed.
`onSuccess`

Return

createMutation returns a MutationTuple to be passed into useMutation:

Index	Type	Description
0	`(variables: V) => Promise<T>`	A function used to trigger the mutation.
1

false

(data: T, variables: V) => void

Accessor<MutationState<T>>

'use client'

import { Box, Stack } from '@/styled-system/jsx'
import { Button } from '@cerberus/react'
import { createMutation, createQuery, useMutation, useQuery } from '@cerberus/signals'
import { Suspense } from 'react'

// Fake DB

type User = {
  id: string
  name: string
}

let dbUser: User = { id: '', name: '' }

// Data fetching

const query = createQuery(
  () => 'init',
  async () => dbUser,
)

const mutation = createMutation(
  async (newId: User['id']) => {
    dbUser = { id: newId, name: `User ${newId}` }
    return dbUser
  },
  {
    invalidate: () => [query.key],
  },
)

// UI

function UserInfo() {
  const data = useQuery(query)
  return <pre>{JSON.stringify(data, null, 2)}</pre>
}

export function MutationDemo() {
  const { mutate } = useMutation(mutation)

  return (
    <Stack direction="column" justify="space-between" w="3/4">
      <Suspense fallback={<Box aria-busy h="200px" w="full" />}>
        <UserInfo />
      </Suspense>

      <Button onClick={() => mutate(crypto.randomUUID())}>Change User</Button>
    </Stack>
  )
}

{
  "id": "",
  "name": ""
}