Cache invalidation patterns: invalidate vs write-through, optimistic rollback, and live sync

Invalidate vs setQueryData: truth by refetch or truth by replication

invalidateQueries({ queryKey: ['invoices'] }) is the conservative move: prefix-match the affected keys, mark them stale, refetch the active ones. You get server truth — sort order, computed totals, rows other users added — at the price of one extra round trip and a brief window where the old data is still on screen. setQueryData(['invoices'], updater) is write-through: patch the cached value synchronously, zero requests, instant UI. Its price is sneakier: your updater must replicate server logic. Insert the new invoice — at which position? The list is sorted by a server-assigned number. Does it match the current filter? Did the server set dueDate, normalize the currency, trigger a side effect on another row? Every divergence is a silent lie in the cache. The senior default: write-through with the server’s response (onSuccess: (created) => setQueryData(...) patching the created object in), or write-through then invalidate — instant UI now, truth reconciled in the background. Reserve pure setQueryData for caches whose shape you fully control, and never invalidate without a key: scope it to the resource family that actually changed, or a 40-widget dashboard turns every checkbox into a request storm.

Optimistic updates: the three-step contract with a rollback

For interactions where even one round trip feels broken — likes, toggles, drag-reorder — update the cache before the server confirms. The contract has three mandatory steps, all in onMutate:

const mutation = useMutation({
  mutationFn: toggleTodo,
  onMutate: async (todo) => {
    // 1. Cancel: an in-flight refetch would overwrite our optimistic write
    await queryClient.cancelQueries({ queryKey: ["todos"] });
    // 2. Snapshot: what we roll back to if the server says no
    const previous = queryClient.getQueryData(["todos"]);
    // 3. Optimistic write-through
    queryClient.setQueryData(["todos"], (old) =>
      old.map((t) => (t.id === todo.id ? { ...t, done: !t.done } : t))
    );
    return { previous };                      // → context
  },
  onError: (_err, _todo, context) =>
    queryClient.setQueryData(["todos"], context.previous), // rollback
  onSettled: () =>
    queryClient.invalidateQueries({ queryKey: ["todos"] }), // reconcile
});

Each step exists because of a specific failure. Skip cancel and a refetch that started before your click can land after your optimistic write and revert it mid-flight — the checkbox flickers off, then on again when the mutation settles; users file it as “the app fought me”. Skip snapshot/rollback and a server rejection leaves the UI permanently claiming something false — the like that never happened. Skip reconcile in onSettled and your optimistic guess (even a correct one) drifts from server-computed fields. The tradeoff is honest: optimistic UI converts p50 latency into zero perceived latency, but buys an error path you must design — rollback plus a visible “couldn’t save” affordance — and it composes badly with many concurrent mutations on the same entity (the snapshot of mutation B may capture mutation A’s unconfirmed guess; TanStack Query’s docs route heavy cases through per-mutation variables or single-flight mutations instead).

Beyond a single list: dependencies, pages, and pushed truth

Once you have the single-list patterns down, ask yourself: where does the data graph get more complex? Dependent queries, pagination, and real-time push each break one of the assumptions above — and each has its own failure cost that doesn’t show up until traffic or page count grows.

Dependent queries chain with enabled: useQuery({ queryKey: ['projects', user?.id], enabled: !!user }) keeps the second query idle until the first resolves. This is the deliberate version of last lesson’s waterfall — fine when the dependency is real, but every enabled chain is serialized latency you chose, so audit chains the way you audit await sequences. Infinite queries make invalidation expensive in a way that surprises: an invalidated useInfiniteQuery refetches every loaded page sequentially to keep cursors consistent — a user 10 pages deep triggers 10 serial requests per invalidation. Mitigations: cap retained pages with maxPages, prefer targeted setQueryData page-patching for single-row edits, and use placeholderData: keepPreviousData on ordinary paginated queries so page flips show the old page instead of a spinner. Websocket-driven sync is the endgame for multi-user staleness, and the senior pattern is unintuitive: on a push event, do not write the payload into the cache — call invalidateQueries with the event’s entity key. Pushed payloads arrive out of order, may omit server-computed fields, and duplicate your write-through logic; using events as “something changed, ask the server” signals keeps one source of truth, and at high event rates you debounce invalidations per key — collapsing 50 events/second into at most a few refetches — which is exactly the storm-throttling that ticket two needed.