State & ArchitectureBaseline · Widely

Normalized Entity Graphs vs Document-Keyed Caches

Mental Model

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.

Interactive Simulator

Document-Keyed Cache vs Normalized Entity Graph

Compare query-keyed snapshot invalidation against pointer-based entity normalization.

Lines of Code
Before
3
After
3
Reflows / Browser Cost
Before
1 extra network round-trip on mutation
After
Synchronous multi-view update
BeforeDocument-Keyed Cache (Invalidate & Refetch)
cache.set('GET:/projects/1', { id: 1, name: 'V2' });
// 'GET:/projects' still holds { id: 1, name: 'V1' } until refetched:
await invalidatePrefix('GET:/projects');
Lines: 3Reflows: 1 extra network round-trip on mutationDependencies: ~12 KB query client

Simple mental model and zero schema coupling; overlapping views converge after background refetch.

After (Native)Normalized Entity Graph (Pointer Propagation)
entities.set('Project:1', { id: 1, name: 'V2' });
// Both 'GET:/projects/1' and 'GET:/projects' resolve 'Project:1' ref:
notifySubscribers('Project:1'); // zero extra fetches
Lines: 3Reflows: Synchronous multi-view updateDependencies: 35-50 KB normalized graph runtime

All 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.

  1. Document-keyed cache: Maps hash(url, params) directly to the raw JSON tree. Mutations call invalidateQueries(['users']) to trigger background refetches, keeping client code under ~12 KB.
  2. Normalized entity graph: Flattens nested payloads into { "User:42": { name: "Ada" } } and replaces nested objects with { __ref: "User:42" } pointers.
  3. Graph updates & GC: Updating User:42 during Optimistic UI patches every view synchronously, while reference counting sweeps unreferenced entities.
TS
// 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 views

Problem Genealogy

  • 2015–2019 (Relay & Apollo Normalized Graphs): Solved cross-view GraphQL consistency by shipping 35–50 KB normalized store runtimes and requiring __typename on 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

Production Pitfall
  • Ghost rows in paginated lists: Updating a normalized entity's status field 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 __typename or id: Normalized clients fall back to unmerged object copies when a projection omits the primary key, causing partial UI drift.
When Not to Use
  • 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.

Connections & Logical Next Steps

State & ArchitectureNormalized Entity Graphs vs Document-Keyed Caches
What This Unlocks
Leaf concept