reactive/data-client / .agents/skills/data-client-schema
data-client-schema
VerifiedModel the app's data with @data-client schemas, which normalize responses into one shared cache so an update shows everywhere. Use it whenever an endpoint returning data is added or its response changes (resource, RestEndpoint, GraphQL, Endpoint), when the data's shape changes, when data from different endpoints must be joined or related, when deriving views from loaded data, or when one item looks different in two places. Covers Entity, GQLEntity, Collection, Union and Query.
1. Defining Schemas
Compose schemas to match the JSON an endpoint returns. Import them from the protocol package
the app uses (@data-client/rest, @data-client/graphql or @data-client/endpoint; both protocol packages re-export
endpoint). For GraphQL, extend GQLEntity instead of Entity; it declares the id field used as pk().
Object
- Entity - represents a single unique object (denormalized)
- EntityMixin - turn any pre-existing class into an Entity
- new Union(Entity) - polymorphic objects (A | B)
{[key:string]: Schema}- immutable objects- new Invalidate(Entity|Union) - to delete an Entity
- new Lazy(() => Schema) - break circular imports / defer deep recursive denormalization
List
- new Collection([Schema]) - mutable/growable lists
[Schema]- immutable lists- new All(Entity|Union) - list all Entities of a kind
Map
new Collection(Values(Schema))- mutable/growable maps- new Values(Schema) - immutable maps
Lens-dependent entity fields
- new Scalar({ lens, key, entity? }) - fields that vary by runtime lens (portfolio, currency, locale) without entity mutation (demo)
Derived / selector pattern
-
new Query(Queryable) - memoized programmatic selectors
const queryRemainingTodos = new Query( TodoResource.getList.schema, entries => entries.filter(todo => !todo.completed).length, );useQuery(query, ...args)passes every arg to the Query'sschemaand to its function,(entries, ...args), so check each arg against both. The schema looks up its data with the args, asuseQuery(schema, ...args)would; when that finds nothing,useQuery()returnsundefined. Give the function an arg of its own only if the schema ignores it: All ignores every arg.Define
Querytransformations with the data model (e.g.src/resources/) — not inside custom hooks wrapping useSuspense/useQuery, which hides data dependencies and couples data logic to view code.
2. Entity best practices
- Every
Entitysubclass defines defaults for all non-optional serialised fields: bare TS field types emit no runtime value, so schema inference breaks. - Override
pk()only when the primary key ≠id. It must read top-level fields, since it also runs on lookup args and delete params, which usually hold only the key: copy a nested key ({ post: { id } }) toidinprocess()instead (example) static indexes = ['username' as const]to look up by a unique non-pk field withuseQuery(User, { username }), instead of building lookupMapspk()return type isnumber | string | undefined- Override
Entity.process(value, parent, key, args)to adapt input before normalizing, e.g. add fields from args/url, or turn an API's stand-in for a missing nested entity (like{}) intoundefined(example).parentandkeysay where the entity was nested static schema(optional) for nested schemas or deserialization functions; it also joins related entities client-side, so never join data by hand (Relationships)- When designing APIs, prefer nesting entities
3. Entity lifecycle methods
- Normalize (JSON response → cache): operates on POJOs; output is JSON-serializable plain data stored in the normalized cache. Order:
process()→pk()→ validate() → visit nested schemas (recurse intoschemafields) → if existing:mergeWithStore()which callsshouldUpdate()and maybeshouldReorder()+merge(); metadata viamergeMetaWithStore(). - Older data arriving after newer (a poll, slow request or embedded copy): override
shouldReorder(existingMeta, incomingMeta, existing, incoming)to compare a version field such asupdatedAt; that alone keeps the newer fields.shouldUpdate()is for skipping updates to save work. - Denormalize (cache → component): creates Entity class instances via
fromJS(), restoring prototype chain so getters, methods, andschemaprocessing work. Order:createIfValid()→ validate() →fromJS()→ unvisit nested schemas (recurse intoschemafields).
4. Union Types (Polymorphic Schemas)
To define polymorphic resources (e.g., events), use Union and a discriminator field.
import { Union } from '@data-client/rest';
export abstract class Event extends Entity {
type: EventType = 'Issue'; // discriminator field is shared
/* ... */
}
export class PullRequestEvent extends Event { /* ... */ }
export class IssuesEvent extends Event { /* ... */ }
export const EventResource = resource({
path: '/users/:login/events/public/:id',
schema: new Union(
{
PullRequestEvent,
IssuesEvent,
// ...other event types...
},
'type', // discriminator field
),
});
5. Collections (Mutable Lists & Maps)
Collections wrap Array or Values schemas to enable mutations (add/remove/move).
pk routing
pk() uses nestKey(parent, key) when nested in an Entity and available; otherwise it uses argsKey(...args), then serializes the result. Without options, it defaults to argsKey: params => ({ ...params }), using all endpoint args as the collection key.
argsKey— derive pk from endpoint arguments (default)nestKey— derive pk from parent entity for nested shared-state collections
Define both on the same Collection to reuse one definition top-level and nested. When argsKey(args) and nestKey(parent) produce the same object shape, the top-level fetch and the nested read resolve to the same (referentially equal) array/map — push/unshift/assign/move/remove on either updates both:
const userTodos = new Collection([Todo], {
argsKey: ({ userId }: { userId?: string }) => ({ userId }),
nestKey: (parent: User) => ({ userId: parent.id }),
});
push, unshift, assign and move add to every stored list whose key fields each equal the field of the same
name in the mutation's params or body. argsKey does not run for them, so name the key's fields as the mutation
sends them: the list above takes a push from POST /users/:userId/todos, or from a body that has userId.
nonFilterArgumentKeys
Default createCollectionFilter uses nonFilterArgumentKeys (default: keys starting with 'order') to exclude non-filter args when matching collections. This affects which existing collections receive new items from push/unshift/assign/move: pushing with { userId: 1 } reaches the {} and { userId: 1 } lists, not { userId: 2 }, and a list arg left out of nonFilterArgumentKeys (such as a sort) keeps new items out of that list.
Override as function, RegExp, or string[]:
new Collection([Todo], { nonFilterArgumentKeys: /orderBy|sortDir/ })
A plain fetch of a Collection endpoint replaces its contents; only the extenders below and
getPage add to it, so load more pages with getPage.
Extenders
Use each as an endpoint's schema (network; resource() exposes them as getList.push etc.) or with ctrl.set()
(local-only).
| Method | Type | Description |
|---|---|---|
push | Array | Entity | Append items to end |
unshift | Array | Entity | Prepend items to start |
assign | Values | Merge entries into map |
remove | Both | Remove items by value from matching collections |
move | Both | Remove from collections matching existing state, add to collections matching new state |
addWith(merge, filter?) | Both | Custom creation schema (used internally by push/unshift/assign) |
moveWith(merge) | Both | Custom move schema (control insertion order, e.g., unshift merge for prepending) |
6. Supplementary Endpoints (enrich existing entities)
When an endpoint returns partial or differently-shaped data for an entity already in cache (e.g., a metadata endpoint, a stats endpoint, a lazy-load expansion endpoint), use the same Entity as the schema — don't create a wrapper entity.
See partial-entities for patterns and examples.
7. Gotchas
- An endpoint without
schemabypasses normalization: its data is never updated by other endpoints' responses orctrl.set(). - Type responses with
Denormalize<typeof schema>, notInstanceType<>; it handles every schema (Union, Collection), not just Entity.
References
Vue projects: read <name>.vue.md instead of <name>.md when it exists.
Each guide holds working code. Read the matching section before writing code.
Relationships
Sections are in relational-data unless the row names another place.
| Situation | Read | Technique |
|---|---|---|
| A response nests related objects | "Nesting" | name each nested Entity in static schema |
| A response has only the id of a related object | "Client side joins" | process() copies the id to a field that static schema maps to the other Entity |
| A response has the list: an endpoint returns it, or the parent nests it | Collections | new Collection([Post], { argsKey, nestKey }) with push/remove/move; no custom merge() |
An entity must nest a list that no response has (user.posts when only posts nest their author), so a sort, another schema or any component reads it from the entity | "Reverse lookups" | the nested entity's process(value, parent, key) stores the parent's id; merge() joins the id lists, which only grow |
| A result that no response has, computed where it is read from each entity's current fields (links that move, a filter, a total) | All | new Query(new All(Post), (posts, { userId }) => posts.filter(post => post.author.id === userId)); it runs again when any entity of that kind changes |
| Two Entity classes refer to each other | "Circular dependencies" | set A.schema after both classes exist; import type in one direction |
Other use cases
| Use case | Read | Technique |
|---|---|---|
| A value from one entity's own fields | "Singular computations" in computed-properties | a getter on the Entity |
| A value across many entities | "Global computations" in computed-properties | a Query, read with useQuery() |
| List items have fewer fields than the detail response | partial-entities | summary and full classes share static key; validateRequired() on the full one |
| A mutation changes more than its own entity | side-effects | the response returns every changed entity and the endpoint's schema names each; not expireAll() |
| A list must stay sorted on the client | sorting-client-side | the endpoint's schema is a Query that sorts its Collection |
| A wrong or incomplete response must fail | validation | static validate() |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |