What changed?
Who owns the truth?
What local UI should change immediately?
What cache entries are now suspicious?
What happens if the server rejects the command?
What happens if the user clicks twice?
What happens if another mutation against the same entity is already pending?
What does success mean: request accepted, write committed, or projection updated?

A mutation is an intent to change server-owned state.
The UI may predict the outcome, but it must not forget who owns the final truth.

onMutate is before network.
onSuccess is after successful response.
onError is after rejected response.
onSettled is always after success or error.

import { useMutation, useQueryClient } from '@tanstack/react-query';

type RenameProjectCommand = {
  projectId: string;
  name: string;
};

type Project = {
  id: string;
  name: string;
  updatedAt: string;
};

async function renameProject(command: RenameProjectCommand): Promise<Project> {
  const response = await fetch(`/api/projects/${command.projectId}/rename`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name: command.name }),
  });

  if (!response.ok) {
    throw new Error('Failed to rename project');
  }

  return response.json();
}

const projectKeys = {
  all: ['projects'] as const,
  detail: (projectId: string) => ['projects', 'detail', projectId] as const,
  lists: () => ['projects', 'list'] as const,
};

export function useRenameProject() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationKey: ['projects', 'rename'],
    mutationFn: renameProject,
    onSuccess: (project) => {
      queryClient.setQueryData(projectKeys.detail(project.id), project);
      queryClient.invalidateQueries({ queryKey: projectKeys.lists() });
    },
  });
}

function RenameProjectForm({ projectId }: { projectId: string }) {
  const renameProject = useRenameProject();
  const [name, setName] = React.useState('');

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        renameProject.mutate({ projectId, name });
      }}
    >
      <input value={name} onChange={(event) => setName(event.target.value)} />
      <button disabled={renameProject.isPending}>Save</button>
      {renameProject.isError ? <p>{renameProject.error.message}</p> : null}
    </form>
  );
}

updateProject.mutate({
  id,
  payload: formState,
});

renameProject.mutate({
  projectId,
  name: form.name.trim(),
});

renameProject.mutate({
  projectId,
  name: form.name.trim(),
  expectedVersion: project.version,
  clientRequestId: crypto.randomUUID(),
});

- a clear verb
- a domain target
- a minimal payload
- idempotency metadata when needed
- concurrency metadata when needed
- no raw component state leakage
- no arbitrary partial object unless the domain command is truly patch-like

export function useApproveCase() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationKey: ['cases', 'approve'],
    mutationFn: approveCase,
    onSuccess: (result, variables) => {
      queryClient.setQueryData(caseKeys.detail(variables.caseId), result.case);
      queryClient.invalidateQueries({ queryKey: caseKeys.timeline(variables.caseId) });
      queryClient.invalidateQueries({ queryKey: caseKeys.lists() });
    },
  });
}

function ApproveButton({ caseId, version }: Props) {
  const approveCase = useApproveCase();

  return (
    <button
      disabled={approveCase.isPending}
      onClick={() => {
        approveCase.mutate({
          caseId,
          expectedVersion: version,
          reason: 'Reviewed and valid',
        });
      }}
    >
      Approve
    </button>
  );
}

- view code expresses intent
- cache reconciliation is centralized
- invalidation policy is not duplicated
- optimistic update logic has one owner
- tests can focus on command semantics
- future backend shape changes do not rewrite every component

useMutation({
  mutationFn,
  onMutate: async (variables) => {
    // before network request
    // cancel conflicting reads
    // snapshot previous cache state
    // apply optimistic patch
    // return rollback context
  },
  onError: (error, variables, context) => {
    // rollback optimistic patch
    // surface recoverable error
  },
  onSuccess: (data, variables, context) => {
    // reconcile authoritative result
    // optionally set exact query data
  },
  onSettled: (data, error, variables, context) => {
    // invalidate related queries
    // cleanup temporary UI state
  },
});

onSuccess: () => {
  queryClient.invalidateQueries({ queryKey: projectKeys.lists() });
}

- many queries may be affected
- server computes derived fields
- permissions may change
- list ordering/filter membership may change
- mutation response is incomplete
- correctness matters more than saving one request

onSuccess: (project) => {
  queryClient.setQueryData(projectKeys.detail(project.id), project);
}

- mutation response contains authoritative entity
- affected cache address is exact
- update is cheap and deterministic
- you want instant detail-page consistency

