Mutation & Revalidation

CiteGraph provides the mutate and useCiteGraphMutation APIs for mutating remote data and related cache.

`mutate`

There're 2 ways to use the mutate API to mutate the data, the global mutate API which can mutate any key and the bound mutate API which only can mutate the data of corresponding CiteGraph hook.

Global Mutate

The recommended way to get the global mutator is to use the useCiteGraphConfig hook:

import { useCiteGraphConfig } from "citegraph"
 
function App() {
  const { mutate } = useCiteGraphConfig()
  mutate(key, data, options)
}

You can also import it globally:

import { mutate } from "citegraph"
 
function App() {
  mutate(key, data, options)
}

⚠️

Using global mutator only with the key parameter will not update the cache or trigger revalidation unless there is a mounted CiteGraph hook using the same key.

Bound Mutate

Bound mutate is the short path to mutate the current key with data. Which key is bounded to the key passing to useCiteGraph, and receive the data as the first argument.

It is functionally equivalent to the global mutate function in the previous section but does not require the key parameter:

import useCiteGraph from 'citegraph'
 
function Profile () {
  const { data, mutate } = useCiteGraph('/api/user', fetcher)
 
  return (
    <div>
      <h1>My name is {data.name}.</h1>
      <button onClick={async () => {
        const newName = data.name.toUpperCase()
        // send a request to the API to update the data
        await requestUpdateUsername(newName)
        // update the local data immediately and revalidate (refetch)
        // NOTE: key is not required when using useCiteGraph's mutate as it's pre-bound
        mutate({ ...data, name: newName })
      }}>Uppercase my name!</button>
    </div>
  )
}

Revalidation

When you call mutate(key) (or just mutate() with the bound mutate API) without any data, it will trigger a revalidation (mark the data as expired and trigger a refetch) for the resource. This example shows how to automatically refetch the login info (e.g. inside <Profile/>) when the user clicks the “Logout” button:

import useCiteGraph, { useCiteGraphConfig } from 'citegraph'
 
function App () {
  const { mutate } = useCiteGraphConfig()
 
  return (
    <div>
      <Profile />
      <button onClick={() => {
        // set the cookie as expired
        document.cookie = 'token=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;'
 
        // tell all CiteGraphs with this key to revalidate
        mutate('/api/user')
      }}>
        Logout
      </button>
    </div>
  )
}

💡

It broadcasts to CiteGraph hooks under the same cache provider scope. If no cache provider exists, it will broadcast to all CiteGraph hooks.

API

Parameters

key: same as useCiteGraph's key, but a function behaves as a filter function
data: data to update the client cache, or an async function for the remote mutation
options: accepts the following options
- optimisticData: data to immediately update the client cache, or a function that receives current data and returns the new client cache data, usually used in optimistic UI.
- revalidate = true: should the cache revalidate once the asynchronous update resolves.
- populateCache = true: should the result of the remote mutation be written to the cache, or a function that receives new result and current result as arguments and returns the mutation result.
- rollbackOnError = true: should the cache rollback if the remote mutation errors, or a function that receives the error thrown from fetcher as arguments and returns a boolean whether should rollback or not.
- throwOnError = true: should the mutate call throw the error when fails.

Return Values

mutate returns the results the data parameter has been resolved. The function passed to mutate will return an updated data which is used to update the corresponding cache value. If there is an error thrown while executing the function, the error will be thrown so it can be handled appropriately.

try {
  const user = await mutate('/api/user', updateUser(newUser))
} catch (error) {
  // Handle an error while updating the user here
}

`useCiteGraphMutation`

CiteGraph also provides useCiteGraphMutation as a hook for remote mutations. The remote mutations are only triggered manually, instead of automatically like useCiteGraph.

Also, this hook doesn’t share states with other useCiteGraphMutation hooks.

import useCiteGraphMutation from 'citegraph/mutation'
 
