ember-data-change-tracker

New

Experimental feature
- isDirty, hasDirtyRelations computed properties
  - Set up in configuration as { enableIsDirty: true }
  - It is experimental and a has one crippling defect, it can not track object type attributes. But if you don't have object types it works fine.

This addon aims to fill in the gaps in the change tracking / rollback that ember data does now.

Currently ember-data
- tracks changes for numbers/strings/date/boolean attributes
- has a changeAttributes() method to see what changed => [ last, current ]
- has a rollbackAttributes() method to rollback attributes
- has a hasDirtyAttributes computed property
This addon:
- tracks modifications in attributes that are object/json/custom type
- tracks replacement of belongsTo associations
- tracks replacement/changes in hasMany associations
- adds a changed() method to DS.Model
- adds a rollback() method to DS.Model
- adds a isDirty computed property to DS.Model ( only if enabled in configuration )
- adds a hasDirtyRelations computed property to DS.Model ( only if enabled in configuration )
- Only works with
  - ember-data versions 2.7+ ( if you have polymphic relationships )
  - ember-data versions 2.5+ ( if you don't )
- Can be used in two modes
  - auto track mode
  - manual track mode ( the default )

Installation

ember install ember-data-change-tracker

Why?

Say there is a user model like this:

  export default Model.extend({
       name: attr('string'),  // ember-data tracks this already
       info: attr('object'),  // ember-data does not track modifications
       json: attr(),          // ember-data does not track modifications if this is object
       company: belongsTo('company', { async: false, polymorphic: true }),  // ember-data does not track replacement
       profile: belongsTo('profile', { async: true }), // ember-data does not track replacement
       projects: hasMany('project', { async: false }), // ember-data does not track additions/deletions
       pets: hasMany('pet', { async: true, polymorphic: true }) // ember-data does not track additions/deletions
   });

You can not currently rollback the info, json if they are modified or company, profile, projects and pets if they change.

Changed

The method changed() is added to model
Shows you any changes in an object attribute type
- whether modified or replacing the value
- attr() will default to 'object' type
- works with any custom type you have created
Shows when you replace a belongsTo association
Shows when you add to a hasMany association
Shows when you delete from a hasMany association
Merges ember-data changeAttribute() information into one unified change object
Unlike ember-data no last and current value is shown, just the boolean => true
- Though you will see [last value, current value] for the attributes that ember-data tracks

Example: ( remove from a hasMany )

  user.get('projects').removeObject(firstProject); // remove project1
  user.changed() //=> {projects: true }

Rollback

The method rollback() is added to model
If you're not using auto track you have to call startTrack() before editing
Performace wise, it's way faster than you think it should be.
- Tested on model with hundreds of items in a hasMany association.
- Though you might want to think twice when tracking one with thousands

Usage:

make and makeList are from ember-data-factory-guy.
- they create and push models ( based on factories ) into the ember-data store

    let info = {foo: 1};
    let projects = makeList('project', 2);
    let [project1] = projects;
    let pets = makeList('cat', 4);
    let [cat, cat2] = pets;
    let bigCompany = make('big-company');
    let smallCompany = make('small-company');

    let user = make('user', { profile: profile1, company: bigCompany, pets, projects });

    // manual tracking model means you have to explicitly call => startTrack
    // to save the current state of things before you edit
    user.startTrack();   

    // edit things  
    user.setProperties({
      'info.foo': 3,
      company: smallCompany,
      profile: profile2,
      projects: [project1],
      pets: [cat1, cat2]
    });

    user.rollback();

    // it's all back to the way it was
    user.get('info') //=> {foo: 1}
    user.get('profile') //=> profile1
    user.get('company') //=> bigCompany
    user.get('projects') //=> first 2 projects
    user.get('pets') //=> back to the same 4 pets

isDirty, hasDirtyRelations

Computed properties to check if the model has changed
Not enabled by default
Need to set enableIsDirty ( true ) on model or global configuration
The only attributes that can NOT be tracked with isDirty are object/array attributes

Usage:

    let info = {foo: 1};
    let pets = makeList('cat', 4);
    let [cat, cat2] = pets;
    let bigCompany = make('big-company');
    let smallCompany = make('small-company');

    let user = make('user', { company: bigCompany, pets });

    user.startTrack();   

    // edit things  
    user.set('name', "new name");
    user.get('isDirty'); //=> true
    
    user.rollback();
    user.get('isDirty'); //=> false
    
    user.set('company', smallCompany);
    user.get('hasDirtyRelations'); //=> true
    user.get('isDirty'); //=> true

    user.rollback();
    user.get('isDirty'); //=> false

    user.set('pets', [cat, cat2]);
    user.get('hasDirtyRelations'); //=> true
    user.get('isDirty'); //=> true
    
    user.rollback();
    user.get('isDirty'); //=> false

    // things that don't work      
    user.set('info.foo', 3); 
    user.get('isDirty'); //=> false ( object/array attributes don't work for computed isDirty )

Configuration

Global configuration
- By default the global settings are:
  - { trackHasMany: true, auto: false, enableIsDirty: false }
    - Essentially this says, track everything in the model but only when I tell you
    - Since this is manual mode you probably want to track everything since you are focused on one edit at a time, hence trackHasMany is on
- The options available are:
  - trackHasMany : should hasMany associations be tracked? ( true is default )
    - this is just a shortcut to exclude all the hasMany relations
  - auto : should tracking be turned on by default? ( false is default )
    - auto tracking means when any model is saved/updated/reloaded the tracker will save the current state, allowing you to rollback anytime
  - enableIsDirty : sets up computed properties on a model
    - hasDirtyRelations for checking on changed relationships
    - isDirty for checking on any changes
      - NOTE: not working for object type attributes, since those are too difficult to observe for the purpose of computed properties
Model configuration
- Takes precedence over global
  - So, globally auto track could be off, but on one model you can turn it on
- The options available are:
  - trackHasMany : same as global trackHasMany
  - auto : same as global auto
  - only : limit the attributes/associations tracked on this model to just these
  - except : don't include these attributes/associations
  - You can use 'only' and 'except' at the same time, but you could also clean your nose with a pipe cleaner

  // file config/environment.js
  var ENV = {
    modulePrefix: 'dummy',
    environment: environment,
    rootURL: '/',
    locationType: 'auto',
    changeTracker: { trackHasMany: true, auto: true }, 
    EmberENV: {
    ... rest of config

Set options on the model

  // file app/models/user.js
  export default Model.extend({
    changeTracker: {only: ['info', 'company', 'pets']}, // settings for user models

    name: attr('string'),
    info: attr('object'),
    json: attr(),
    company: belongsTo('company', { async: false, polymorphic: true }),
    profile: belongsTo('profile', { async: true }),
    projects: hasMany('project', { async: false }),
    pets: hasMany('pet', { async: true, polymorphic: true })
  });

Serializer extras

Mixin is provided that will allow you to remove any attributes/associations that did not change from the serialized json
Useful when you want to reduce the size of a json payload
removing unchanged values can be big reduction at times

Example:

Let's say you set up the user model's serializer with keep-only-changed mixin

// file: app/serializers/user.js
import DS from 'ember-data';
import keepOnlyChanged from 'ember-data-change-tracker/mixins/keep-only-changed';

export default DS.RESTSerializer.extend(keepOnlyChanged);

Then when you are updating the user model

user.set('info.foo', 1);
user.serialize(); //=> '{ info: {"foo:1"} }'

Without this mixin enabled the json would look like:

  { name: "dude", info: {"foo:1"}, company: "1" companyType: "company", profile: "1" }

where all the attributes and association are included whether they changed or not

Extra's

Adds a few more helpful methods to ember data model
- didChange(key)
  - did the value on this key change?
- savedTrackerValue(key)
  - this is the value that the key had after it was created/saved and before any modifications

Usage:

  user.startTrack(); // saves all keys that are being tracked
  user.savedTrackerValue('info') //=> {foo: 1}  original value of info
  user.set('info.foo', 8)      
  user.didChange('info') //=> true
  user.savedTrackerValue('info') //=> {foo: 1}  original value of info

Known Issues

Ember less than 2.10 AND you are using auto track mode
When pushing data to the store directly to create a model ( usually done when using websockets .. but same issue if using factory guy) you need to call model.saveChanges() manually after creating that new model
Testing
- In unit / integration tests you have to manually initialize change-tracker if you are testing anything that requires the addon to be enabled

For example:

import {moduleForModel, test} from 'ember-qunit';
import {make, manualSetup} from 'ember-data-factory-guy';
import {initializer as changeInitializer} from 'ember-data-change-tracker';

moduleForModel('project', 'Unit | Model | project', {

  beforeEach() {
    manualSetup(this.container);
    changeInitializer();
  }
});

License

Leooo/ember-data-change-tracker

ErrorLooks like something went wrong!

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Error
Looks like something went wrong!

Packages