onSuccess: (project) => {
  queryClient.setQueryData(projectKeys.detail(project.id), project);
  queryClient.invalidateQueries({ queryKey: projectKeys.lists() });
}

function TodoList() {
  const todos = useTodos();
  const createTodo = useCreateTodo();

  return (
    <ul>
      {todos.data?.map((todo) => <li key={todo.id}>{todo.text}</li>)}

      {createTodo.isPending ? (
        <li style={{ opacity: 0.5 }}>{createTodo.variables.text}</li>
      ) : null}
    </ul>
  );
}

- optimistic state is local to one component
- temporary row does not need to be globally visible
- rollback can be handled by simply not rendering pending variables
- you want lower cache complexity

export function useCreateTodo() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationKey: ['todos', 'create'],
    mutationFn: createTodo,
    onMutate: async (command) => {
      await queryClient.cancelQueries({ queryKey: todoKeys.list() });

      const previousTodos = queryClient.getQueryData<Todo[]>(todoKeys.list());
      const optimisticTodo: Todo = {
        id: `temp:${command.clientRequestId}`,
        text: command.text,
        status: 'pending',
      };

      queryClient.setQueryData<Todo[]>(todoKeys.list(), (old = []) => [
        optimisticTodo,
        ...old,
      ]);

      return { previousTodos, optimisticTodoId: optimisticTodo.id };
    },
    onError: (_error, _command, context) => {
      queryClient.setQueryData(todoKeys.list(), context?.previousTodos ?? []);
    },
    onSuccess: (createdTodo, _command, context) => {
      queryClient.setQueryData<Todo[]>(todoKeys.list(), (old = []) =>
        old.map((todo) =>
          todo.id === context?.optimisticTodoId ? createdTodo : todo,
        ),
      );
    },
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: todoKeys.list() });
    },
  });
}

- multiple components should see optimistic state
- list/detail UI must feel instant
- the optimistic state participates in selection/counts/badges
- you can define reliable rollback/reconciliation

return { oldData };

return {
  affectedKeys: [projectKeys.detail(projectId), projectKeys.lists()],
  previousProject,
  previousListPages,
  optimisticEntityId,
  startedAt: Date.now(),
};

- which cache entries were touched
- previous snapshots required to restore
- temporary IDs inserted into collections
- request/client IDs for matching success result
- whether rollback is safe or only invalidation is safe

Initial: false
Mutation A optimistic: true
Mutation B optimistic: false
A fails
Naive rollback to false might be okay by accident.
B succeeds

Initial: false
A optimistic: true
B optimistic: false
B succeeds
A fails later
Naive rollback from A restores false? okay.

- serial mutation scope
- entity-level command queue
- invalidation instead of manual rollback
- server version checks
- state machine workflow

PATCH project name -> "Alpha"
PATCH project name -> "Beta"
Responses arrive out of order.
The UI might show Alpha even though Beta was the last user intent.

function useRenameProject() {
  const queryClient = useQueryClient();
  const latestRequestIdRef = React.useRef<string | null>(null);

  return useMutation({
    mutationFn: renameProject,
    onMutate: (command) => {
      latestRequestIdRef.current = command.clientRequestId;
    },
    onSuccess: (project, command) => {
      if (latestRequestIdRef.current !== command.clientRequestId) {
        return;
      }

      queryClient.setQueryData(projectKeys.detail(project.id), project);
    },
  });
}

renameProject.mutate({
  projectId,
  name,
  expectedVersion: project.version,
});

useMutation({
  mutationFn: updateProject,
  scope: { id: `project:${projectId}` },
});

- operation order matters
- offline mutation queue must preserve order
- same entity cannot safely accept parallel writes
- duplicate command avoidance is more important than throughput

<button disabled={mutation.isPending}>Submit</button>

- double-click before disabled state renders
- retry after timeout
- browser refresh
- mobile network replay
- user opening two tabs

type CreateInvoiceCommand = {
  customerId: string;
  items: InvoiceItemInput[];
  clientRequestId: string;
};

If a mutation creates money, identity, workflow transition, or irreversible state,
include an idempotency key and expect the server to enforce it.

type ApiError =
  | { type: 'validation'; fields: Record<string, string> }
  | { type: 'conflict'; currentVersion: number; message: string }
  | { type: 'forbidden'; message: string }
  | { type: 'network'; message: string }
  | { type: 'unknown'; message: string };

