const [data, setData] = useState(null);
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);

Which server value did this component observe?
When was it observed?
Is it still fresh enough?
Who else can mutate it?
Which cached projections are affected by this mutation?
Can the same request complete out of order?
Can the user perform the command twice?
Can another tab mutate the same entity?
Can stale permissions leak an illegal action?
Can optimistic UI lie longer than allowed?
Can pagination drift under concurrent writes?
Can hydration show a different truth than the client cache?

A React component should never pretend cached server data is locally owned state.

Case detail page: status = APPROVED
Case list page: status = PENDING
Dashboard count: pending = 18, should be 17

await approveCase(caseId);
queryClient.invalidateQueries({ queryKey: ['case', caseId] });

['cases', 'list', filters]
['dashboard', 'case-counts']
['case-history', caseId]
['assignee-workload', assigneeId]
['notifications']

const caseMutationImpact = {
  approve: (caseId: CaseId) => [
    caseKeys.detail(caseId),
    caseKeys.lists(),
    dashboardKeys.caseCounts(),
    auditKeys.caseHistory(caseId),
  ],
};

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

  return useMutation({
    mutationFn: approveCase,
    onSuccess: (_, variables) => {
      for (const key of caseMutationImpact.approve(variables.caseId)) {
        queryClient.invalidateQueries({ queryKey: key });
      }
    },
  });
}

Which entity changed?
Which list projections include that entity?
Which aggregate counts include it?
Which permission/action snapshots depend on it?
Which related entity projections should refresh?
Which route loaders or server-rendered pages cache it?

useQuery({
  queryKey: ['cases'],
  queryFn: () => searchCases({ status, assigneeId, page }),
});

useQuery({
  queryKey: ['cases', 'search', { status, assigneeId, page }],
  queryFn: () => searchCases({ status, assigneeId, page }),
});

export const caseKeys = {
  all: ['cases'] as const,
  detail: (caseId: string) => [...caseKeys.all, 'detail', caseId] as const,
  search: (params: CaseSearchParams) =>
    [...caseKeys.all, 'search', canonicalizeCaseSearchParams(params)] as const,
};

tenantId
locale
timezone
current organization
permission scope
feature flag affecting projection
API version
currency
sort field
sort direction
page/cursor
search text after normalization
include/exclude fields

Screen A loaded data with parameter X.
Screen B asks for parameter Y.
Screen B briefly or permanently shows X.

User typed: "compliance"
Response for "com" arrives after response for "compliance"
UI shows results for "com"

useEffect(() => {
  setLoading(true);

  fetchCases(searchText).then((result) => {
    setData(result);
    setLoading(false);
  });
}, [searchText]);

useEffect(() => {
  let ignore = false;

  async function run() {
    setLoading(true);
    const result = await fetchCases(searchText);

    if (!ignore) {
      setData(result);
      setLoading(false);
    }
  }

  run();

  return () => {
    ignore = true;
  };
}, [searchText]);

useEffect(() => {
  const controller = new AbortController();

  async function run() {
    setLoading(true);

    try {
      const result = await fetchCases(searchText, {
        signal: controller.signal,
      });
      setData(result);
    } catch (error) {
      if (!controller.signal.aborted) {
        setError(error);
      }
    } finally {
      if (!controller.signal.aborted) {
        setLoading(false);
      }
    }
  }

  run();

  return () => controller.abort();
}, [searchText]);

useQuery({
  queryKey: caseKeys.search({ searchText }),
  queryFn: ({ signal }) => fetchCases({ searchText, signal }),
});

Request identity must match state identity.

10:00 User A opens case note version 3
10:01 User B opens case note version 3
10:02 User A saves version 4
10:03 User B saves based on version 3
10:03 Server accepts B, A's edit disappears

await saveNote({ id, body });

await saveNote({
  id,
  body,
  expectedVersion: note.version,
});

if currentVersion !== expectedVersion:
  return 409 Conflict with current server value
else:
  save and increment version

