Padrões otimistas com React Query e Zustand

O gancho useMutation do React Query oferece infraestrutura integrada para atualizações otimistas por meio de três retornos de chamada do ciclo de vida: onMutate (é acionado antes da mutação e retorna um objeto de contexto), onError (é acionado em caso de falha e recebe o contexto) e onSettled (é acionado em caso de sucesso ou falha). Essa estrutura foi criada especificamente para padrões otimistas.

Em onMutate, você executa três etapas: primeiro, cancela todas as consultas em andamento dos dados afetados (await queryClient.cancelQueries({ queryKey })); depois, captura o cache atual (queryClient.getQueryData(queryKey)); por fim, aplica a atualização otimista ao cache (queryClient.setQueryData(queryKey, updater)). Retorne a captura como contexto.

O retorno de chamada onError recebe o erro, as variáveis da mutação e o contexto retornado por onMutate. Use o contexto para reverter: queryClient.setQueryData(queryKey, context.previousData). O contexto é a ponte entre a captura feita em onMutate e a reversão em onError.

O retorno de chamada onSettled é acionado independentemente de a operação ter sido concluída com sucesso ou falhado. Use-o para buscar novamente a consulta e sincronizar com o estado do servidor: queryClient.invalidateQueries({ queryKey }). Isso garante que, após qualquer mutação — seja ela bem-sucedida (o servidor pode ter transformado os dados) ou malsucedida (a reversão foi concluída) —, você eventualmente convergirá para a verdade do servidor.

Um exemplo prático: alternar o estado de conclusão de uma tarefa. Em onMutate, faça uma captura da lista de tarefas e atualize a tarefa específica no cache. Em onError, restaure a captura a partir do contexto. Em onSettled, invalide a consulta de tarefas para buscá-la novamente. O usuário vê a alternância instantaneamente; o servidor é sincronizado em segundo plano.

Em uma loja Zustand, as atualizações otimistas são simples: crie uma ação updateItem(id, changes) que atualize imediatamente o item na loja e depois chame a API. Se a API falhar, chame outra ação revertItem(id, previousState). As atualizações síncronas de estado do Zustand tornam a etapa otimista instantânea.

Ao atualizar de forma otimista um estado profundamente aninhado do Zustand, use o produce do Immer para obter mutações mais limpas: set(produce(state => { state.items[id] = { ...state.items[id], ...changes } })). O Immer gerencia atualizações imutáveis com uma sintaxe mutável, tornando as alterações complexas em estados aninhados legíveis e seguras.

O React 19 introduziu useOptimistic(state, updateFn) como um gancho integrado para atualizações otimistas em ações do servidor. const [optimisticState, addOptimistic] = useOptimistic(items, (state, newItem) => [...state, newItem]). Chamar addOptimistic(newItem) atualiza imediatamente a interface enquanto a ação do servidor é executada de forma assíncrona.

useOptimistic gerencia a reversão automaticamente. Quando a ação do servidor é concluída (com sucesso ou com um erro), o React reverte o estado otimista e aplica o estado real do servidor. Você não precisa escrever uma lógica manual de reversão — o React gerencia o ciclo de vida da atualização otimista durante o limite de Suspense da ação.

As atualizações otimistas manuais oferecem controle total, mas exigem código repetitivo. React Query onMutate/onError/onSettled integra-se ao cache de consultas para fazer a sincronização automática. useOptimistic é a opção mais simples para ações do servidor, mas requer React 19 e uma arquitetura de ações do servidor. Escolha com base na sua camada de dados: manual para estados locais simples, React Query para APIs REST e useOptimistic para RSC/ações do servidor.

Considere sua arquitetura ao escolher um padrão otimista. Se você usa React Query em toda a aplicação, o padrão onMutate é consistente e tem conhecimento do cache. Se usa Zustand para o estado global, o padrão baseado em ações se encaixa naturalmente. Se está usando React 19 com ações do servidor, useOptimistic é a escolha idiomática. Misturar padrões em uma mesma aplicação é comum e aceitável.

O que o retorno de chamada onMutate deve retornar no React Query para permitir a reversão em onError?

useMutation do React Query usa onMutate (cancela consultas, faz uma captura, aplica a atualização otimista e retorna o contexto), onError (restaura a captura a partir do contexto) e onSettled (invalida para buscar novamente). As atualizações otimistas do Zustand chamam a ação de estado imediatamente e depois a API, revertendo em caso de falha. useOptimistic do React 19 oferece reversão automática em ações do servidor. Escolha o padrão que se adapta à arquitetura da sua camada de dados.