Normalized Entity Graphs vs Document-Keyed Caches
Document-keyed caches store each query response by its request key, leaving the same user record stale in /feed after /profile updates it. Normalized caches deduplicate entities by (type, id) so one write updates every subscriber, at the cost of schema-aware garbage collection.
Document-Keyed Cache vs Normalized Entity Graph
Compare query-keyed snapshot invalidation against pointer-based entity normalization.
cache.set('GET:/projects/1', { id: 1, name: 'V2' });
// 'GET:/projects' still holds { id: 1, name: 'V1' } until refetched:
await invalidatePrefix('GET:/projects');Simple mental model and zero schema coupling; overlapping views converge after background refetch.
entities.set('Project:1', { id: 1, name: 'V2' });
// Both 'GET:/projects/1' and 'GET:/projects' resolve 'Project:1' ref:
notifySubscribers('Project:1'); // zero extra fetchesAll views reading Project:1 update immediately, though filtered list membership still needs eviction.
Under the Hood
A Server State Cache Machine stores remote snapshots under one of two indexing topologies. The choice determines whether consistency happens by key invalidation or by graph pointer resolution.
- Document-keyed cache: Maps
hash(url, params)directly to the raw JSON tree. Mutations callinvalidateQueries(['users'])to trigger background refetches, keeping client code under ~12 KB. - Normalized entity graph: Flattens nested payloads into
{ "User:42": { name: "Ada" } }and replaces nested objects with{ __ref: "User:42" }pointers. - Graph updates & GC: Updating
User:42during Optimistic UI patches every view synchronously, while reference counting sweeps unreferenced entities.
// Document-keyed: fast lookup, requires key invalidation on write
const docCache = new Map([['GET:/team/7', { members: [{ id: 42, name: 'Ada' }] }]]);
// Normalized: single source per entity, pointer-resolved on read
const entityTable = new Map([['User:42', { id: 42, name: 'Ada' }]]);
const queryRefs = new Map([['GET:/team/7', { members: ['User:42'] }]]);
entityTable.set('User:42', { id: 42, name: 'Ada L.' }); // updates all viewsProblem Genealogy
- 2015–2019 (Relay & Apollo Normalized Graphs): Solved cross-view GraphQL consistency by shipping 35–50 KB normalized store runtimes and requiring
__typenameon every selection set. - 2020+ (SWR & TanStack Query): Proved that 80% of REST/RPC apps need only document-keyed caches paired with coarse prefix invalidation.
Production Pitfalls
- Ghost rows in paginated lists: Updating a normalized entity's
statusfield updates its badge, yet fails to move it out of a cached['tasks', { status: 'open' }]page because list membership is still query-keyed. - Silent cache misses on missing
__typenameorid: Normalized clients fall back to unmerged object copies when a projection omits the primary key, causing partial UI drift.
- When not to use a normalized entity graph: For REST/RPC APIs with flat payloads, paginated search feeds, or fewer than 3 overlapping entity views per screen, normalized graph normalization and custom cache-eviction rules add unnecessary bundle weight and stale-list bugs over document-keyed invalidation.