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

useMutation управляет операциями записи (POST/PUT/PATCH/DELETE). В отличие от useQuery, результат мутации не кешируется автоматически, но вы можете синхронизировать его с Query Cache вручную. В v5 добавили массу тонкостей:

• mutationKey участвует в useMutationState, девтулзах и persistQueryClient, поэтому стройте иерархию ключей так же тщательно, как для useQuery.
• Параметры gcTime, networkMode, throwOnError, retry, meta, scope позволяют превратить мутацию в строго типизированную команду с нужными SLA.
• mutationFn теперь получает AbortSignal и meta в третьем аргументе, что удобно для отмены запросов и проброса дополнительных данных.
• mutationCache даёт возможность подписаться на все мутации и строить глобальные тосты, индикаторы отправки или outbox; вместе с persistQueryClient можно хранить историю неотправленных операций и повторять их после восстановления сети.
• useMutationState умеет фильтровать незавершённые/ошибочные мутации — отличный инструмент для глобальных индикаторов прогресса и повторной отправки.
• Композиция queryClient.ensureQueryData + mutation.mutateAsync помогает сначала гарантировать наличие связанных данных (например, пользователя), а уже затем выполнять запись.

Базовый пример

import { useMutation, useQueryClient } from '@tanstack/react-query';
import { createTodo } from './api';

export function CreateTodoForm() {
  const queryClient = useQueryClient();
  const mutation = useMutation({
    mutationKey: ['createTodo'],
    mutationFn: createTodo,
    onSuccess: async () => {
      await queryClient.invalidateQueries({ queryKey: ['todos'], refetchType: 'active' });
    },
  });

  return (
    <form
      onSubmit={event => {
        event.preventDefault();
        const form = new FormData(event.currentTarget);
        mutation.mutate({ title: form.get('title') as string });
      }}
    >
      <input name="title" disabled={mutation.isPending} />
      <button type="submit" disabled={mutation.isPending}>
        {mutation.isPending ? 'Сохраняем…' : 'Создать'}
      </button>
    </form>
  );
}

Что здесь важно

• refetchType: 'active' не трогает кэшированные, но не смонтированные запросы.
• Форма вызывает mutation.mutate, а не mutateAsync, чтобы не забыть про event.preventDefault.
• Пока мутация выполняется, мы блокируем поля ввода и кнопку.

Жизненный цикл мутации

• onMutate (sync/async) — вызывается до mutationFn.
• onSuccess — после успешного завершения.
• onError — при ошибке (error, variables, context).
• onSettled — всегда, независимо от результата.

Все обработчики могут быть заданы глобально через QueryClient.

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

const mutation = useMutation({
  mutationFn: updateTodo,
  onMutate: async updated => {
    await queryClient.cancelQueries({ queryKey: ['todos'] });
    const previous = queryClient.getQueryData<Todo[]>(['todos']);
    queryClient.setQueryData(['todos'], old =>
      old?.map(todo => (todo.id === updated.id ? { ...todo, ...updated } : todo)),
    );
    return { previous };
  },
  onError: (_err, _vars, context) => {
    if (context?.previous) {
      queryClient.setQueryData(['todos'], context.previous);
    }
  },
  onSettled: () => {
    queryClient.invalidateQueries({ queryKey: ['todos'] });
  },
});

• onMutate может вернуть контекст, доступный в onError/onSettled.
• Важно отменить активные запросы перед изменением кеша, чтобы не перезаписать оптимистичные данные прошлыми ответами.

Тонкости оптимизма v5

• Возвращайте из onMutate не только предыдущие данные, но и функцию rollback, чтобы в onError просто вызвать context.rollback?.().
• Можно комбинировать оптимистичное обновление с mutation.setState({ status: 'success', data: ... }), чтобы UI мгновенно переключал состояния без ожидания сетевого ответа.
• Для бесконечных списков (useInfiniteQuery) используйте queryClient.setQueriesData с pageParam и аккуратно обновляйте нужную страницу.
• Если мутация зависит от другой мутации, используйте mutation.addRevertListener(fn) (через mutationCache), чтобы откатывать каскадно.

mutate vs mutateAsync

• mutate(variables, { onSuccess }) — callback-стиль.
• mutateAsync(variables) — возвращает Promise, удобно для async/await форм.

await mutation.mutateAsync(formData);
toast.success('Задача обновлена');

Обновление кеша без инвалидции