type SaveNoteResult =
  | { type: 'saved'; note: Note }
  | { type: 'conflict'; serverNote: Note; attemptedBody: string };

if (result.type === 'conflict') {
  openConflictResolutionDialog({
    serverNote: result.serverNote,
    attemptedBody: result.attemptedBody,
  });
}

version number
ETag / If-Match
updatedAt precondition
idempotency key
operation token
server-side merge policy

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

double tap before disabled renders
browser retry
network retry
user opens another tab
mobile reconnect replay
back button resubmission
server timeout after successful write

const commandId = crypto.randomUUID();

await createCase({
  commandId,
  payload,
});

Same commandId + same actor + same operation = same result, not duplicate effect.

const createCaseMutation = useMutation({
  mutationFn: createCase,
  scope: { id: 'create-case' },
});

Disable button is UX.
Idempotency is correctness.

onMutate: ({ caseId }) => {
  queryClient.setQueryData(caseKeys.detail(caseId), old => ({
    ...old,
    status: 'APPROVED',
  }));
}

useMutation({
  mutationFn: approveCase,
  onMutate: async ({ caseId }) => {
    await queryClient.cancelQueries({ queryKey: caseKeys.detail(caseId) });

    const previous = queryClient.getQueryData(caseKeys.detail(caseId));

    queryClient.setQueryData(caseKeys.detail(caseId), (old: Case | undefined) => {
      if (!old) return old;
      return { ...old, status: 'APPROVING' };
    });

    return { previous };
  },
  onError: (_error, { caseId }, context) => {
    queryClient.setQueryData(caseKeys.detail(caseId), context?.previous);
  },
  onSuccess: (serverCase) => {
    queryClient.setQueryData(caseKeys.detail(serverCase.id), serverCase);
  },
  onSettled: (_data, _error, { caseId }) => {
    queryClient.invalidateQueries({ queryKey: caseKeys.detail(caseId) });
  },
});

setEntireCaseList(optimisticCaseList);

Optimistically patch the smallest safe projection.
Invalidate projections whose recalculation depends on server-only rules.

onSuccess: (serverResult) => {
  queryClient.setQueryData(caseKeys.detail(serverResult.id), serverResult);
}

status label
computed SLA
assigned queue
normalized name
server timestamp
audit metadata
permission-dependent actions

Optimistic UI is acceptable only when rollback, reconciliation, and conflict policy are explicit.

queryClient.invalidateQueries();

network storms
loading flicker
lost scroll position
wasted server CPU
hard-to-debug refetch cascades
janky transitions
poor offline behavior

const impact = {
  updateCaseAssignee: ({ caseId, oldAssigneeId, newAssigneeId }) => [
    caseKeys.detail(caseId),
    caseKeys.lists(),
    workloadKeys.assignee(oldAssigneeId),
    workloadKeys.assignee(newAssigneeId),
  ],
};

Detail: priority = HIGH
List row: priority = MEDIUM
Dashboard: high priority count unchanged

Entity detail projection != list row projection != dashboard aggregate projection

const caseKeys = {
  all: ['cases'] as const,
  detail: (id: string) => [...caseKeys.all, 'detail', id] as const,
  list: (params: CaseListParams) => [...caseKeys.all, 'list', params] as const,
  counts: (scope: CaseScope) => [...caseKeys.all, 'counts', scope] as const,
};

queryClient.setQueryData(caseKeys.detail(caseId), serverCase);
queryClient.invalidateQueries({ queryKey: caseKeys.listPrefix() });
queryClient.invalidateQueries({ queryKey: caseKeys.countsPrefix() });

Do not attempt to locally resort every list unless the sort/filter rule is fully client-known.
Invalidate the list family.

Prefer invalidation or server-pushed update.
Avoid optimistic aggregate arithmetic unless the rule is trivial and isolated.

Page 1: A B C D E
New item X inserted at top
Page 2 request offset=5 returns E F G H I
User sees duplicate E or misses one item

Give me items after cursor=D

const pendingItems = usePendingCreatedCases();

return (
  <CaseList
    pendingItems={pendingItems}
    pages={data.pages}
  />
);

