References — fw-09 A Server-State Query Cache
Primary sources first. Read the real implementation after you have written yours, never before.
The libraries
- TanStack Query source — read
queryCache.ts,query.tsandretryer.ts. Thequery-corepackage is framework-agnostic and is the reference implementation of this whole problem. - SWR — a much smaller take on the same idea; useful contrast
- Apollo Client cache — normalised caching, which TanStack Query deliberately does not do
- RTK Query — the same problem solved inside a Redux store
The concepts that actually matter
- stale-while-revalidate (RFC 5861) — the HTTP header the UX pattern is named after
- HTTP caching (RFC 9111) — freshness, validation,
ETag. A query cache is a second cache layer with its own vocabulary for the same ideas; knowing both prevents confusion. AbortController— cancellation, and why it is the only fix that is safe when a request has a server-side effect- Idempotency keys — the server-side half of retry safety
The bug this module exists to prevent
"Stale response overwrites newer data" — completion order is not issue order. Three fixes (cancellation, sequence numbers, render-time guards) all "work" for a read and are not equivalent when the request mutates. Set up and measured in fe-01's failure lab (sibling project).
Related modules
- fe-01 — Execution model (sibling project) — async ordering, and the F2 race lab
- fe-02 — Memory & leaks (sibling project) — a cache without an eviction policy is a leak; measured at 38 MB
- fw-08 — Router — route-level data loading
- fe-16/fe-17/fe-18 (planned) — server state, races, and API integration as distributed systems
When a claim here proves stale, record it in PROGRESS.md section 7.