For a client-side cache of server data keyed by the request, what does a stale entry mean and what does a reader get?

## Why server data needs a cache of its own A component tree holds two kinds of value that behave nothing alike. The first is **owned by the tree**: whether a panel is open, what the user has typed, which tab is selected. Nobody outside the tab can change it, so the copy in memory *is* the truth. The second is **owned by the server**: an order, a price, a list of teammates. There the tree holds a **copy that was correct at the instant the response arrived**, and it can be wrong a second later because somebody else changed the record. That difference is why server data is not kept the way ordinary state is kept. It is stored in a cache **keyed by what was asked** — the resource, the filters, the sort, the page, and the identity of the caller. The key matters as much as the value: two components that ask the same question land on the same entry instead of firing two requests and holding two copies that can disagree on the same screen. ## Fresh, stale, and the read policy Each entry records when its data arrived and is governed by a **staleness window**: how long the stored value is treated as good enough to serve without checking. - **fresh** — inside the window. The read is answered from memory; no request is made. - **stale** — past the window. The value is still *usable*, it is just no longer *trusted*. `stale` is therefore a claim about confidence, not about content. The entry is not empty, not deleted and not broken. What a read does with it is a policy choice: | read policy | what the reader sees first | requests per read | what it costs | |---|---|---|---| | refetch first, render nothing until it lands | a loading placeholder, every time | one, blocking | slowest screen; the content flickers away on every visit | | serve from memory only | the stored value, indefinitely | none | the user can act on a value that is hours old | | stale-while-revalidate | the stored value immediately | one, in the background | a short window where the previous value is on screen | Most component frameworks and the data layers built for them default to the third row, because it is the only one that is both instant and self-correcting. ## The read path, step by step 1. A component subscribes to the cache for key `K`. 2. The entry for `K` exists and is fresh: serve the stored value, make no request. 3. The entry exists and is stale: serve the stored value **and** start one refetch for `K`. A refetch already in flight for `K` is joined, not duplicated. 4. The entry is missing: there is nothing to serve, so this reader really is in a loading state. 5. The response lands: the entry is replaced, its arrival time reset, and every subscriber of `K` re-renders with the new value. Step 5 is the part that surprises people: the refetch does not belong to the component that triggered it. It updates the entry, and everything reading that entry updates with it. ## What the reader has to handle - **Two success shapes.** Data with nothing in flight, and data with a refetch in flight. The second should keep the content on screen and show a subdued indicator at most. - **Never blank on revalidate.** Replacing rendered content with a placeholder because the entry went stale throws away the whole benefit of the cache and causes layout shift. - **A failed refetch over good data.** A stale value plus a failed check is still more useful than an empty screen; surface the failure without deleting the value. - **Values that must not be stale.** Anything the user is about to act on irreversibly — a total to be charged, a permission, remaining stock — is confirmed by the server as part of the action, not trusted from a cached read. ## Where this goes wrong in practice The two common failures are opposite. One is a staleness window of zero everywhere, so every mount refetches and the app behaves as if there were no cache at all, only a memory cost. The other is an unbounded window with no refetch triggers, so a long-lived tab quietly shows yesterday's numbers. A third, subtler failure is an **unstable key** — a key rebuilt from a freshly created object or an unpinned timestamp on each render. Every read then looks like a brand-new question, so the cache reports a miss rather than a stale hit, and the screen flashes a loading placeholder that looks like a refetch bug but is really a keying bug.