data-client-schema_skill

Overview

This skill defines client-side data schemas and patterns for normalizing, denormalizing, and querying JSON returned by APIs. It models Entities, Collections, Unions (polymorphic types), Maps/Values, Queries (memoized selectors), and lifecycle operations like primary key resolution, validation, merge, and invalidation. The goal is predictable async state handling across REST, GraphQL, SSE, and WebSocket feeds. It pairs TypeScript types with runtime schemas to keep UI state normalized and efficient.

How this skill works

You declare schema objects (Entity classes, Collection, Union, Values, All, Query, etc.) that mirror the API payload shape. During normalization the system runs Entity.process → validate → pk → mergeWithStore (calling shouldUpdate/shouldReorder/merge) and stores flattened records. Denormalization reconstructs nested objects via createIfValid → validate → fromJS. Queries run memoized selectors against normalized entries to compute derived results efficiently.

When to use it

• Building a client cache for REST/GraphQL responses that must stay consistent across components
• Handling deeply nested or relational API payloads where normalization improves updates and lookups
• Modeling polymorphic resources (events/messages) that require type discrimination
• Implementing optimistic updates, invalidation, or entity deletion flows
• Writing selectors that depend on normalized store slices for memoized derived data

Best practices

• Define defaults for all non-optional serialized fields on every Entity subclass to avoid undefined state
• Override pk() only when the primary key is not id; return number|string|undefined
• Set static schema on Entities for nested relations and client-side joins instead of manual merging
• Use Entity.process to inject fields derived from request args or URL before validation
• Prefer Denormalize<> types from the library to derive TypeScript types that respect Unions and complex schemas

Example use cases

• Model a Todo app where Todo is an Entity, Todos list is a Collection, and user grouping uses a Query selector
• Normalize a feed of polymorphic events using Union with a shared discriminator field (e.g., type)
• Expose a Values(map) of settings keyed by name and a Collection of items for draggable lists
• Handle SSE/WebSocket messages by normalizing incoming event payloads and merging into the store
• Create a server-paginated resource where All lists every Entity of a kind and Collection handles page inserts