🌲 Get back to Nature 🐿️ Or shipping 💚
SchemaRecord is:
- ⚡️ Fast
- 📦 Tiny
- ✨ Optimized
- 🚀 Scalable
Universal
Never write a Model again.
This package provides presentation capabilities for your resource data. It works together with an EmberData Cache and associated Schemas to simplify the most complex parts of your state management.
pnpm install @warp-drive/schema-record
Tagged Releases
Install using your javascript package manager of choice. For instance with pnpm
pnpm add @warp-drive/schema-record
If this package is how you are first learning about EmberData, we recommend starting with learning about the Store and Requests
SchemaRecord integrates with EmberData via the Store's resource lifecycle hooks.
When EmberData needs to create a new presentation class to pair with some resource
data, it calls instantiateRecord. When it no longer needs that class, it will call
teardownRecord.
import Store from '@ember-data/store';
import SchemaRecord from '@warp-drive/schema-record';
import Cache from '@ember-data/json-api';
const DestroyHook = Symbol.for('destroy');
export default class extends Store {
instantiateRecord(identifier) {
return new SchemaRecord(this, identifier);
}
teardownRecord(record: SchemaRecord): void {
record[DestroyHook]();
}
}Any Store method that returns records will use SchemaRecord once configured as above. After that, its up to you what SchemaRecord can do.
SchemaRecord's behavior is driven by the Schemas you register with the Store's Schema Service. Schemas are simple json objects that follow a pattern.
You could manually construct schemas, though that would be laborious. We recommend
compiling schemas from another available source such as your API's types. If you don't
have a source from which to compile schemas, consider using @warp-drive/schema-dsl.
The Schema DSL allows authoring rich, expressive schemas using familiar Typescript and Decorators, which compile at build into json schemas you can deliver to your app either in your asset bundle, via a separate fetch, or from your API.
The Schema DSL will also compile and register types for your schemas that give you robust typescript support.
SchemaRecord is Immutable. This means by design you cannot mutate a SchemaRecord instance.
How then do you make edits and preserve changes?
Edits are performed in mutation workflows. A workflow is begun by forking the store. Forks are cheap copy-on-write scopes that allow you to make changes in isolation without affecting the global state of the application (until you want to). You can even fork forks, though its probably not that useful to do so in the common case.
const fork = await store.fork();Forks are not themselves editable, they are just a pre-requisite. There are three ways to get an editable SchemaRecord instance.
- Create a new record with
const editable = fork.createRecord(<type>, data) - Checkout an existing record in edit mode:
const editable = fork.checkoutRecord(record) - Access a related record on a record already in edit mode:
const editableFriend = editable.bestFriend
If you decide you want to discard your changes, there's no need to rollback. Simply dereferencing the fork and any records you've received from it will cause it to GC.
However, explicitly calling fork.deref() will ensure that if you did forget to dereference
any records and left them around somewhere as a variable, they'll blow up with a useful
error if used again.
To save changes, call fork.request(saveRecord(editable)). Saving changes will only commit
the changes to the fork, it won't commit them upstream. To reflect the changes upstream, call
await fork.merge(store). In most cases, store should be the store you forked from, though
it is allowed to attempt to merge into a parent store as well.
// get a fork for editing
const fork = await store.fork();
// create a new record
const user = fork.createRecord('user', { name: 'Chris' });
// save the record
await fork.request(createRecord(user));
// reflect the changes back to the original store
await store.merge(fork);Note: merging behavior is determined by the Cache implementation. The implementations maintained by the EmberData team will merge both persisted and unpersisted changes back to the upstream (preserving them as remote and local state respectively). This approach allows developers to choose to optimistically vs pessimistically update the global state.
// get a fork for editing
const fork = await store.fork();
// create a new record
const user = fork.createRecord('user', { name: 'Chris' });
// reflect the (dirty) changes back to the original store
await store.merge(fork);
// save the record
await fork.request(createRecord(user));
// reflect the (clean) changes back to the original store
await store.merge(fork);The schema format is the array representation of a Map structure. From which we will populate or append to a Map!
[
[ 'user', <user-schema> ],
[ 'company', <company-schema> ],
]It follows this signature:
type ResourceType = string; // 'user'
type FieldName = string; // 'name'
type FieldDef = {
name: string;
type: string | null;
kind: 'resource' | 'collection' | 'attribute' | 'derivation' | 'object' | 'array';
options: Record<string, unknown>;
};
type ResourceSchema = Array<[FieldName, FieldDef]>
type Schemas = Array<[ResourceType, ResourceSchema]>You'll find this syntax is capable of describing most conceivable behaviors, including some emergent ones we're sure we haven't thought of yet.