Quick StartAPI Reference
Quick Start

Tracking changes

Suggest Edits

How-To Guides

Enabling change tracking

In order to improve performance, change tracking is not enabled by default on records, instead, change tracking is an opt-in feature that can be achieved by setting the track property inside the schema of the particular record you wish to track. See below for examples of how to achieve basic change tracking.

👍

Tip

When re-using Mapper configs on a server side implementation, be considerate of the performance implications of leaving change tracking on in a Node.js environment.

Tracking individual properties

Since change tracking is an opt-in feature, you are required to specify which properties need to be tracked inside the schema. To track an individual property simply add track: true to the property definition.

import { DataStore } from 'js-data';

const store = new DataStore();

store.defineMapper('document', {
  endpoint: 'documents',
  schema: {
    properties: {
      id: { type: 'number' },
      title: { type: 'string', track: true }, // only title will be tracked
      content: { type: 'string' }
    }
  }
});

const doc = store.add('document', {
  title: 'Lessons Learned',
  content: '...'
});

// listen for any changes on the doc record
doc.on('change', (record, changes) => {
  console.log(changes); // { changed: { title: "Lessons I need to Learn" } }
});

// listen for changes to a specific tracked property
doc.on('change:title', (record, value) => {
  console.log(`New title: ${value}`); // "Lessons I need to Learn"
});

doc.title = 'Lessons I need to Learn'; // will trigger a change
doc.content = 'How a microwave works.'; // will not trigger a change

Tracking all properties of a record

If you know you want to track all properties of a record you can place track: true at the root of the schema definition. Note: properties not declared in the schema may not be tracked.

import { DataStore } from 'js-data';

const store = new DataStore();

store.defineMapper('document', {
  endpoint: 'documents',
  schema: {
    /**
     * All properties declared below will be tracked.
     * Any properties that are not included in the schema will NOT!
     */
    track: true,
    properties: {
      id: { type: 'number' },
      title: { type: 'string' },
      content: { type: 'string' }
    }
  }
});

const doc = store.add('document', {
  title: 'Lessons Learned',
  content: '...'
});

// listen for any changes on the doc record
doc.on('change', (record, changes) => {
  console.log(changes)
  /*  output:
      {
        changed: {
          title: "Lessons I need to Learn",
          content: "How a microwave works."
        }
      }
  */
});

// listen for changes to a specific tracked property
doc.on('change:title', (record, value) => {
  console.log(`New title: ${value}`); // "Lessons I need to Learn"
});
// listen for changes to a specific tracked property
doc.on('change:content', (record, value) => {
  console.log(`New content: ${value}`); // "How a microwave works."
});

// These changes will be batched into a single event loop,
// triggering one "change" event.
doc.title = 'Lessons I need to Learn'; // will trigger a change
doc.content = 'How a microwave works.'; // will trigger a change

👍

Tip

Records with tracked properties emit change events, which may bubble up. See Events & Listeners for more information.

Updated over 7 years ago

What’s Next