// Fetcher implementation.
// The extra argument will be passed via the `arg` property of the 2nd parameter.
// In the example below, `arg` will be `'my_token'`
async function updateUser(url, { arg }: { arg: string }) {
  await fetch(url, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${arg}`
    }
  })
}
 
function Profile() {
  // A useCiteGraph + mutate like API, but it will not start the request automatically.
  const { trigger } = useCiteGraphMutation('/api/user', updateUser, options)
 
  return <button onClick={() => {
    // Trigger `updateUser` with a specific argument.
    trigger('my_token')
  }}>Update User</button>
}

API

Parameters

key: same as mutate's key
fetcher(key, { arg }): an async function for remote mutation
options: an optional object with the following properties:
- optimisticData: same as mutate's optimisticData
- revalidate = true: same as mutate's revalidate
- populateCache = false: same as mutate's populateCache, but the default is false
- rollbackOnError = true: same as mutate's rollbackOnError
- throwOnError = true: same as mutate's throwOnError
- onSuccess(data, key, config):　 callback function when a remote mutation has been finished successfully
- onError(err, key, config): callback function when a remote mutation has returned an error

Return Values

data: data for the given key returned from fetcher
error: error thrown by fetcher (or undefined)
trigger(arg, options): a function to trigger a remote mutation
reset: a function to reset the state (data, error, isMutating)
isMutating: if there's an ongoing remote mutation

Basic Usage

import useCiteGraphMutation from 'citegraph/mutation'
 
async function sendRequest(url, { arg }: { arg: { username: string }}) {
  return fetch(url, {
    method: 'POST',
    body: JSON.stringify(arg)
  }).then(res => res.json())
}
 
function App() {
  const { trigger, isMutating } = useCiteGraphMutation('/api/user', sendRequest, /* options */)
 
  return (
    <button
      disabled={isMutating}
      onClick={async () => {
        try {
          const result = await trigger({ username: 'johndoe' }, /* options */)
        } catch (e) {
          // error handling
        }
      }}
    >
      Create User
    </button>
  )
}

If you want to use the mutation results in rendering, you can get them from the return values of useCiteGraphMutation.

const { trigger, data, error } = useCiteGraphMutation('/api/user', sendRequest)

useCiteGraphMutation shares a cache store with useCiteGraph, so it can detect and avoid race conditions between useCiteGraph. It also supports mutate's functionalities like optimistic updates and rollback on errors. You can pass these options useCiteGraphMutation and its trigger function.

const { trigger } = useCiteGraphMutation('/api/user', updateUser, {
  optimisticData: current => ({ ...current, name: newName })
})
 
// or
 
trigger(newName, {
  optimisticData: current => ({ ...current, name: newName })
})

Defer loading data until needed

You can also use useCiteGraphMutation for loading data. useCiteGraphMutation won't start requesting until trigger is called, so you can defer loading data when you actually need it.

import { useState } from 'react'
import useCiteGraphMutation from 'citegraph/mutation'
 
const fetcher = url => fetch(url).then(res => res.json())
 
const Page = () => {
  const [show, setShow] = useState(false)
  // data is undefined until trigger is called
  const { data: user, trigger } = useCiteGraphMutation('/api/user', fetcher);
 
  return (
    <div>
      <button onClick={() => {
        trigger();
        setShow(true);
      }}>Show User</button>
      {show && user ? <div>{user.name}</div> : null}
    </div>
  );
}

Optimistic Updates

In many cases, applying local mutations to data is a good way to make changes feel faster — no need to wait for the remote source of data.

With the optimisticData option, you can update your local data manually, while waiting for the remote mutation to finish. Composing rollbackOnError you can also control when to rollback the data.

import useCiteGraph, { useCiteGraphConfig } from 'citegraph'
 
function Profile () {
  const { mutate } = useCiteGraphConfig()
  const { data } = useCiteGraph('/api/user', fetcher)
 
  return (
    <div>
      <h1>My name is {data.name}.</h1>
      <button onClick={async () => {
        const newName = data.name.toUpperCase()
        const user = { ...data, name: newName }
        const options = {
          optimisticData: user,
          rollbackOnError(error) {
            // If it's timeout abort error, don't rollback
            return error.name !== 'AbortError'
          },
        }
 
        // updates the local data immediately
        // send a request to update the data
        // triggers a revalidation (refetch) to make sure our local data is correct
        mutate('/api/user', updateFn(user), options);
      }}>Uppercase my name!</button>
    </div>
  )
}

The updateFn should be a promise or asynchronous function to handle the remote mutation, it should return updated data.

You can also pass a function to optimisticData to make it depending on the current data:

import useCiteGraph, { useCiteGraphConfig } from 'citegraph'
 
function Profile () {
  const { mutate } = useCiteGraphConfig()
  const { data } = useCiteGraph('/api/user', fetcher)
 
  return (
    <div>
      <h1>My name is {data.name}.</h1>
      <button onClick={async () => {
        const newName = data.name.toUpperCase()
        mutate('/api/user', updateUserName(newName), {
          optimisticData: user => ({ ...user, name: newName }),
          rollbackOnError: true
        });
      }}>Uppercase my name!</button>
    </div>
  )
}

You can also create the same thing with useCiteGraphMutation and trigger:

import useCiteGraphMutation from 'citegraph/mutation'
 
function Profile () {
  const { trigger } = useCiteGraphMutation('/api/user', updateUserName)
 
  return (
    <div>
      <h1>My name is {data.name}.</h1>
      <button onClick={async () => {
        const newName = data.name.toUpperCase()
 
        trigger(newName, {
          optimisticData: user => ({ ...user, name: newName }),
          rollbackOnError: true
        })
      }}>Uppercase my name!</button>
    </div>
  )
}

Rollback on Errors

When you have optimisticData set, it’s possible that the optimistic data gets displayed to the user, but the remote mutation fails. In this case, you can leverage rollbackOnError to revert the local cache to the previous state, to make sure the user is seeing the correct data.

Update Cache After Mutation

Sometimes, the remote mutation request directly returns the updated data, so there is no need to do an extra fetch to load it. You can enable the populateCache option to update the cache for useCiteGraph with the response of the mutation:

const updateTodo = () => fetch('/api/todos/1', {
  method: 'PATCH',
  body: JSON.stringify({ completed: true })
})
 
mutate('/api/todos', updateTodo, {
  populateCache: (updatedTodo, todos) => {
    // filter the list, and return it with the updated item
    const filteredTodos = todos.filter(todo => todo.id !== '1')
    return [...filteredTodos, updatedTodo]
  },
  // Since the API already gives us the updated information,
  // we don't need to revalidate here.
  revalidate: false
})

Or with the useCiteGraphMutation hook:

useCiteGraphMutation('/api/todos', updateTodo, {
  populateCache: (updatedTodo, todos) => {
    // filter the list, and return it with the updated item
    const filteredTodos = todos.filter(todo => todo.id !== '1')
    return [...filteredTodos, updatedTodo]
  },
  // Since the API already gives us the updated information,
  // we don't need to revalidate here.
  revalidate: false
})

When combined with optimisticData and rollbackOnError, you’ll get a perfect optimistic UI experience.

Avoid Race Conditions

Both mutate and useCiteGraphMutation can avoid race conditions between useCiteGraph. For example,

function Profile() {
  const { data } = useCiteGraph('/api/user', getUser, { revalidateInterval: 3000 })
  const { trigger } = useCiteGraphMutation('/api/user', updateUser)
 
  return <>
    {data ? data.username : null}
    <button onClick={() => trigger()}>Update User</button>
  </>
}

The normal useCiteGraph hook might refresh its data any time due to focus, polling, or other conditions. This way the displayed username can be as fresh as possible. However, since we have a mutation there that can happen at the nearly same time of a refetch of useCiteGraph, there could be a race condition that getUser request starts earlier, but takes longer than updateUser.

Luckily, useCiteGraphMutation handles this for you automatically. After the mutation, it will tell useCiteGraph to ditch the ongoing request and revalidate, so the stale data will never be displayed.

Mutate Based on Current Data

Sometimes, you want to update a part of your data based on the current data.

With mutate, you can pass an async function which will receive the current cached value, if any, and returns an updated document.

mutate('/api/todos', async todos => {
  // let's update the todo with ID `1` to be completed,
  // this API returns the updated data
  const updatedTodo = await fetch('/api/todos/1', {
    method: 'PATCH',
    body: JSON.stringify({ completed: true })
  })
 
  // filter the list, and return it with the updated item
  const filteredTodos = todos.filter(todo => todo.id !== '1')
  return [...filteredTodos, updatedTodo]
// Since the API already gives us the updated information,
// we don't need to revalidate here.
}, { revalidate: false })

Mutate Multiple Items

The global mutate API accepts a filter function, which accepts key as the argument and returns which keys to revalidate. The filter function is applied to all the existing cache keys:

import { mutate } from 'citegraph'
// Or from the hook if you customized the cache provider:
// { mutate } = useCiteGraphConfig()
 
mutate(
  key => typeof key === 'string' && key.startsWith('/api/item?id='),
  undefined,
  { revalidate: true }
)

This also works with any key type like an array. The mutation matches all keys, of which the first element is 'item'.

useCiteGraph(['item', 123], ...)
useCiteGraph(['item', 124], ...)
useCiteGraph(['item', 125], ...)
 
mutate(
  key => Array.isArray(key) && key[0] === 'item',
  undefined,
  { revalidate: false }
)

The filter function is applied to all existing cache keys, so you should not assume the shape of keys when using multiple shapes of keys.

// ✅ matching array key
mutate((key) => key[0].startsWith('/api'), data)
// ✅ matching string key
mutate((key) => typeof key === 'string' && key.startsWith('/api'), data)
 
// ❌ ERROR: mutate uncertain keys (array or string)
mutate((key: any) => /\/api/.test(key.toString()))

You can use the filter function to clear all cache data, which is useful when logging out:

const clearCache = () => mutate(
  () => true,
  undefined,
  { revalidate: false }
)
 
// ...clear cache on logout
clearCache()

Arguments Error Handling