Deterministic TanStack Query v5 Offline Mutation Queuing and Optimistic Rollback

--- description: Deterministic TanStack Query v5 Offline Mutation Queuing and Optimistic Rollback - Enforces strict mutation context snapshotting, deterministic rollback chains, and queue-aware cache invalidations in TanStack Query v5 during offline replay. Prevents client-state tearing and phantom cache overwrites when synchronizing persisted mutation queues against eventually consistent backend services. Ensures optimistic updates preserve immutable snapshots and cancel in-flight queries before mutating the QueryClient cache. globs: src/**/*.{ts,tsx}, app/**/*.{ts,tsx}, lib/api/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tanstack-query-v5-offline-mutation-optimistic-rollback-standard" --- # Deterministic TanStack Query v5 Offline Mutation Queuing and Optimistic Rollback > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unbounded Optimistic Cache Mutation without In-Flight Query Cancellation or Immutable Snapshot Rollback ## System Constraints You are a Principal Frontend Architect enforcing deterministic offline mutation management and optimistic state reconciliations using TanStack Query v5. Every mutation that updates the UI optimistically or resumes from an offline state must systematically cancel overlapping queries, take immutable snapshots of previous state, strictly restore snapshots inside onError, and sequence refetches inside onSettled rather than prematurely overwriting the cache. ## Strict Guidelines - Engineers MUST ALWAYS await queryClient.cancelQueries({ queryKey }) within onMutate before reading or writing optimistic cache states to prevent race conditions from concurrent network fetches. - Engineers MUST ALWAYS return an immutable snapshot object containing previous cache entries from onMutate to serve as the context contract for onError rollbacks. - Engineers MUST ALWAYS restore the snapshot directly using queryClient.setQueryData(queryKey, context.previousData) within the mutation onError handler instead of relying solely on refetches. - Engineers MUST NOT rely on synchronous mutation returns or unhandled promises within onMutate; onMutate MUST be an async function returning the rollback context. - Engineers MUST ALWAYS specify a unique scope.id or deterministic mutationKey when mutations must be executed sequentially during offline queue draining to avoid out-of-order race conditions. - Code SHOULD invalidate affected queries strictly inside onSettled rather than onSuccess to guarantee eventual consistency across both failure rollback and success pathways. - Components NEVER directly mutate local component state to simulate offline progress; all optimistic changes must flow through the central QueryClient cache via setQueryData with explicit rollbacks. ## Bad vs Good Implementations ### Naive Optimistic Mutation Causing Cache Tearing and Lost Rollback Context #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: This implementation fails to await queryClient.cancelQueries, meaning any in-flight GET request will resolve and clobber the optimistic state. Furthermore, it does not record a snapshot of the prior cache state in onMutate, making deterministic rollback impossible when the mutation fails or the device is offline and rejects upon replay. ```typescript import { useMutation, useQueryClient } from '@tanstack/react-query'; interface Todo { id: string; title: string; completed: boolean; } export function useUpdateTodo() { const queryClient = useQueryClient(); return useMutation({ mutationFn: async (updatedTodo: Todo) => { const res = await fetch(`/api/todos/${updatedTodo.id}`, { method: 'PUT', body: JSON.stringify(updatedTodo), }); return res.json(); }, // VIOLATION: cancelQueries not awaited; previous state not captured; // concurrent fetches can overwrite optimistic update; no rollback on error. onMutate: (newTodo) => { queryClient.setQueryData(['todos'], (old: Todo[] | undefined) => old ? old.map((t) => (t.id === newTodo.id ? newTodo : t)) : [] ); }, onError: (err) => { // VIOLATION: Silent error, leaves phantom optimistic state in cache console.error('Update failed:', err); }, }); } ``` #### Production Standard (Correct) > **Standard**: Awaits query cancellation to eliminate race conditions, snapshots the cache before mutation, returns typed context for deterministic rollback in onError, invalidates in onSettled to synchronize eventual backend consistency, and specifies networkMode: 'offlineFirst' for safe queued execution. ```typescript import { useMutation, useQueryClient } from '@tanstack/react-query'; interface Todo { id: string; title: string; completed: boolean; } interface MutationContext { previousTodos: Todo[] | undefined; } export const todosQueryKey = ['todos'] as const; export function useUpdateTodo() { const queryClient = useQueryClient(); return useMutation<Todo, Error, Todo, MutationContext>({ mutationKey: ['todos', 'update'], mutationFn: async (updatedTodo: Todo) => { const res = await fetch(`/api/todos/${updatedTodo.id}`, { method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(updatedTodo), }); if (!res.ok) { throw new Error(`Failed to update todo: ${res.statusText}`); } return res.json(); }, onMutate: async (newTodo): Promise<MutationContext> => { // 1. Cancel in-flight queries to prevent overwriting optimistic state await queryClient.cancelQueries({ queryKey: todosQueryKey }); // 2. Snapshot current cache state for rollback guarantee const previousTodos = queryClient.getQueryData<Todo[]>(todosQueryKey); // 3. Apply optimistic update immutably queryClient.setQueryData<Todo[]>(todosQueryKey, (old) => old ? old.map((t) => (t.id === newTodo.id ? newTodo : t)) : [newTodo] ); return { previousTodos }; }, onError: (_err, _newTodo, context) => { // 4. Deterministically rollback to captured snapshot if available if (context?.previousTodos !== undefined) { queryClient.setQueryData(todosQueryKey, context.previousTodos); } }, onSettled: async () => { // 5. Invalidate on settled to reconcile with eventual backend state await queryClient.invalidateQueries({ queryKey: todosQueryKey }); }, networkMode: 'offlineFirst', }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Deterministic TanStack Query v5 Offline Mutation Queuing and Optimistic Rollback

Deterministic TanStack Query v5 Offline Mutation Queuing and Optimistic Rollback defines an industrial-grade behavioral standard for frontend engineering. Enforces strict mutation context snapshotting, deterministic rollback chains, and queue-aware cache invalidations in TanStack Query v5 during offline replay. Prevents client-state tearing and phantom cache overwrites when synchronizing persisted mutation queues against eventually consistent backend services. Ensures optimistic updates preserve immutable snapshots and cancel in-flight queries before mutating the QueryClient cache. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Unbounded Optimistic Cache Mutation without In-Flight Query Cancellation or Immutable Snapshot Rollback Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Unbounded Optimistic Cache Mutation without In-Flight Query Cancellation or Immutable Snapshot Rollback	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS await queryClient.cancelQueries({ queryKey }) within onMutate before reading or writing optimistic cache states to prevent race conditions from concurrent network fetches.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.