On this page

Creating Mutations

Learn how to mutate cached queries in React.

source

import { createMutation, useMutation } from '@cerberus/signals'

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.

const { mutate, ...state } = useMutation(myMutation)

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	`false`	An Object of conditional options for defined mutations.

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`	`(data: T, variables: V) => void`	A callback to run when the mutation is successful.
`onError`	`(error: unknown, variables: V) => void`	A callback to run when the mutation has errored.

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	`Accessor<MutationState<T>>`	The state of the mutation.

On this page

Edit this page on Github

On this page

'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": ""
}