Mutations and Targeted Invalidation

Mutations and Targeted Invalidation Create and update remote state without manual refresh choreography

Phase 22 - TanStack Query Volume 06 - Professional Frontend

Writes belong in mutations
export function useCreateTask() {
const queryClient = useQueryClient();

return useMutation({
mutationFn: createTask,
onSuccess: async () => {
await queryClient.invalidateQueries({
queryKey: taskKeys.lists(),
});
},
});
}

A successful create means cached Task lists may now be stale. We do not need to manually discover every rendered list and call refetch on it. We invalidate the relevant key family.

Update mutation
export function useUpdateTask(taskId: string) {
const queryClient = useQueryClient();

return useMutation({ mutationFn: (input: UpdateTaskInput) => updateTask(taskId, input), onSuccess: async (saved) => { queryClient.setQueryData(taskKeys.detail(taskId), saved); await queryClient.invalidateQueries({ queryKey: taskKeys.lists() }); }, }); }

Why invalidate instead of patching every list manually? TaskFlow lists can differ by status, priority, search, sort and page. A status update can move a record out of one list and into another. Manual patching is possible, but it is easy to create subtle cache inconsistencies. Phase 22 starts with targeted invalidation. Optimistic cache manipulation is intentionally deferred to Phase 25.

Mutation retry Mutations default to zero retries, which is safer for writes because a retry can repeat a side effect unless the operation is known to be idempotent. TaskFlow keeps retry disabled until an operation explicitly earns it.

Await invalidation when the UX depends on fresh data

If onSuccess returns the invalidateQueries promise, the mutation remains pending until the related active queries have finished invalidation/refetch work. This can make “Save -> return to refreshed list” deterministic.

Invalidation matrix Mutation Detail cache List caches

Create Task Usually no existing detail key Invalidate Task lists

Update Task Set saved Task into its detail key Invalidate lists because filters/sort membership may change

Delete Task Remove or invalidate detail Invalidate lists

Status transition Refresh detail if viewed Invalidate lists; record may enter or leave filtered pages

This is deliberately conservative. Phase 25 can optimize perceived latency with optimistic updates after rollback and concurrency hazards are understood.