Skip to main content
Version: Next

Updating data

Data in a source can be updated by applying a transform, which consists of one or more operations. Transforms must be applied atomically—all operations succeed or fail together.

Operations#

Operations each represent a single change to a record or relationship (e.g. adding a record, updating a field, deleting a relationship, etc.).

The base Operation interface consists of:

  • op - a string identifying the type of operation
  • options - (Optional) a RequestOptions object

The other members of an Operation are specific to the op. The following standard record-specific operations are defined in @orbit/records:

interface AddRecordOperation extends Operation {  op: 'addRecord';  record: InitializedRecord;}
interface UpdateRecordOperation extends Operation {  op: 'updateRecord';  record: InitializedRecord;}
interface RemoveRecordOperation extends Operation {  op: 'removeRecord';  record: RecordIdentity;}
interface ReplaceKeyOperation extends Operation {  op: 'replaceKey';  record: RecordIdentity;  key: string;  value: string;}
interface ReplaceAttributeOperation extends Operation {  op: 'replaceAttribute';  record: RecordIdentity;  attribute: string;  value: unknown;}
interface AddToRelatedRecordsOperation extends Operation {  op: 'addToRelatedRecords';  record: RecordIdentity;  relationship: string;  relatedRecord: RecordIdentity;}
interface RemoveFromRelatedRecordsOperation extends Operation {  op: 'removeFromRelatedRecords';  record: RecordIdentity;  relationship: string;  relatedRecord: RecordIdentity;}
interface ReplaceRelatedRecordsOperation extends Operation {  op: 'replaceRelatedRecords';  record: RecordIdentity;  relationship: string;  relatedRecords: RecordIdentity[];}
interface ReplaceRelatedRecordOperation extends Operation {  op: 'replaceRelatedRecord';  record: RecordIdentity;  relationship: string;  relatedRecord: RecordIdentity | null;}

Transforms#

The Transform interface has the following members:

  • id - a string that uniquely identifies the transform
  • operations - an instance or array of Operation objects
  • options - an optional object that represents options that can influence how a transform is processed

Although transforms can be created "manually", you'll probably find it easier to use a builder function that returns a transform.

To use a transform builder, pass a function into a source's method that expects a transform, such as update or push. A TranformBuilder that's compatible with the source should be applied as an argument. You can then use this builder to create one or more operations.

For instance, here's how you might update a memory source with a single record:

const earth = {  type: 'planet',  id: 'earth',  attributes: {    name: 'Earth'  }};
memory.update((t) => t.addRecord(earth));

To perform more than one operation in a single transform, just return an array of operations:

memory.update((t) => [t.addRecord(earth), t.addRecord(jupiter)]);

Standard transforms#

You can use the standard @orbit/data transform builder as follows:

// Adding a new recordmemory.update((t) =>  t.addRecord({    type: 'planet',    id: 'earth',    attributes: {      name: 'Earth'    }  }));
// Updating a recordmemory.update((t) =>  t.updateRecord({    type: 'planet',    id: 'earth',    attributes: {      name: 'Earth',      classification: 'terrestrial',      atmosphere: true    }  }));
// Removing a recordmemory.update((t) => t.removeRecord({ type: 'planet', id: 'earth' }));
// Replacing a keymemory.update((t) =>  t.replaceKey({ type: 'planet', id: 'earth' }, 'remoteId', 'abc123'));
// Replacing an attributememory.update((t) =>  t.replaceAttribute(    { type: 'planet', id: 'earth' },    'classification',    'gaseous'  ));
// Adding a member to a to-many relationshipmemory.update((t) =>  t.addToRelatedRecords({ type: 'planet', id: 'jupiter' }, 'moons', {    type: 'moon',    id: 'io'  }));
// Removing a member from a to-many relationshipmemory.update((t) =>  t.removeFromRelatedRecords({ type: 'planet', id: 'jupiter' }, 'moons', {    type: 'moon',    id: 'io'  }));
// Replacing every member of a to-many relationshipmemory.update((t) =>  t.replaceRelatedRecords({ type: 'planet', id: 'jupiter' }, 'moons', [    { type: 'moon', id: 'io' },    { type: 'moon', id: 'europa' }  ]));
// Replacing a to-one relationshipmemory.update((t) =>  t.replaceRelatedRecord({ type: 'planet', id: 'jupiter' }, 'solarSystem', {    type: 'solarSystem',    id: 'ourSolarSystem'  }));

Transform options#

Options can be added to transforms to provide processing instructions to particular sources and to include metadata about transforms.

For example, the following transform is given a label and contains instructions for the source named remote:

memory.update(  (t) =>    t.updateRecord({      type: 'planet',      id: 'earth',      attributes: {        name: 'Earth',        classification: 'terrestrial',        atmosphere: true      }    }),  {    label: 'Update planet Earth',    sources: {      remote: {        timeout: 100000      }    }  });

A label can be useful for providing an understanding of actions that have been queued for processing.

The sources: { ${sourceName}: sourceSpecificOptions } pattern is used to pass options that only a particular source will understand when processing a transform. In this instance, we're telling our remote source to use a custom timeout when performing this particular update.

It is possible to pass different options to each operation in the transform.

memory.update((t) => [  t    .addRecord({      type: 'planet',      attributes: {        name: 'Earth'      }    })    .options({ timeout: 1000 }),  t    .addRecord({      type: 'planet',      attributes: {        name: 'Jupiter'      }    })    .options({ timeout: 2000 })]);