home / skills / harborgrid-justin / lexiflow-premium / client-side-cache-normalization

client-side-cache-normalization skill

/frontend/.github-skills/client-side-cache-normalization

This skill implements a normalized client-side cache to keep React app data consistent, auto-updating UI and efficient entity management.

npx playbooks add skill harborgrid-justin/lexiflow-premium --skill client-side-cache-normalization

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

594 B

---
name: client-side-cache-normalization
description: Implement a normalized entity cache to maintain data consistency across a React app.
---

# Client-Side Cache Normalization

## Summary
Implement a normalized entity cache to maintain data consistency across a React app.

## Key Capabilities
- Flatten nested API responses.
- Automatic UI updates.
- Garbage collect entities.

## PhD-Level Challenges
- Handle polymorphic data types.
- Resolve relationships.
- Optimize read performance.

## Acceptance Criteria
- Demonstrate consistency.
- Provide a schema.
- Benchmark retrieval speeds.

Overview

This skill implements a normalized entity cache for client-side React applications to keep data consistent across the UI. It flattens nested API responses into a single source of truth, enabling automatic UI updates and targeted cache invalidation. The implementation includes garbage collection of unused entities and tools to benchmark retrieval performance.

How this skill works

The cache ingests server responses and normalizes them into entity tables keyed by type and id. Components read derived queries from the normalized store; updates to any entity automatically notify dependents so the UI refreshes without refetching entire payloads. The system resolves relationships by storing references rather than nested objects, supports polymorphic types with type-discriminated records, and periodically garbage-collects orphaned entities.

When to use it

When multiple components read and update the same server entities and you need immediate consistency.
When APIs return deeply nested or repeated objects that cause duplication in client state.
When you want deterministic cache invalidation and minimal network traffic for updates.
When building complex forms or lists in a legal-management app where entity identity matters.
When you need to benchmark and optimize read latency for large client datasets.

Best practices

Design and publish a cache schema mapping server types to normalized entity shapes before implementation.
Use stable, application-wide id fields for keys; include a type discriminator for polymorphic records.
Normalize at the API boundary and keep normalized data immutable to simplify change detection.
Resolve relationships as references and provide selectors that recompose nested views on demand.
Measure retrieval speeds and tune indexing or memoization to optimize hot read paths.

Example use cases

Flattening court case payloads that include nested parties, documents, and events so UI updates reflect single-source changes.
Updating a client record in one form and having all open lists and detail panes reflect the change instantly.
Garbage-collecting detached attachments after document deletion to reduce memory use on long-lived sessions.
Handling polymorphic activity logs where entries can reference different entity types while preserving fast lookups.

FAQ

How do polymorphic entities work in the cache?

Store a type discriminator with each record and key entities by (type, id). Selectors can switch logic by type to recompose views.

How is garbage collection handled?

Track reference counts from root queries and relationships; periodically remove entities with zero references or use a deterministic LRU policy.