If the backend owns ordering, the frontend should not pretend to own final pagination placement.

const { data: permissions } = useQuery({
  queryKey: ['permissions'],
  queryFn: getPermissions,
  staleTime: Infinity,
});

role changes
case assignment changes
workflow status changes
organization switching
policy changes
feature entitlement changes
license expiration

const permissionKeys = {
  caseActions: (caseId: string, actorId: string) =>
    ['permissions', 'case-actions', caseId, actorId] as const,
};

onSuccess: (_, { caseId }) => {
  queryClient.invalidateQueries({ queryKey: caseKeys.detail(caseId) });
  queryClient.invalidateQueries({ queryKey: permissionKeys.caseActions(caseId, actorId) });
}

Frontend permission state is UX guidance.
Backend authorization is enforcement.

Something went wrong.

type CommandError =
  | { type: 'validation'; fieldErrors: Record<string, string> }
  | { type: 'forbidden'; reason: string }
  | { type: 'conflict'; current: Case }
  | { type: 'not-found' }
  | { type: 'network'; retryable: boolean }
  | { type: 'unexpected'; traceId?: string };

If the user can respond differently, the error deserves a different state.

GET queries
idempotent commands
network timeout
temporary 503
rate-limit with retry-after policy

non-idempotent create command
payment/charging command
irreversible destructive command
approval/escalation command without command id
mutation with side effects but no idempotency key

Queries can often retry.
Mutations should retry only when the command contract is idempotent or explicitly replay-safe.

server and client use different query keys
query client singleton shared across requests
server data not dehydrated into client
client auth/session differs from server request
staleTime too low for hydration use case
clock/timezone-based data differs
random/default values differ

function createRequestQueryClient() {
  return new QueryClient();
}

The query key used to prefetch on the server must equal the query key used by the client component.

// server
prefetchQuery({ queryKey: ['case', id], queryFn: ... })

// client
useQuery({ queryKey: ['cases', 'detail', id], queryFn: ... })

SSR server state is not HTML decoration. It is a cache seed with identity, freshness, and request scope.

old data shown after logout
tenant A data visible after tenant switch
stale permission cache restores illegal actions
schema changes break cached records
persisted cache survives role change
sensitive data written to localStorage
cache garbage collection discards persisted data earlier than expected

max age
schema version
auth/session scope
tenant scope
sensitive-data exclusion
logout cleanup
migration/drop policy
rehydration loading policy

const cacheScope = {
  schemaVersion: 3,
  tenantId,
  actorId,
};

Persistence extends the lifetime of bugs and data exposure.
Only persist cache entries whose lifecycle and sensitivity are explicit.

const channel = new BroadcastChannel('server-state-events');

export function publishCaseChanged(caseId: string) {
  channel.postMessage({ type: 'case.changed', caseId });
}

export function subscribeToServerStateEvents(onEvent: (event: unknown) => void) {
  channel.addEventListener('message', (event) => onEvent(event.data));
}

useEffect(() => {
  return subscribeToServerStateEvents((event) => {
    if (event.type === 'case.changed') {
      queryClient.invalidateQueries({ queryKey: caseKeys.detail(event.caseId) });
      queryClient.invalidateQueries({ queryKey: caseKeys.lists() });
    }
  });
}, [queryClient]);

Multi-tab freshness is a distributed systems problem in miniature.
Use invalidation signals and write preconditions, not hope.

Can this command be safely replayed?
Does it need idempotency key?
Can it expire?
What if permissions change before reconnect?
What if the target entity is deleted?
What order must queued commands preserve?
Can the user inspect/cancel pending commands?

type PendingCommand = {
  commandId: string;
  type: 'case.comment.add';
  payload: AddCommentPayload;
  createdAt: string;
  status: 'queued' | 'sending' | 'failed' | 'confirmed';
};

Saved locally
Waiting for connection
Sending
Server rejected
Conflict detected
Confirmed

Offline support is not a fetch option. It is a command queue and reconciliation design.

