Patrones optimistas con React Query y Zustand

El hook useMutation de React Query proporciona infraestructura integrada para las actualizaciones optimistas mediante tres callbacks del ciclo de vida: onMutate (se ejecuta antes de la mutación y devuelve un objeto de contexto), onError (se ejecuta cuando falla y recibe el contexto) y onSettled (se ejecuta tanto si tiene éxito como si falla). Esta estructura está diseñada específicamente para los patrones optimistas.

En onMutate, realice tres pasos: primero, cancele las consultas en curso de los datos afectados (await queryClient.cancelQueries({ queryKey })); después, guarde una instantánea de la caché actual (queryClient.getQueryData(queryKey)); por último, aplique la actualización optimista a la caché (queryClient.setQueryData(queryKey, updater)). Devuelva la instantánea como contexto.

El callback onError recibe el error, las variables de la mutación y el contexto devuelto por onMutate. Use el contexto para revertir los cambios: queryClient.setQueryData(queryKey, context.previousData). El contexto conecta la instantánea tomada en onMutate con la reversión realizada en onError.

El callback onSettled se ejecuta tanto si la operación tiene éxito como si falla. Úselo para volver a solicitar la consulta y sincronizarla con el estado del servidor: queryClient.invalidateQueries({ queryKey }). Esto garantiza que, después de cualquier mutación —tanto si tuvo éxito (el servidor puede haber transformado los datos) como si falló (la reversión se completó)—, el estado termine convergiendo hacia la información real del servidor.

Un ejemplo práctico es alternar el estado de completado de una tarea. En onMutate, guarde una instantánea de la lista de tareas y, después, actualice la tarea específica en la caché. En onError, restaure la instantánea desde el contexto. En onSettled, invalide la consulta de tareas para volver a solicitar los datos. El usuario ve el cambio al instante y el servidor se sincroniza en segundo plano.

En un almacén de Zustand, las actualizaciones optimistas son sencillas: cree una acción updateItem(id, changes) que actualice inmediatamente el elemento en el almacén y, después, llame a la API. Si la API falla, llame a otra acción revertItem(id, previousState). Las actualizaciones de estado síncronas de Zustand hacen que el paso optimista sea inmediato.

Al actualizar de forma optimista un estado de Zustand profundamente anidado, use produce de immer para realizar mutaciones de forma clara: set(produce(state => { state.items[id] = { ...state.items[id], ...changes } })). Immer gestiona las actualizaciones inmutables con una sintaxis mutable, lo que hace que los cambios complejos en estados anidados sean legibles y seguros.

React 19 introdujo useOptimistic(state, updateFn) como hook integrado para las actualizaciones optimistas dentro de las Server Actions. const [optimisticState, addOptimistic] = useOptimistic(items, (state, newItem) => [...state, newItem]). Al llamar a addOptimistic(newItem), la interfaz de usuario se actualiza inmediatamente mientras la acción del servidor se ejecuta de forma asíncrona.

useOptimistic gestiona la reversión automáticamente. Cuando la Server Action termina (correctamente o con un error), React revierte el estado optimista y aplica el estado real del servidor. No necesita escribir lógica de reversión manual: React gestiona el ciclo de vida de la actualización optimista durante el límite Suspense de la acción.

Las actualizaciones optimistas manuales ofrecen control total, pero requieren código repetitivo. React Query, mediante onMutate/onError/onSettled, se integra con la caché de consultas para sincronizarla automáticamente. useOptimistic es la opción más sencilla para las Server Actions, pero requiere React 19 y una arquitectura basada en acciones del servidor. Elija según su capa de datos: manual para estados locales sencillos, React Query para API REST y useOptimistic para RSC/Server Actions.

Tenga en cuenta su arquitectura al elegir un patrón optimista. Si usa React Query en toda la aplicación, su patrón onMutate es coherente y tiene en cuenta la caché. Si usa Zustand para el estado global, el patrón basado en acciones encaja de forma natural. Si trabaja con React 19 y Server Actions, useOptimistic es la opción idiomática. Es habitual y aceptable combinar patrones en una misma aplicación.

¿Qué debe devolver el callback onMutate en React Query para permitir la reversión en onError?

React Query useMutation usa onMutate (cancela consultas, guarda una instantánea, aplica la actualización optimista y devuelve el contexto), onError (restaura la instantánea desde el contexto) y onSettled (invalida la consulta para volver a solicitar los datos). Las actualizaciones optimistas de Zustand llaman primero a la acción de estado y después a la API, y revierten los cambios si falla. React 19 useOptimistic proporciona una reversión automática dentro de las Server Actions. Elija el patrón que se adapte a la arquitectura de su capa de datos.