function SaveProjectError({ error }: { error: ApiError }) {
  switch (error.type) {
    case 'validation':
      return <FieldErrors fields={error.fields} />;
    case 'conflict':
      return <ConflictBanner message={error.message} />;
    case 'forbidden':
      return <PermissionBanner message={error.message} />;
    case 'network':
      return <RetryBanner message={error.message} />;
    case 'unknown':
      return <GenericError message={error.message} />;
  }
}

useMutation({
  mutationFn: saveDraft,
  retry: 2,
  retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 30_000),
});

- idempotent PUT-like updates
- save draft with idempotency key
- background sync queue
- marking read when duplicate success is harmless

- payments
- irreversible workflow transitions
- one-time token consumption
- create operations without idempotency key
- external side effects such as sending email/SMS

Do not configure mutation retry until you can explain idempotency.

User approves case.
API returns 202 Accepted with commandId.
Workflow engine processes transition asynchronously.
Case detail updates later.
Timeline projection updates later.
List counters update later.

- show command accepted state
- invalidate or poll relevant queries
- optionally subscribe to workflow status
- avoid lying that final state is complete

onSuccess: () => navigate('/projects');

- destination list still stale
- user cannot see validation/concurrency warning
- success page assumes projection already updated
- navigation hides a failed background invalidation

onSuccess: async (project) => {
  queryClient.setQueryData(projectKeys.detail(project.id), project);
  await queryClient.invalidateQueries({ queryKey: projectKeys.lists() });
  navigate(`/projects/${project.id}`);
}

onSuccess: (result) => {
  if (result.status === 'accepted') {
    navigate(`/imports/${result.jobId}`);
    return;
  }

  navigate(`/projects/${result.project.id}`);
}

Draft phase    : user edits local state
Command phase  : user submits intent to server

- should draft reset after success?
- should field errors map back into local form state?
- should server result replace current form values?
- can submit happen while another submit is pending?
- should dirty state survive network failure?
- should optimistic UI be field-level or cache-level?

function ProjectSettingsForm({ project }: { project: Project }) {
  const [draft, setDraft] = React.useState(() => ({ name: project.name }));
  const save = useRenameProject();

  const dirty = draft.name !== project.name;

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        save.mutate(
          {
            projectId: project.id,
            name: draft.name,
            expectedVersion: project.version,
            clientRequestId: crypto.randomUUID(),
          },
          {
            onSuccess: (updatedProject) => {
              setDraft({ name: updatedProject.name });
            },
          },
        );
      }}
    >
      <input
        value={draft.name}
        onChange={(event) => setDraft({ name: event.target.value })}
      />
      <button disabled={!dirty || save.isPending}>Save</button>
    </form>
  );
}

- global upload progress
- background sync queue
- optimistic row inserted from modal into list
- notification badge for pending actions

import { useMutationState } from '@tanstack/react-query';

function PendingTodoCreates() {
  const pendingTodos = useMutationState({
    filters: {
      mutationKey: ['todos', 'create'],
      status: 'pending',
    },
    select: (mutation) => mutation.state.variables as CreateTodoCommand,
  });

  return pendingTodos.map((todo) => (
    <PendingTodoRow key={todo.clientRequestId} text={todo.text} />
  ));
}

onSuccess: (created) => {
  queryClient.setQueryData(projectKeys.detail(created.id), created);
  queryClient.invalidateQueries({ queryKey: projectKeys.lists() });
}

onSuccess: (updated) => {
  queryClient.setQueryData(projectKeys.detail(updated.id), updated);
  queryClient.invalidateQueries({ queryKey: projectKeys.lists() });
}

onSuccess: (_result, variables) => {
  queryClient.removeQueries({ queryKey: projectKeys.detail(variables.projectId) });
  queryClient.invalidateQueries({ queryKey: projectKeys.lists() });
}

onSuccess: () => {
  queryClient.invalidateQueries({ queryKey: boardKeys.columns(boardId) });
}

onSuccess: (result, variables) => {
  queryClient.setQueryData(caseKeys.detail(variables.caseId), result.case);
  queryClient.invalidateQueries({ queryKey: caseKeys.timeline(variables.caseId) });
  queryClient.invalidateQueries({ queryKey: caseKeys.lists() });
}

onSuccess: () => {
  queryClient.invalidateQueries({ queryKey: ['permissions'] });
  queryClient.invalidateQueries({ queryKey: ['navigation'] });
  queryClient.invalidateQueries({ queryKey: ['cases'] });
}