useMutation({
  mutationFn: toggleTodo,
  onSuccess: (data) => {
    queryClient.setQueryData(['todo', data.id], data);
    queryClient.setQueriesData(
      { queryKey: ['todos'] },
      old => old?.map(todo => (todo.id === data.id ? data : todo)),
    );
  },
});

Это уменьшает количество запросов в сеть и делает UI мгновенным.

Когда всё же инвалидировать

• После мутации, которая меняет количество элементов (создание/удаление), лучше инвалидировать список, чтобы обновить пагинацию и счётчики.
• Если сервер может выполнить дополнительные побочные эффекты (например, обновить метаданные проекта), безопаснее вызвать invalidateQueries по связанным ключам (['project', projectId]).
• Для очень тяжёлых запросов можно использовать refetchType: 'none' и queryClient.setQueryData, а сервер «догонять» бекграундным prefetchQuery.

meta и конфигурация

useMutation({
  mutationFn: ({ title }) => client.post('/todos', { title }),
  meta: { feature: 'todo-create' },
  onSuccess: (_data, _vars, _ctx, mutation) => {
    analytics.track('todo_created', mutation.meta);
  },
});

Где ещё полезен meta

• mutationFn: async (vars, { signal, meta }) => ... — можно передать meta.traceId, segment, optimisticResponse.
• mutationCache.subscribe получает mutation.options.meta, что позволяет строить глобальные уведомления с категорией события.
• useMutationState({ filters: { meta: { feature: 'todo-create' }, status: 'pending' } }) — быстро показывает, что конкретно сейчас отправляется.

Состояния мутации

• status: 'idle' | 'pending' | 'error' | 'success'
• Булевы помощники: isPending, isSuccess, isError, isIdle, isPaused
• Трассировка: failureCount, failureReason, submittedAt

Откат (Rollback) и очередь

• Для нескольких оптимистичных изменений комбинируйте mutationCache и onMutate, чтобы хранить историю.
• В офлайн-сценариях используйте persistQueryClient + onlineManager, чтобы повторить мутации после восстановления сети.

Лучшие практики

• Каждой сущности — свой mutationKey.
• Избегайте инвалидации ['todos'] без фильтров, если обновляете только один элемент — используйте invalidateQueries({ queryKey: ['todos'], exact: true }) или setQueryData.
• В формах используйте mutation.reset() при повторном открытии модалки.

Дополнительные паттерны

Глобальные индикаторы отправки

const pendingSaves = useMutationState({
  filters: { status: 'pending', mutationKey: ['todo', 'save'] },
});

return <Spinner hidden={!pendingSaves.length} />;

useMutationState подписывается на кэш мутаций, не требует проп-дриллинга и автоматически очищается по gcTime.

Каскадные мутации

const updateTodo = useMutation({ mutationKey: ['todos', 'update'], mutationFn: patchTodo });
const revalidateStats = useMutation({ mutationKey: ['stats', 'sync'], mutationFn: syncStats });

await updateTodo.mutateAsync(payload);
await revalidateStats.mutateAsync({ projectId: payload.projectId });

• Если вторую мутацию нужно запускать только при успехе первой, вызывайте её из onSuccess.
• Чтобы не потерять контекст ошибки, используйте Promise.allSettled.

Управление очередью

• Для режима «одна мутация за раз» проверяйте mutation.isPending перед следующим вызовом или используйте p-retry/p-queue.
• При необходимости отправлять пачки (bulk update) используйте meta.batchId и храните промежуточные ответы в mutationCache.

Работа с AbortController

const mutation = useMutation({
  mutationFn: async (payload, { signal }) => {
    return client.post('/upload', payload, { signal });
  },
});

useEffect(() => {
  return () => mutation.reset(); // отменит активную загрузку при размонтировании формы
}, [mutation]);

Предзаполнение форм и связывание с query

• Берите данные для отправки напрямую из queryClient.getQueryData, чтобы не хранить лишнее состояние.
• Комбинируйте useQuery + useMutation в одном хуке, возвращая data, mutate и isPending. Это упрощает повторное использование бизнес-логики.

Инструменты отладки

• В девтулзах можно включить отображение mutationCache и видеть историю всех POST/PUT/DELETE.
• queryClient.getMutationCache().find({ mutationKey }) помогает собрать статистику или принудительно завершить/удалить мутацию.
• В тестах используйте await waitFor(() => expect(mutation.isSuccess).toBe(true)), а затем проверяйте, что правильные данные оказались в queryClient.