1. Defining Schemas

Define schemas to represent the JSON returned by an endpoint. Compose these to represent the data expected.

Object

Entity - represents a single unique object (denormalized)
new Union(Entity) - polymorphic objects (A | B)
{[key:string]: Schema} - immutable objects
new Invalidate(Entity|Union) - to delete an Entity

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

Derived / selector pattern

new Query(Queryable) - memoized programmatic selectors

const queryRemainingTodos = new Query(
  TodoResource.getList.schema,
  entries => entries.filter(todo => !todo.completed).length,
);

const groupTodoByUser = new Query(
  TodoResource.getList.schema,
  todos => Object.groupBy(todos, todo => todo.userId),
);

2. Entity best practices

Every Entity subclass defines defaults for all non-optional serialised fields.
Override pk() only when the primary key ≠ id.
pk() return type is number | string | undefined
Override Entity.process(value, parent, key, args) to insert fields based on args/url
static schema (optional) for nested schemas or deserialization functions
- When designing APIs, prefer nesting entities

3. Entity lifecycle methods

Normalize order: process() → validate() → pk() → if existing: mergeWithStore() which calls shouldUpdate() and maybe shouldReorder() + merge(); metadata via mergeMetaWithStore().
Denormalize order: createIfValid() → validate() → fromJS().

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. Best Practices & Notes

Always set up schema on every resource/entity/collection for normalization
Normalize deeply nested or relational data by defining proper schemas

6. Common Mistakes to Avoid

Don't forget to use fromJS() or assign default properties for class fields

References

For detailed API documentation, see the references directory:

Entity - Normalized data class
Collection - Mutable/growable lists
Union - Polymorphic schemas
Query - Programmatic selectors
Invalidate - Delete entities
Values - Map schemas
All - List all entities of a kind
Array - Immutable list schema
Object - Object schema
schema - Schema overview
relational-data - Relational data guide
computed-properties - Computed properties guide
partial-entities - Partial entities guide
side-effects - Side effects guide
sorting-client-side - Client-side sorting guide

rdc-schema