Cache Behaviour — Staleness, Refetching and Invalidation

// Structure keys from general to specific
['problems']                                  // everything problems-related
['problems', 'list', { topic, page }]         // one list
['problems', 'detail', slug]                  // one item

// Then invalidation can be as broad or narrow as the write requires
queryClient.invalidateQueries({ queryKey: ['problems'] })            // all
queryClient.invalidateQueries({ queryKey: ['problems', 'list'] })    // lists only
queryClient.invalidateQueries({ queryKey: ['problems', 'detail', slug] })

// A key factory keeps them consistent and typo-proof
export const problemKeys = {
  all: ['problems'],
  lists: () => [...problemKeys.all, 'list'],
  list: (filters) => [...problemKeys.lists(), filters],
  details: () => [...problemKeys.all, 'detail'],
  detail: (slug) => [...problemKeys.details(), slug],
}

// The bug this prevents: one file uses ['problem', slug] and another
// uses ['problems', slug], so the invalidation silently misses.

// A STALE query refetches when:
//   - a component using it mounts
//   - the window regains focus          (refetchOnWindowFocus, default on)
//   - the network reconnects            (refetchOnReconnect, default on)
//   - refetchInterval fires             (off by default)
//   - you invalidate it

// A FRESH query does none of these. staleTime is the only control.

// Choosing staleTime by how the data behaves:
//   a published article       Infinity or hours   — it barely changes
//   a problem list            5 minutes
//   the user's own progress   30 seconds
//   a live leaderboard        refetchInterval: 10_000

// Window focus refetching is excellent for dashboards and confusing
// for forms — the user tabs away, comes back, and the screen shifts.
// Turn it off where the page holds an in-progress edit.

// Manual reads and writes, when you need them
queryClient.getQueryData(problemKeys.detail(slug))
queryClient.setQueryData(problemKeys.detail(slug), updated)   // seed the cache

// 1. Key too coarse — different data sharing one entry
useQuery({ queryKey: ['problems'], queryFn: () => list({ topic }) })
// Switching topic shows the previous topic's rows, because the key
// did not change. Fix: put every input in the key.

// 2. Missing invalidation — a write nobody told the cache about
await deleteSubmission(id)
// the submissions list still shows it until a reload.
// Fix: invalidate every affected key in onSuccess. Write them down
// as part of the mutation, not later.

// A useful discipline: for each mutation, write a one-line comment
// listing what it invalidates. Reviewers can then check it.

// Seeding detail from a list avoids a spinner on navigation:
onSuccess: (rows) => {
  rows.forEach(r => queryClient.setQueryData(problemKeys.detail(r.slug), r))
}
// The detail page then renders instantly and refetches in the
// background for the fields the list did not carry.