Modèles optimistes avec React Query et Zustand

La fonction useMutation de React Query fournit une infrastructure intégrée pour les mises à jour optimistes grâce à trois fonctions de rappel du cycle de vie : onMutate (s’exécute avant la mutation et renvoie un objet de contexte), onError (s’exécute en cas d’échec et reçoit le contexte) et onSettled (s’exécute en cas de réussite ou d’échec). Cette structure est conçue spécifiquement pour les schémas optimistes.

Dans onMutate, effectuez trois étapes : commencez par annuler les requêtes en cours portant sur les données concernées (await queryClient.cancelQueries({ queryKey })), puis capturez un instantané du cache actuel (queryClient.getQueryData(queryKey)) et, enfin, appliquez la mise à jour optimiste au cache (queryClient.setQueryData(queryKey, updater)). Renvoyez l’instantané comme contexte.

La fonction de rappel onError reçoit l’erreur, les variables de la mutation et le contexte renvoyé par onMutate. Utilisez le contexte pour annuler l’opération : queryClient.setQueryData(queryKey, context.previousData). Le contexte sert de lien entre l’instantané capturé dans onMutate et l’annulation effectuée dans onError.

La fonction de rappel onSettled s’exécute quelle que soit l’issue. Utilisez-la pour recharger la requête et la synchroniser avec l’état du serveur : queryClient.invalidateQueries({ queryKey }). Cela garantit qu’après toute mutation — qu’elle ait réussi (le serveur peut avoir transformé les données) ou échoué (l’annulation est terminée) — vous finissez par converger vers l’état de référence du serveur.

Un exemple concret : basculer l’état terminé d’une tâche. Dans onMutate, capturez la liste des tâches, puis mettez à jour la tâche concernée dans le cache. Dans onError, restaurez l’instantané depuis le contexte. Dans onSettled, invalidez la requête des tâches pour la recharger. L’utilisateur voit la bascule immédiatement ; le serveur se synchronise en arrière-plan.

Dans un magasin d’état Zustand, les mises à jour optimistes sont simples : créez une action updateItem(id, changes) qui met immédiatement à jour l’élément dans le magasin, puis appelle l’API. Si l’API échoue, appelez une autre action revertItem(id, previousState). Les mises à jour synchrones de l’état de Zustand rendent l’étape optimiste instantanée.

Lors de la mise à jour optimiste d’un état Zustand profondément imbriqué, utilisez la fonction de production d’Immer pour obtenir des mutations claires : set(produce(state => { state.items[id] = { ...state.items[id], ...changes } })). Immer prend en charge les mises à jour immuables avec une syntaxe mutable, ce qui rend les modifications complexes d’un état imbriqué lisibles et sûres.

React 19 a introduit useOptimistic(state, updateFn), une fonction intégrée pour les mises à jour optimistes dans les actions serveur. const [optimisticState, addOptimistic] = useOptimistic(items, (state, newItem) => [...state, newItem]). L’appel de addOptimistic(newItem) met immédiatement l’interface à jour pendant que l’action serveur s’exécute de manière asynchrone.

useOptimistic gère automatiquement l’annulation. Lorsque l’action serveur se termine (avec succès ou avec une erreur), React rétablit l’état optimiste et applique l’état réel provenant du serveur. Vous n’avez pas besoin d’écrire vous-même la logique d’annulation : React gère le cycle de vie de la mise à jour optimiste pendant la frontière Suspense de l’action.

Les mises à jour optimistes manuelles offrent un contrôle total, mais nécessitent du code répétitif. Le trio onMutate/onError/onSettled de React Query s’intègre au cache des requêtes pour une synchronisation automatique. useOptimistic est la solution la plus simple pour les actions serveur, mais nécessite React 19 et une architecture fondée sur les actions serveur. Faites votre choix en fonction de votre couche de données : manuel pour un état local simple, React Query pour les API REST, useOptimistic pour les RSC/actions serveur.

Tenez compte de votre architecture lorsque vous choisissez un schéma optimiste. Si vous utilisez React Query dans toute votre application, son schéma onMutate est cohérent et tient compte du cache. Si vous utilisez Zustand pour l’état global, le schéma fondé sur des actions s’intègre naturellement. Si vous utilisez React 19 avec les actions serveur, useOptimistic est le choix idiomatique. Il est courant et acceptable de mélanger les schémas au sein d’une même application.

La fonction useMutation de React Query utilise onMutate (annuler les requêtes, capturer un instantané, appliquer la mise à jour optimiste et renvoyer le contexte), onError (restaurer l’instantané depuis le contexte) et onSettled (invalider pour recharger). Les mises à jour optimistes de Zustand appellent immédiatement l’action d’état, puis l’API, et annulent l’opération en cas d’échec. useOptimistic fournit une annulation automatique dans les actions serveur de React 19. Choisissez le schéma adapté à l’architecture de votre couche de données.