Pola Optimistis dengan React Query dan Zustand

Pengait useMutation milik React Query menyediakan infrastruktur bawaan untuk pembaruan optimistis melalui tiga panggilan balik siklus hidup: onMutate dipanggil sebelum mutasi dan mengembalikan objek konteks, onError dipanggil saat gagal dan menerima konteks, serta onSettled dipanggil saat berhasil maupun gagal. Struktur ini dirancang khusus untuk pola optimistis.

Dalam onMutate, lakukan tiga langkah: pertama, batalkan semua kueri yang sedang berlangsung untuk data yang terdampak (await queryClient.cancelQueries({ queryKey })), lalu buat cuplikan tembolok saat ini (queryClient.getQueryData(queryKey)), dan terakhir terapkan pembaruan optimistis ke tembolok (queryClient.setQueryData(queryKey, updater)). Kembalikan cuplikan tersebut sebagai konteks.

Panggilan balik onError menerima kesalahan, variabel mutasi, dan konteks yang dikembalikan dari onMutate. Gunakan konteks tersebut untuk memulihkan status: queryClient.setQueryData(queryKey, context.previousData). Konteks menjadi penghubung antara cuplikan yang diambil dalam onMutate dan pemulihan dalam onError.

Panggilan balik onSettled dipanggil baik saat berhasil maupun gagal. Gunakan untuk mengambil ulang kueri dan menyinkronkan status dengan server: queryClient.invalidateQueries({ queryKey }). Dengan demikian, setelah mutasi apa pun—baik berhasil karena server mungkin telah mengubah data maupun gagal karena pemulihan telah selesai—status Anda pada akhirnya akan selaras dengan kebenaran server.

Contoh praktisnya adalah mengubah status selesai sebuah tugas. Dalam onMutate, buat cuplikan daftar tugas, lalu perbarui tugas tertentu di tembolok. Dalam onError, pulihkan cuplikan dari konteks. Dalam onSettled, tandai kueri tugas agar diambil ulang. Pengguna melihat perubahan seketika, sementara server menyinkronkannya di latar belakang.

Dalam penyimpanan Zustand, pembaruan optimistis cukup sederhana: buat tindakan updateItem(id, changes) yang langsung memperbarui elemen di penyimpanan, lalu memanggil API. Jika API gagal, panggil tindakan lain, revertItem(id, previousState). Pembaruan status sinkron milik Zustand membuat langkah optimistis berlangsung seketika.

Saat memperbarui status Zustand bertingkat secara optimistis, gunakan produce milik immer untuk mutasi yang rapi: set(produce(state => { state.items[id] = { ...state.items[id], ...changes } })). Immer menangani pembaruan yang tidak dapat diubah dengan sintaks yang dapat mengubah data, sehingga perubahan status bertingkat yang rumit menjadi mudah dibaca dan aman.

React 19 memperkenalkan useOptimistic(state, updateFn) sebagai pengait bawaan untuk pembaruan optimistis dalam Tindakan Server. const [optimisticState, addOptimistic] = useOptimistic(items, (state, newItem) => [...state, newItem]). Pemanggilan addOptimistic(newItem) langsung memperbarui antarmuka pengguna sementara tindakan server berjalan secara asinkron.

useOptimistic menangani pemulihan secara otomatis. Saat Tindakan Server selesai, baik berhasil maupun dengan kesalahan, React mengembalikan status optimistis dan menerapkan status nyata dari server. Anda tidak perlu menulis logika pemulihan manual—React mengelola siklus hidup pembaruan optimistis selama batas Suspense tindakan tersebut.

Pembaruan optimistis manual memberi kendali penuh, tetapi memerlukan kode berulang. React Query onMutate/onError/onSettled terintegrasi dengan tembolok kueri untuk sinkronisasi otomatis. useOptimistic adalah pilihan paling sederhana untuk Tindakan Server, tetapi memerlukan React 19 dan arsitektur tindakan server. Pilih berdasarkan lapisan data Anda: manual untuk status lokal sederhana, React Query untuk API REST, dan useOptimistic untuk RSC/Tindakan Server.

Pertimbangkan arsitektur Anda saat memilih pola optimistis. Jika Anda menggunakan React Query di seluruh aplikasi, polanya yang menggunakan onMutate konsisten dan memperhatikan tembolok. Jika Anda menggunakan Zustand untuk status global, pola berbasis tindakan akan cocok secara alami. Jika Anda menggunakan React 19 dengan Tindakan Server, useOptimistic adalah pilihan yang paling sesuai dengan pola React. Mencampur pola dalam satu aplikasi merupakan hal yang umum dan dapat diterima.

Apa yang harus dikembalikan panggilan balik onMutate di React Query agar pemulihan dapat dilakukan dalam onError?

React Query useMutation menggunakan onMutate untuk membatalkan kueri, membuat cuplikan, menerapkan pembaruan optimistis, dan mengembalikan konteks; onError untuk memulihkan cuplikan dari konteks; serta onSettled untuk menandai kueri tidak berlaku agar dapat diambil ulang. Pembaruan optimistis Zustand langsung memanggil tindakan status, lalu API, dan memulihkan status saat gagal. React 19 useOptimistic menyediakan pemulihan otomatis dalam Tindakan Server. Pilih pola yang sesuai dengan arsitektur lapisan data Anda.