6. Мутации и оптимистичные апдейты

useMutation отвечает за запись: создание, обновление, удаление, запуск серверных команд.

Важная разница с запросами:

• query автоматически кешируются
• mutation автоматически не синхронизируют query cache

Именно поэтому после мутации вы обычно делаете одно из двух:

• инвалидируете связанные запросы
• обновляете кеш вручную через setQueryData

Базовый useMutation

const queryClient = useQueryClient()

const createTodoMutation = useMutation({
  mutationKey: ['todos', 'create'],
  mutationFn: createTodo,
  onSuccess: async () => {
    await queryClient.invalidateQueries({ queryKey: ['todos'] })
  },
})

Что стоит запомнить:

• mutationKey помогает в Devtools, useMutationState и общей телеметрии.
• Если возвращаете Promise из onSuccess или onSettled, mutation будет считаться pending до завершения этой работы.

mutate и mutateAsync

• mutate удобен в обработчиках событий.
• mutateAsync удобен в async/await сценариях.

await createTodoMutation.mutateAsync({ title })
toast.success('Created')

Обновление кеша из ответа мутации

Если сервер возвращает обновлённый объект, не обязательно делать лишний refetch:

const updateTodoMutation = useMutation({
  mutationFn: updateTodo,
  onSuccess: (data, variables) => {
    queryClient.setQueryData(['todos', 'detail', variables.id], data)
  },
})

Это официальный и рекомендуемый паттерн для detail-записей.

Иммутабельность

queryClient.setQueryData(['todos', 'detail', id], (old) =>
  old
    ? {
        ...old,
        title: newTitle,
      }
    : old,
)

Никогда не мутируйте old напрямую.

Оптимистичное обновление через UI

Самый простой вариант: не трогать кеш, а показать временный элемент по variables.

const addTodoMutation = useMutation({
  mutationKey: ['todos', 'create'],
  mutationFn: (text: string) => axios.post('/api/todos', { text }),
  onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
})

const optimisticText = addTodoMutation.variables

Такой подход хорош, если optimistic state нужен только в одном месте экрана.

Оптимистичное обновление через кеш

Если optimistic state должен отразиться в нескольких местах, обновляйте кеш.

const mutation = useMutation({
  mutationFn: updateTodo,
  onMutate: async (newTodo, context) => {
    await context.client.cancelQueries({ queryKey: ['todos'] })

    const previousTodos = context.client.getQueryData<Todo[]>(['todos'])

    context.client.setQueryData<Todo[]>(['todos'], (old = []) =>
      old.map((todo) =>
        todo.id === newTodo.id ? { ...todo, ...newTodo } : todo,
      ),
    )

    return { previousTodos }
  },
  onError: (_error, _variables, onMutateResult, context) => {
    context.client.setQueryData(['todos'], onMutateResult?.previousTodos)
  },
  onSettled: (_data, _error, variables, _onMutateResult, context) => {
    return context.client.invalidateQueries({ queryKey: ['todos'] })
  },
})

Это актуальный паттерн из официальной документации:

• в onMutate отменяем конкурирующие refetch
• сохраняем snapshot
• пишем optimistic data
• в onError откатываем
• в onSettled синхронизируем с сервером

Когда инвалидировать, а когда писать в кеш

Инвалидировать лучше, если:

• меняется список, пагинация, счётчики, сортировка
• сервер выполняет побочные эффекты
• клиенту трудно точно воспроизвести итоговое состояние

Писать в кеш лучше, если:

• mutation возвращает готовый detail-объект
• изменение локальное и полностью известно
• лишний refetch только создаст шум

На практике часто используют гибрид:

• setQueryData для мгновенного UI
• invalidateQueries для гарантии консистентности

useMutationState

Позволяет читать состояние мутаций в любом месте приложения.

const pendingTodos = useMutationState<string>({
  filters: {
    mutationKey: ['todos', 'create'],
    status: 'pending',
  },
  select: (mutation) => mutation.state.variables,
})

Подходит для:

• глобальных индикаторов сохранения
• optimistic UI вне компонента, где вызывается mutate
• очередей отправки

Состояния mutation

• isIdle
• isPending
• isSuccess
• isError
• isPaused

Плюс полезные поля:

• variables
• submittedAt
• failureCount
• failureReason

Ошибки и retry

Для мутаций retry нужен реже, чем для query.

Обычно:

• формы: retry: 0
• идемпотентные команды: кастомный retry
• offline-first: networkMode: 'offlineFirst' и персистентность

Практические советы

• Не инвалидируйте весь кеш после каждой мутации.
• Привязывайте mutationKey к доменной модели, а не к названию кнопки.
• Для detail-записей используйте mutation response, а не обязательный refetch.
• Для optimistic list updates сначала отменяйте активные queries.