Server State Cache Machines (fresh → stale → fetching)
Storing API payloads in Redux or useState turns every mount into a redundant network waterfall. A server-state cache machine tracks fresh, stale, and fetching transitions, deduplicating concurrent reads via HTTP Caching patterns and revalidating on Visibility Changes.
Server State Cache Transitions
Trace how a key-indexed cache machine deduplicates observers, serves stale data, and runs GC.
Two components request ['user', 42] simultaneously; only one fetch() executes.
if (entry.inflight) return entry.inflight;- status
- fetching
- observers
- 2
- networkRequests
- 1
Under the Hood
A cache machine indexes every query by a deterministic serialized key in a Map<QueryKey, QueryEntry>. Multiple mounted observers subscribe to the same entry instead of owning independent fetch lifecycles.
- In-Flight Deduplication: When an observer mounts for a key with an active
Promise, the machine returns the existing promise reference instead of opening a second TCP/HTTP stream. - Stale-While-Revalidate (SWR): If
Date.now() - updatedAt < staleTime, the entry staysfreshand returns cached data synchronously. OncestaleTimeexpires, reads still return stale data in 0 ms while dispatching a background refetch. - Observer Reference Counting & GC: Each mounted component increments
observers.size. Whenobservers.sizehits0, agcTimetimer starts; if no observer remounts before expiry, V8 reclaims the entry.
class QueryEntry<T> {
state: 'fresh' | 'stale' | 'fetching' = 'fetching';
data?: T;
updatedAt = 0;
inflight: Promise<T> | null = null;
fetch(fetcher: () => Promise<T>, staleTime: number): Promise<T> {
if (this.inflight) return this.inflight;
if (this.data && Date.now() - this.updatedAt < staleTime) return Promise.resolve(this.data);
this.state = 'fetching';
return (this.inflight = fetcher().then((res) => {
Object.assign(this, { data: res, updatedAt: Date.now(), state: staleTime > 0 ? 'fresh' : 'stale', inflight: null });
return res;
}));
}
}Problem Genealogy
- 2015 (Global Store Boilerplate): Teams stored server responses in Redux with manual
isLoadingbooleans, shipping 25 KB of reducer/thunk code and still suffering duplicate mounts. - 2019 (SWR & React Query): Replaced client-owned loading flags with key-indexed cache machines modeled after RFC 5861
stale-while-revalidate. - 2024 (Unified Hydration & Optimistic Mutations): Cache machines serialize dehydrated snapshots during SSR and roll back optimistic writes deterministically.
Production Pitfalls
- Thundering Herd on
staleTime: 0: DefaultingstaleTimeto0marks every response immediately stale, causing a full refetch burst whenever a user switches browser tabs or remounts a list. - Unstable Object Keys: Passing inline objects with randomized property order or unmemoized functions as query keys defeats
Maplookup and leaks entries untilgcTimeexpires.
- When not to use a client cache machine: Never put high-frequency ephemeral streams (60 fps WebSocket telemetry, local drag coordinates) into a serialized query cache; key hashing and subscriber notifications add unnecessary heap allocations.
Connections & Logical Next Steps
Both normalized graphs and document caches sit inside server-state cache machines to manage staleness and invalidation.
Remote entities require staleness tracking, deduplication, and background revalidation instead of manual store slices.
Client cache machines mirror HTTP Cache-Control stale-while-revalidate semantics in JavaScript heap memory.
Tab refocus triggers visibilitychange listeners that transition stale cache entries back to fetching.