Optimistic Updates

# Optimistic Update Decision Table

| Operation | Course decision | Why |
|---|---|---|
| Task status toggle | Optimistic | Small, reversible, predictable result |
| Task title edit | Usually optimistic | Predictable, but preserve server validation errors |
| Create Task | UI optimism first | Avoid inventing fake permanent IDs |
| Delete Task | Usually pessimistic initially | Destructive; accidental false success is costly |
| Membership role change | Pessimistic | Security-sensitive authorization operation |
| Payroll finalization | Pessimistic | High-impact irreversible business workflow |
| Purchase-order approval | Usually pessimistic | Approval rules may fail and user should not see false completion |

# TaskFlow Phase 25 - Optimistic Updates Snapshot

This snapshot extends the Phase 22 TanStack Query architecture. It intentionally demonstrates two strategies:

1. UI optimism through mutation variables (preferred when one view needs the prediction).
2. Cache optimism through onMutate + rollback (used when several observers share the same Task detail cache).

The server remains authoritative. Task list caches are invalidated after settlement rather than attempting to reproduce every filter/pagination rule in client code.

# Sources

- https://tanstack.com/query/latest/docs/framework/react/guides/optimistic-updates
- https://tanstack.com/query/latest/docs/framework/react/guides/query-cancellation
- https://tanstack.com/query/latest/docs/framework/react/guides/invalidations-from-mutations
- https://tanstack.com/query/latest/docs/framework/react/guides/mutations
- https://tanstack.com/query/latest/docs/framework/react/reference/functions/useMutationState
- https://tanstack.com/query/latest/docs/reference/QueryClient

"use client";

import { usePendingTaskCreates } from "@/hooks/use-create-task-pending";

export function PendingTaskRows() {
  const pending = usePendingTaskCreates();

  return pending.map(item => (
    <tr key={item.submittedAt} aria-busy="true">
      <td>{item.input.title}</td>
      <td>Pending creation</td>
      <td>{item.input.priority ?? "MEDIUM"}</td>
    </tr>
  ));
}

"use client";

import { useTaskStatusOptimistic } from "@/hooks/use-task-status-optimistic";
import type { TaskStatus } from "@/lib/api/task-types";

type Props = {
  taskId: string;
  status: TaskStatus;
};

export function TaskStatusButton({ taskId, status }: Props) {
  const mutation = useTaskStatusOptimistic(taskId);

  const visibleStatus = mutation.isPending
    ? mutation.variables
    : status;

  const nextStatus: TaskStatus =
    visibleStatus === "DONE" ? "IN_PROGRESS" : "DONE";

"use client";

import { useIsMutating } from "@tanstack/react-query";

export function TaskSavingIndicator() {
  const count = useIsMutating({ mutationKey: ["tasks", "mutation"] });

  if (count === 0) return null;

  return (
    <span role="status" aria-live="polite">
      Saving {count === 1 ? "change" : `${count} changes`}...
    </span>
  );
}

"use client";

import { useMutation, useMutationState } from "@tanstack/react-query";
import { createTask } from "@/lib/api/task-mutations";
import { taskKeys } from "@/lib/query/task-keys";
import { taskMutationKeys } from "@/lib/query/task-mutation-keys";
import type { CreateTaskInput } from "@repo/validators/tasks";

export function useCreateTask() {
  return useMutation({
    mutationKey: taskMutationKeys.create(),
    mutationFn: createTask,
    onSettled: async (_data, _error, _variables, _result, context) => {
      await context.client.invalidateQueries({
        queryKey: taskKeys.lists(),
      });
    },
  });
}

"use client";

import { useMutation } from "@tanstack/react-query";
import { taskKeys } from "@/lib/query/task-keys";
import { taskMutationKeys } from "@/lib/query/task-mutation-keys";
import { updateTask } from "@/lib/api/task-mutations";
import type { Task, TaskStatus } from "@/lib/api/task-types";

export function useTaskStatusOptimistic(taskId: string) {
  return useMutation({
    mutationKey: taskMutationKeys.updateStatus(taskId),
    scope: { id: `task-status:${taskId}` },

    mutationFn: (status: TaskStatus) =>
      updateTask(taskId, { status }),

    onMutate: async (status, context) => {
      const key = taskKeys.detail(taskId);

      await context.client.cancelQueries({ queryKey: key });

export const taskMutationKeys = {
  all: ["tasks", "mutation"] as const,
  create: () => [...taskMutationKeys.all, "create"] as const,
  updateStatus: (taskId: string) =>
    [...taskMutationKeys.all, "status", taskId] as const,
};

# Phase 25 Optimistic Update Test Matrix

| Scenario | Expected result |
|---|---|
| Status mutation starts | Predicted status appears immediately |
| Detail query is refetching | cancelQueries prevents stale response from overwriting prediction |
| Server accepts status | Detail cache uses server Task; lists invalidate |
| Server returns 403 | Previous Task detail is restored; permission error shown |
| Server returns 409 | Previous Task detail is restored; conflict explained |
| Network fails | Previous Task detail is restored; retry remains possible |
| Two changes same Task | Same scope serializes requests in intent order |
| Two changes different Tasks | Requests can run independently |
| Create Task pending | Temporary UI row uses mutation variables + submittedAt |
| Create succeeds | Pending row disappears after list refetch returns server Task |
| Status-filtered list | List is reconciled by invalidation/refetch rather than fabricated client metadata |
| Logout while mutations exist | Existing Phase 22 logout clears QueryClient cache |