Mutação e atualizações otimistas com SWR

A função mutate global do SWR permite acionar a revalidação de qualquer chave do cache de qualquer lugar da aplicação: mutate('/api/user') faz com que todos os hooks useSWR('/api/user') busquem os dados novamente.

Importe-a com: import { mutate } from 'swr'. Isso é útil para invalidar dados após uma ação do servidor fora de um componente que tenha acesso direto à função mutate associada.

Passe dados como segundo argumento para mutate: mutate('/api/user', updatedUser) define imediatamente o cache como updatedUser, sem fazer uma solicitação de rede. Isso às vezes é chamado de mutação local.

Adicione { revalidate: false } como terceiro argumento para impedir que SWR faça uma nova busca após a atualização otimista.

useSWRMutation foi projetado para mutações iniciadas pelo usuário (envios de formulários, cliques em botões), em oposição à busca automática. Ele não é executado durante a montagem; é executado somente quando você chama trigger().

Importe-o de swr/mutation: const { trigger, isMutating, data, error } = useSWRMutation('/api/post', sendRequest).

A função de busca de useSWRMutation recebe (key, { arg }), em que arg é o valor passado a trigger(). Exemplo: async (url, { arg: newPost }) => fetch(url, { method: 'POST', body: JSON.stringify(newPost) }).

Chame trigger({ title: 'New Post', content: '...' }) para executar a mutação com os dados da publicação como arg.

isMutating de useSWRMutation é true enquanto a solicitação da mutação está em andamento. Utilize-o para desativar botões de envio e exibir indicadores de carregamento durante a solicitação, evitando envios duplicados.

Isso substitui a variável de estado isSubmitting que, de outro modo, teria de ser gerenciada com useState.

Uma atualização otimista aplica imediatamente à interface o resultado esperado, antes que o servidor confirme a alteração. Se o servidor for bem-sucedido, nada mais será necessário. Se falhar, a atualização será revertida para o estado anterior.

Esse padrão faz as interfaces parecerem instantâneas: um botão de curtir parece ser pressionado imediatamente, sem esperar a resposta do POST.

Utilize mutate(key, newData, { optimisticData: optimisticValue, rollbackOnError: true }). O SWR define imediatamente o cache como optimisticValue, envia a solicitação de revalidação e reverte para o valor anterior se a solicitação gerar uma exceção.

A opção rollbackOnError: true é essencial para garantir a correção: sem ela, uma mutação malsucedida deixa dados otimistas obsoletos no cache.

Quando rollbackOnError: true está definido e a mutação é rejeitada, o SWR restaura automaticamente o cache para o instantâneo obtido antes da atualização otimista. Não é necessário escrever código manual de reversão.

Além disso, defina populateCache: false se o corpo da resposta da mutação não tiver o mesmo formato dos dados de useSWR, para impedir que a resposta atualize o cache incorretamente.

useSWR retorna um mutate vinculado: const { data, mutate } = useSWR('/api/user', fetcher). Esse mutate vinculado direciona-se automaticamente à chave '/api/user'; não é necessário informar a chave novamente.

Utilize o mutate vinculado dentro dos componentes responsáveis pela exibição dos dados. Utilize o mutate global do swr quando precisar invalidar uma chave a partir de um componente não relacionado ou de uma função utilitária.

useMutation do React Query tem um padrão semelhante de trigger/isMutating. Principais diferenças: o retorno de chamada onSuccess do React Query com queryClient.invalidateQueries é o padrão idiomático de invalidação do cache. O SWR utiliza diretamente a função mutate para atualizar o cache.

Ambos oferecem suporte a atualizações otimistas e reversão, mas o formato da API é diferente. Equipes proficientes em uma delas podem aprender a outra rapidamente.

Depois de uma mutação bem-sucedida, há três opções: fazer uma nova busca chamando mutate(key), atualizar o cache com o corpo da resposta (se a API retornar o recurso atualizado) ou combinar as duas abordagens com atualizações otimistas e revalidação.

Para mutações em listas (como adicionar um item), atualize manualmente o cache para acrescentar o novo item e depois faça a revalidação para confirmar o estado no servidor. Isso evita uma nova busca completa da lista e mantém os dados consistentes.

Qual opção deve ser definida em mutate do SWR para reverter automaticamente uma atualização otimista em caso de erro?

mutate(key) aciona a revalidação; mutate(key, data) atualiza o cache sem fazer uma nova busca. useSWRMutation gerencia mutações explícitas acionadas pelo usuário com trigger(), o estado isMutating e suporte a extraArg. As atualizações otimistas com optimisticData e rollbackOnError: true fazem as interfaces parecerem instantâneas, com recuperação automática após erros.

O mutate vinculado de useSWR direciona-se à própria chave; o mutate global de swr funciona em qualquer lugar.