query_started key duration scope
query_failed key error_type retry_count
mutation_started command_id mutation_key entity_id
mutation_optimistic_applied command_id affected_keys
mutation_failed command_id error_type rollback_applied
mutation_success command_id affected_keys invalidated_keys
cache_invalidated reason keys
hydration_cache_miss query_key route

type CommandMeta = {
  commandId: string;
  clientRequestId: string;
  route: string;
};

What query key produced this value?
When was it fetched?
Was it fresh or stale?
Which mutation should have invalidated it?
Did invalidation happen?
Did refetch happen?
Did refetch fail?
Was an optimistic patch applied?
Was rollback applied?
Was another tab involved?
Did SSR seed this cache entry?

A production cache needs an audit trail of why it changed, not just what value it currently holds.

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

  await approveCaseMutation.onSuccess(undefined, { caseId: 'case-1' }, undefined);

  expect(invalidateSpy).toHaveBeenCalledWith({
    queryKey: caseKeys.detail('case-1'),
  });
  expect(invalidateSpy).toHaveBeenCalledWith({
    queryKey: caseKeys.lists(),
  });
  expect(invalidateSpy).toHaveBeenCalledWith({
    queryKey: dashboardKeys.caseCounts(),
  });
});

it('rolls back optimistic status when approval fails', async () => {
  const queryClient = createTestQueryClient();
  queryClient.setQueryData(caseKeys.detail('case-1'), {
    id: 'case-1',
    status: 'PENDING',
  });

  const context = await mutationOptions.onMutate?.({ caseId: 'case-1' });

  expect(queryClient.getQueryData(caseKeys.detail('case-1'))).toMatchObject({
    status: 'APPROVING',
  });

  mutationOptions.onError?.(new Error('Forbidden'), { caseId: 'case-1' }, context);

  expect(queryClient.getQueryData(caseKeys.detail('case-1'))).toMatchObject({
    status: 'PENDING',
  });
});

[ ] Every query has a complete key factory.
[ ] Query keys include tenant/session/locale/scope when they affect data.
[ ] Every mutation has an impact map.
[ ] Optimistic updates have rollback and reconciliation.
[ ] Commands that create durable side effects have idempotency keys.
[ ] Commands that overwrite durable state have version/precondition handling.
[ ] Error states distinguish validation, forbidden, conflict, not found, network, and unexpected errors.
[ ] Pagination uses stable cursor strategy when concurrent writes matter.
[ ] Permission/action projections are invalidated after workflow transitions.
[ ] SSR prefetch and client usage share the same query key factory.
[ ] Persisted cache is scoped by schema/session/tenant and cleared on logout.
[ ] Multi-tab behavior is explicitly handled or consciously accepted.
[ ] Query/mutation events are observable in development and production diagnostics.

useEffect(() => {
  let ignore = false;

  fetchCase(caseId).then((data) => {
    if (!ignore) setCase(data);
  });

  return () => {
    ignore = true;
  };
}, [caseId]);

function useCase(caseId: string) {
  return useQuery({
    queryKey: caseKeys.detail(caseId),
    queryFn: ({ signal }) => fetchCase(caseId, { signal }),
  });
}

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

onSuccess: (_, variables) => {
  for (const key of getApproveCaseImpact(variables.caseId)) {
    queryClient.invalidateQueries({ queryKey: key });
  }
}

catch {
  toast.error('Something went wrong');
}

switch (error.type) {
  case 'validation':
    form.setErrors(error.fieldErrors);
    break;
  case 'conflict':
    openConflictDialog(error.current);
    break;
  case 'forbidden':
    showForbiddenNotice(error.reason);
    break;
  default:
    reportUnexpectedError(error);
}

How do I fetch this endpoint?

What is the identity of this projection?
Who owns the truth?
How fresh must it be?
Which command changes it?
Which projections become stale?
Can the command be duplicated?
Can the update conflict?
Can optimistic UI be rolled back?
Can hydration seed the same key?
Can another tab or user invalidate this view?
What evidence will I have when this breaks in production?