Pattern ottimistici con React Query e Zustand

L'hook useMutation di React Query fornisce un'infrastruttura integrata per gli aggiornamenti ottimistici tramite tre callback del ciclo di vita: onMutate (viene eseguita prima della mutazione e restituisce un oggetto di contesto), onError (viene eseguita in caso di errore e riceve il contesto) e onSettled (viene eseguita in caso di successo o errore). Questa struttura è progettata specificamente per i pattern ottimistici.

In onMutate, esegua tre passaggi: innanzitutto annulli le query in corso per i dati interessati (await queryClient.cancelQueries({ queryKey })), quindi salvi uno snapshot della cache corrente (queryClient.getQueryData(queryKey)) e infine applichi l'aggiornamento ottimistico alla cache (queryClient.setQueryData(queryKey, updater)). Restituisca lo snapshot come contesto.

La callback onError riceve l'errore, le variabili della mutazione e il contesto restituito da onMutate. Usi il contesto per eseguire il rollback: queryClient.setQueryData(queryKey, context.previousData). Il contesto fa da collegamento tra lo snapshot acquisito in onMutate e il rollback in onError.

La callback onSettled viene eseguita indipendentemente dal successo o dall'errore. La usi per eseguire il refetch della query e sincronizzarla con lo stato del server: queryClient.invalidateQueries({ queryKey }). In questo modo, dopo qualsiasi mutazione — sia riuscita (il server potrebbe aver trasformato i dati) sia fallita (rollback completato) — si converge infine sullo stato effettivo del server.

Un esempio pratico: alternare lo stato completato di un todo. In onMutate, salvi uno snapshot dell'elenco dei todo, quindi aggiorni lo specifico todo nella cache. In onError, ripristini lo snapshot dal contesto. In onSettled, invalidi la query dei todo per eseguire il refetch. L'utente vede il cambio immediatamente; il server si sincronizza in background.

In uno store Zustand, gli aggiornamenti ottimistici sono semplici: crei un'azione updateItem(id, changes) che aggiorna immediatamente l'elemento nello store, quindi chiama l'API. Se l'API non riesce, chiami un'altra azione revertItem(id, previousState). Gli aggiornamenti sincroni dello stato di Zustand rendono immediato il passaggio ottimistico.

Quando aggiorna ottimisticamente uno stato Zustand profondamente annidato, usi produce di Immer per eseguire mutazioni più leggibili: set(produce(state => { state.items[id] = { ...state.items[id], ...changes } })). Immer gestisce gli aggiornamenti immutabili con una sintassi mutabile, rendendo leggibili e sicure le modifiche a stati annidati complessi.

React 19 ha introdotto useOptimistic(state, updateFn) come hook integrato per gli aggiornamenti ottimistici all'interno delle Server Actions. const [optimisticState, addOptimistic] = useOptimistic(items, (state, newItem) => [...state, newItem]). La chiamata a addOptimistic(newItem) aggiorna immediatamente l'interfaccia mentre la Server Action viene eseguita in modo asincrono.

useOptimistic gestisce automaticamente il rollback. Quando la Server Action viene completata (con successo o con un errore), React ripristina lo stato ottimistico e applica lo stato reale del server. Non è necessario scrivere manualmente la logica di rollback: React gestisce il ciclo di vita dell'aggiornamento ottimistico all'interno del boundary di Suspense dell'azione.

Gli aggiornamenti ottimistici manuali offrono il pieno controllo, ma richiedono codice ripetitivo. onMutate/onError/onSettled di React Query si integra con la cache delle query per la sincronizzazione automatica. useOptimistic è la soluzione più semplice per le Server Actions, ma richiede React 19 e un'architettura basata sulle Server Actions. Scelga in base al data layer: manuale per lo stato locale semplice, React Query per le API REST, useOptimistic per RSC/Server Actions.

Quando sceglie un pattern ottimistico, consideri la sua architettura. Se usa React Query in tutta l'app, il suo pattern onMutate è coerente e tiene conto della cache. Se usa Zustand per lo stato globale, il pattern basato sulle azioni si integra naturalmente. Se usa React 19 con Server Actions, useOptimistic è la scelta idiomatica. Mescolare i pattern all'interno della stessa app è comune e accettabile.

Che cosa dovrebbe restituire la callback onMutate di React Query per consentire il rollback in onError?

React Query useMutation usa onMutate (annulla le query, salva uno snapshot, applica l'aggiornamento ottimistico e restituisce il contesto), onError (ripristina lo snapshot dal contesto) e onSettled (invalida la query per eseguire il refetch). Gli aggiornamenti ottimistici di Zustand chiamano immediatamente l'azione dello stato e poi l'API, eseguendo il ripristino in caso di errore. React 19 useOptimistic offre il rollback automatico all'interno delle Server Actions. Scelga il pattern più adatto all'architettura del suo data layer.