updateCase({ caseId, status: 'approved' });

approveCase({
  caseId,
  decisionReason,
  evidenceIds,
  expectedVersion,
  clientRequestId,
});

- audit trail should record business intent
- authorization can be checked per command
- validation differs per transition
- command idempotency matters
- conflict handling is explicit
- optimistic UI can represent "approval pending" not just status mutation

export function useApproveCase() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationKey: ['cases', 'approve'],
    mutationFn: approveCase,
    retry: false,
    onSuccess: (result, command) => {
      queryClient.setQueryData(caseKeys.detail(command.caseId), result.case);
      queryClient.invalidateQueries({ queryKey: caseKeys.timeline(command.caseId) });
      queryClient.invalidateQueries({ queryKey: caseKeys.availableActions(command.caseId) });
      queryClient.invalidateQueries({ queryKey: caseKeys.lists() });
    },
  });
}

Case detail changed.
Timeline changed.
Available actions changed.
Lists/counters may change.

it('submits approve command with expected version', async () => {
  render(<ApproveButton caseId="case-1" version={7} />);

  await user.click(screen.getByRole('button', { name: /approve/i }));

  expect(api.approveCase).toHaveBeenCalledWith({
    caseId: 'case-1',
    expectedVersion: 7,
    reason: expect.any(String),
    clientRequestId: expect.any(String),
  });
});

it('invalidates case timeline and lists after approval', async () => {
  const queryClient = createTestQueryClient();
  const invalidateSpy = vi.spyOn(queryClient, 'invalidateQueries');

  // render hook with QueryClientProvider
  // trigger mutation success

  expect(invalidateSpy).toHaveBeenCalledWith({ queryKey: caseKeys.timeline('case-1') });
  expect(invalidateSpy).toHaveBeenCalledWith({ queryKey: caseKeys.lists() });
});

it('rolls back optimistic todo when create fails', async () => {
  const queryClient = createTestQueryClient();
  queryClient.setQueryData(todoKeys.list(), []);

  server.rejectNextCreateTodo();

  // trigger mutation
  // assert temp todo appears
  // await failure
  // assert temp todo removed
});

- success response reconciles exact cache
- error rolls back or invalidates
- duplicate click does not create duplicate command
- conflict error keeps draft and shows resolution path
- optimistic item has stable temp ID
- list invalidation covers filtered lists
- mutation does not retry unsafe commands

Component calls mutation just to fetch data imperatively.

Use query with proper key and enabled condition.

Detail page updated but sidebar count/list remains stale.

Map mutation domain effects to query key families.

Filtered/paginated list contains entity that no longer belongs.

Patch exact detail; invalidate derived lists.

User sees committed state after server rejects command.

Use rollback context or invalidate after error.

Concurrent optimistic mutations overwrite each other.

Use entity-scoped serial mutation, request IDs, server versioning, or invalidate instead of manual snapshot rollback.

API returns partial payload, UI treats it as authoritative full entity.

Only set exact cache when response shape matches that cache contract.

Double click creates two invoices/orders/cases.

Disable pending UI, use client request ID, require backend idempotency.

Network retry repeats irreversible operation.

Disable retry unless idempotency is guaranteed.

User navigates away before cache reconciliation/error display.

Await critical invalidation or navigate to command status route.

Command
- What business intent does this mutation represent?
- Is the payload minimal and typed?
- Does it include idempotency/concurrency metadata when needed?

Lifecycle
- What happens while pending?
- What happens on validation error?
- What happens on conflict error?
- What happens on network failure?
- Is retry safe?

Cache
- Which detail queries are exact and can be updated directly?
- Which list/projection queries must be invalidated?
- Does permission/navigation/action availability need invalidation?
- Does optimistic update have rollback/reconciliation?

Concurrency
- Can two commands run at the same time?
- Does order matter?
- Do we need mutation scope?
- Does the server enforce version/idempotency?

UX
- Is duplicate submit prevented?
- Is draft preserved on failure?
- Is success shown only when true?
- Does navigation wait for required consistency?

Testing
- Are success/error/rollback/invalidation paths tested?
- Are duplicate/parallel cases tested if relevant?

Query = remote read dependency.
Mutation = remote write command.

- command intent
- pending UI
- validation/conflict/network error handling
- optimistic prediction
- cache reconciliation
- invalidation
- duplicate prevention
- concurrency policy
- navigation
- observability