Mutações Otimistas no Frontend (o caminho de escrita)

Quando Usar

Use esta habilidade quando precisar de uma disciplina portátil e independente de framework para o caminho de escrita de qualquer aplicativo React ou React Native que use uma camada de consulta/cache. Codifica o ciclo de vida da atualização otimista (cancelar consultas em andamento → instantâneo de todo o cache afetado → aplicar patch instantaneamente → reverter exatamente em caso de erro → invalidar em...

Habilidade portátil — legível por Claude Code, OpenCode, Codex, Cursor, Windsurf e outros. Esta habilidade descreve a disciplina do caminho de escrita — atualizações otimistas, reversão, idempotência, coerência de cache — não uma biblioteca de UI ou um sistema de estilo. Ela se baseia diretamente na habilidade contratos-de-dados-frontend (escritas passam pelo cliente tipado) e na habilidade arquitetura-frontend (mutações vivem em modules/{feature}/hooks/, indexadas por uma fábrica).

O objetivo: uma escrita parece instantânea (a UI a reflete antes que o servidor confirme), é segura (uma falha restaura o estado anterior exato, e uma nova tentativa nunca cobra duas vezes) e deixa o cache coerente (a página de detalhes e todas as páginas de lista concordam). Todas as três ao mesmo tempo — essa é a arte.

0. As cinco ideias centrais

1. O ciclo de vida otimista é fixo. cancelar → instantâneo → aplicar patch → (erro: reverter) → (concluir: invalidar). Toda mutação otimista segue os mesmos cinco passos.
2. Reverta exatamente. Em caso de falha, restaure o instantâneo exato tirado antes do patch — não uma re-derivação de "melhor palpite". Mantenha o instantâneo no contexto da mutação.
3. A idempotência é gerada uma vez, não por tentativa. A chave é criada na inicialização do formulário (ou primeira intenção), para que uma nova tentativa de rede reproduza a resposta original do servidor em vez de executar a ação duas vezes.
4. Os caches se movem em sincronia. Uma mudança de status aplica patch ao cache de detalhes e a todas as páginas de lista que contêm a entidade, para que os indicadores nunca discordem entre as superfícies.
5. O estado do servidor nunca entra no armazenamento do cliente. O estado otimista vive no cache de consulta, não em Zustand/Redux. O cache é a única fonte de verdade para os dados do servidor (por arquitetura-frontend §4).

1. Quando ser otimista (e quando não ser)

O otimismo é uma ferramenta de UX para escritas que você tem confiança de que terão sucesso. Se a falha for comum ou cara de desfazer, prefira um estado pendente.

2. O ciclo de vida otimista (TanStack Query)

A forma canônica. Cada passo tem um trabalho; pular um quebra a correção.

// modules/invoice/hooks/useInvoiceMutations.ts
interface MarkPaidContext {
  previousInvoice: Invoice | undefined; // instantâneo do detalhe
  previousLists: Array<[readonly unknown[], InvoiceListResponse]>; // instantâneo de cada página de lista
}

export function useMarkInvoicePaid() {
  const queryClient = useQueryClient();
  const notifyError = useApiErrorToast();

  return useMutation<Invoice, ApiError, { id: InvoiceId }, MarkPaidContext>({
    mutationFn: ({ id }) => apiClient.post<Invoice>(INVOICE_API.markPaid(id)),

    // 1 + 2 + 3: cancelar leituras em andamento, instantâneo, aplicar patch
    onMutate: async ({ id }) => {
      await queryClient.cancelQueries({ queryKey: invoiceKeys.all }); // (1) sem sobrescrita de refetch tardio

      const detailKey = invoiceKeys.detail(id);

…