New onQuery handler?

[denisborovikov]

In some cases, we might want to optimistically update the cache before or at the same time, when the mutation occurs.

We can do it by using queryCache.setQueryData and then calling mutation function like here

queryCache.setQueryData('todos', [...data, text])
...
mutatePostTodo(text)

But as I can see, we can't encapsulate an optimistic cache update into the custom hook. If we would have a handler, that executes at the same time as the mutation, we could do it:

function useCustomDelete() {
  return useMutation(foo, { onQuery: variables => queryCache.setQueryData(...)})
}

const [delete] = useCustomDelete();
...
delete(variables);

What do you think?

[tannerlinsley]

Ooooooo very interesting. How about onMutate?

[denisborovikov]

Yes, it makes more sense in this context.

[tannerlinsley]

Would it be worth discussing how a general rollback would take place too? Eg if the mutation falls?

[denisborovikov]

I think, existing onError/onSettled should perfectly work here.

[tannerlinsley]

What about storing the previous value before the optimistic update?

[denisborovikov]

I see what you mean. I didn't think about it in this way. I meant we can refetch query from the server in case of error.

[denisborovikov]

I think this will work.

function useCustomDelete() {
  const rollback = queryCache. getQueryData(...);
  return useMutation(foo, { 
    onMutation: variables => queryCache.setQueryData(...)},
    onError: () => queryCache.setQueryData(rollback),
  )
}

const [delete] = useCustomDelete();
...
delete(variables);

[tannerlinsley]

What do you think about this?

Automatic Rollback for Failed Mutations

When you optimistically update your state before performing a mutation, there is a non-zero chance that the mutation will fail. In that event, you would normally refetch your queries that you optimistically updated. In some circumstances though, refetching may not work correctly and the mutation error could represent some type of server issue that won't make it possible to refetch. In this event, you can instead choose to rollback your update.

To do this, useMutation provides an onMutate handler that can achieve both the optimistic update and the rollback logic in one single API. First, you define your optimistic update, then return a function to run in the event that the mutation fails:

useMutation(updateTodo, {
  onMutate: (newTodo) => {
    // Store the previous value in this closure
    const previousTodo = queryCache.getQueryData(['todos', newTodo.id])

    // Optimistically update the query data
    queryCache.setQueryData(['todos', newTodo.id], newTodo)

    // Return a rollback function
    return (err) => {
      queryCache.setQueryData(['todos', newTodo.id], previousTodo)
    }
  }
})

[tannerlinsley]

So it would look more like this:

useMutation(updateTodo, {
  // When mutate is called:
  onMutate: (newTodo) => {
    // Store the previous value in this closure
    const previousTodo = queryCache.getQueryData(['todos', newTodo.id])

    // Optimistically update the query data
    queryCache.setQueryData(['todos', newTodo.id], newTodo)

    // Return a rollback value
    return previousTodo
  },
  // If the mutation fails:
  onError: (err, newTodo, previousTodo) => {
    queryCache.setQueryData(['todos', newTodo.id], previousTodo)
  }
  // If the mutation was successful:
  onSuccess: newTodo => queryCache.setQueryData(['todos', newTodo.id], newTodo)
})

[tannerlinsley]

While the first approach is very useEffect-esque with the rollback function, I like the idea of only having one single handler for each side-effect

[denisborovikov]

My concern is that originally I thought about a general-purpose handler which fires at the same time as mutation happens. The second thought was that we can use it for optimistic updates. But it's not limited to this use-case, so returning value or function may cause questions. Maybe it makes sense to name the handler specifically for optimistic updates.

[tannerlinsley]

I think it's totally fine to define the API up front that whatever you return will be available in the onError handler. As long as it's documented well, I think onMutate is a fine name, mostly because it corresponds to what is happening and when, instead of assuming a specific purpose like onMutateRollback, which is really just one interpretation of how to use the side-effect.

[cherniavskii]

I like "return value" more, because there's less magic in it
Also, onMutate naming seems good to me

[cherniavskii]

But as I can see, we can't encapsulate an optimistic cache update into the custom hook.

Did you consider something like this?

function useCustomDelete() {
  const [mutate, ...mutation] = useMutation(foo);

  function customMutate(...args) {
    queryCache.setQueryData(...)
    return mutate(...args)
  }

  return [customMutate, ...mutation];
}

const [delete] = useCustomDelete();
...
delete(variables);

[tannerlinsley]

You would still end up needing to get the previous value, then extend the functionality of the onError handler to revert back. It's not that it's not possible to do right now, and more that the API doesn't afford to it.

[denisborovikov]

Yes, this is also possible but looks hacky for me. You'll probably also need to use useMemo to preserve reference equality what makes the code even more verbose. The logic base on handlers seems more idiomatic.

[tannerlinsley]

Agreed. I think this approach is my favorite right now.

[cherniavskii]

Just wanted to make sure it's possible right now

[tannerlinsley]

Here are the final docs:

Automatic Rollback for Failed Mutations

When you optimistically update your state before performing a mutation, there is a non-zero chance that the mutation will fail. In most cases, you can just trigger a refetch for your optimistic queries to revert them to their true server state. In some circumstances though, refetching may not work correctly and the mutation error could represent some type of server issue that won't make it possible to refetch. In this event, you can instead choose to rollback your update.

To do this, useMutation's onMutate handler option allows you to return a snapshotted rollback value that will later be passed to both onError and onSettled handlers as the last argument:

useMutation(updateTodo, {
  // When mutate is called:
  onMutate: (newTodo) => {
    // Snapshot the previous value
    const previousTodo = queryCache.getQueryData(['todos', newTodo.id])

    // Optimistically update to the new value
    queryCache.setQueryData(['todos', newTodo.id], newTodo)

    // Return the snapshotted value
    return previousTodo
  },
  // If the mutation fails, use the value returned from onMutate to roll back
  onError: (err, newTodo, previousTodo) => {
    queryCache.setQueryData(['todos', newTodo.id], previousTodo)
  }
  // If the mutation was successful:
  onSuccess: newTodo => {
    queryCache.setQueryData(['todos', newTodo.id], newTodo)
  }
})

You can also use the onSettled function in place of the separate onError and onSuccess handlers if you wish:

useMutation(updateTodo, {
  // ...
  onSettled: (newTodo, error, variables, previousTodo) => {
    if (error) {
      queryCache.setQueryData(['todos', newTodo.id], previousTodo)
    } else {
      queryCache.setQueryData(['todos', newTodo.id], newTodo)
    }
  },
})

[cherniavskii]

- onError: (err, newTodo, previousTodo) => {
+ onError: (err, variables, previousTodo) => {

?

[cherniavskii]

actually it doesn't matter

[tannerlinsley]

Yeah, that's actually just for the example/walkthrough portion of the docs. The actual API docs have it listed more generically.