Creating Mutations

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

Usage

createMutation allows you create a Mutation Factory that works alongside Cerberus Queries. Mutations provide optimistic updates and invalidation options to keep your UI seamlessly "real-time" by fetching in the background on your behalf.

Mutations are used when you want to make updates to data that is associated with a query.

Likewise, if you have a query that will never have update-related actions associated with it - you don't need mutations.

Creating Mutations

Creating a mutation requires two things:

1. A Promise to call when activated
2. Mutation options to utilize when mutate is called

Ultimately, when you create a mutation you are really just creating a factory that can be called where ever and whenever you are ready.

Using Mutations

Depending on your goals will determine how to you the mutation. The following sections outline the different use cases whether you are optimistically updating or not.

Mutations can live at any level. All that matters is that the factory has access to the query.key to reference.

There are no restrictions to Cerberus Signal Primitives which means you can use them at any scope.

Pattern 1: Optimistic Updates

Optimistic updates allow you to update the state of your query data which which will render in the UI immediately while calling the Promise-based mutation in the background.

This is done by using the setQueryData helper function.

Utilizing this helper will allow your application to appearingly have "real-time" functionality.

Once the mutation is settled, the return value will automagically overwrite the optimistic value. If these are the same - there will be no visual difference in the UI. If there is a descrepency, the UI will automagically be corrected.

To use optimitic updates, add the onMutate method to the options Object of your second argument and call the setQueryData helper to update the state.

const updateUser = createMutation((payload: User) => api.updateUser(payload), {
// Optimistically update the UI instantly
onMutate: (vars) => {
  setQueryData<User>(getUser.key(vars.id), (prev) => {
    if (!prev) return { id: vars.id, name: vars.name }
    return { ...prev, name: vars.name }
  })
},
})

The setQueryData helper accepts a query.key with the same arguments that the original query expects. This is done by using the key property from the original query.

Pattern 2: Non-optimistically

If you are interested in a legacy approach that matches traditional application updates via visual loading states - simply omit the onMutate option (and thus not using setQueryData).

onMutate does not create the optimistic update - setQueryData does. So, if you needed the onMutate lifecycle method you can still use it.

Within Components

To use mutations within a component, pass the factory to the useMutation hook. This will return an Object that contains the mutate method and any of the other return properties.

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

The Mutation Lifecycle

When you trigger a mutation that includes onMutate and invalidate handlers, Cerberus orchestrates a complex, highly-optimized sequence of events under the hood.

Understanding this lifecycle is key to mastering Optimistic UI. Here is the exact chronology of what happens the millisecond you call mutate():

1. The Trigger

The user clicks a button and your component calls mutate(payload).

2. The Optimistic Update (onMutate)

Before the network request even begins, Cerberus synchronously executes your onMutate callback.

• You use setQueryData to inject the expected result directly into the cache.
• The Engine Lock: Cerberus instantly increments an internal version integer on that specific cache node.
• The UI Update: The UI instantly snaps to the new state. Because this uses direct signal memory pointers, it executes in ~130 nanoseconds with zero main-thread blocking.

3. The Network Request

The asynchronous mutation function you defined in the factory (e.g., api.updateUser) is fired to the server. Your component can track this loading state using the isolated pending status.

4. Background SWR (invalidate)

Once the server responds successfully, your invalidate callback fires.

• It flags the target query cache as "stale."
• Because the UI already has data (your optimistic update), Cerberus intentionally bypasses React Suspense boundaries.
• A background Stale-While-Revalidate (SWR) fetch is quietly triggered to verify the data against the database. The user experiences absolutely zero UI flickering.

5. Resolution & The Version Lock

When the background SWR fetch finally resolves, the engine performs one final, critical check before saving the data: The Version Lock.

• It compares the cache's current version to the version it was when the fetch started.
• If they match: The background data perfectly overwrites the cache, confirming the database is in sync with the UI.
• If they differ: This means the user rapidly clicked mutate() again while the background fetch was running. Cerberus realizes this fetch is now stale, intercepts the data, and silently aborts the update. This guarantees your users will never experience a "Flash of Unstyled Content" (FOUC) or see their UI snap backward during rapid interactions.

Timeline Visualization

API

createMutation accepts the following options:

Mutation Options

The options Objecct contains the following optional properties:

Return

useMutation returns a MutationReturn Object that contains the following properties:

setQueryData

setQueryData doesn't return anything and accepts following properties: