@cityads/ember-data-change-tracker 0.11.0

package/.eslintrc.js

@@ -0,0 +1,15 @@
+/* global module */
+module.exports = {
+  root: true,
+  parserOptions: {
+    ecmaVersion: 2017,
+    sourceType: 'module'
+  },
+  extends: 'eslint:recommended',
+  env: {
+    browser: true
+  },
+  rules: {
+    "no-console": "off"
+  }
+};

package/LICENSE.md

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2017
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,308 @@
+# ember-data-change-tracker
+
+[![npm version](https://badge.fury.io/js/@cityads%2Fember-data-change-tracker.svg)](http://badge.fury.io/js/@cityads%2Fember-data-change-tracker)
+
+**New**  
+  - Experimental feature
+    - isDirty, hasDirtyRelations computed properties  
+      - Set up in [configuration](https://github.com/danielspaniel/ember-data-change-tracker#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 ```changedAttributes()``` 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 ```modelChanges()``` 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:
+
+```javascript
+  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.
+  
+  
+### model changes
+  
+  - The method ```modelChanges()``` 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 )
+```javascript
+  user.get('projects').removeObject(firstProject); // remove project1
+  user.modelChanges() //=> {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](https://github.com/danielspaniel/ember-data-factory-guy). 
+  - they create and push models ( based on factories ) into the ember-data store
+ 
+```javascript 
+    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](https://github.com/danielspaniel/ember-data-change-tracker#configuration)
+ - The only attributes that can NOT be tracked with isDirty are object/array
+   attributes
+ 
+Usage:
+  
+```javascript 
+
+    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         
+
+```javascript
+  // 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
+
+```javascript
+  // 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
+
+```javascript
+// 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
+
+```javascript
+user.set('info.foo', 1);
+user.serialize(); //=> '{ info: {"foo:1"} }'
+```
+
+Without this mixin enabled the json would look like:
+```javascript
+  { 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:
+```javascript
+  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
+ - 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.saveTrackerChanges()``` 
+   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:
+ 
+```javascript
+
+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();
+  }
+});
+
+```                                   

package/addon/index.js

@@ -0,0 +1,4 @@
+import {initializer} from './initializer';
+import keepOnlyChanged from './mixins/keep-only-changed';
+
+export {keepOnlyChanged, initializer};

package/addon/initializer.js

@@ -0,0 +1,4 @@
+/* global require */
+export function initializer() {
+  require('ember-data-change-tracker/model-ext');
+}

package/addon/mixins/keep-only-changed.js

@@ -0,0 +1,26 @@
+import Ember from 'ember';
+
+// EmberData does not serialize hasMany relationships by default
+export default Ember.Mixin.create({
+  keepValue(record, key) {
+    return record.get('isNew') || record.didChange(key);
+  },
+
+  serializeAttribute: function(snapshot, json, key) {
+    if (this.keepValue(snapshot.record, key)) {
+      return this._super(...arguments);
+    }
+  },
+
+  serializeBelongsTo: function(snapshot, json, relationship) {
+    if (this.keepValue(snapshot.record, relationship.key)) {
+      return this._super(...arguments);
+    }
+  },
+
+  serializeHasMany: function(snapshot, json, relationship) {
+    if (this.keepValue(snapshot.record, relationship.key)) {
+      return this._super(...arguments);
+    }
+  }
+});

package/addon/model-ext.js

@@ -0,0 +1,212 @@
+import Ember from 'ember';
+import Model from 'ember-data/model';
+import Tracker from './tracker';
+
+Model.reopen({
+
+  init(){
+    this._super(...arguments);
+    if (Tracker.isAutoSaveEnabled(this)) {
+      this.initTracking();
+    }
+    if (Tracker.isIsDirtyEnabled(this)) {
+      // this is experimental
+      Tracker.initializeDirtiness(this);
+    }
+
+    this.setupTrackerMetaData();
+    this.setupUnknownRelationshipLoadObservers();
+  },
+
+  /**
+   * Did an attribute/association change?
+   *
+   * @param {String} key the attribute/association name
+   * @param {Object} changed optional ember-data changedAttribute object
+   * @returns {Boolean} true if value changed
+   */
+  didChange(key, changed, options) {
+    return Tracker.didChange(this, key, changed, options);
+  },
+
+  /**
+   * Did any attribute/association change?
+   *
+   * returns object with:
+   *  {key: value} = {attribute: true}
+   *
+   * If the the attribute changed, it will be included in this object
+   *
+   * @returns {*}
+   */
+  modelChanges() {
+    let changed = Ember.assign({}, this.changedAttributes());
+    let trackerInfo = Tracker.metaInfo(this);
+    for (let key in trackerInfo) {
+      if (!changed[key] && trackerInfo.hasOwnProperty(key)) {
+        if (this.didChange(key, changed)) {
+          changed[key] = true;
+        }
+      }
+    }
+    return changed;
+  },
+
+  /**
+   * Rollback all the changes on this model, for the keys you are
+   * tracking.
+   *
+   * NOTE: Be sure you understand what keys you are tracking.
+   * By default, tracker will save all keys, but if you set up
+   * a model to 'only' track a limited set of keys, then the rollback
+   * will only be limited to those keys
+   *
+   */
+  rollback() {
+    const isNew = this.get('isNew');
+    this.rollbackAttributes();
+    if (isNew) { return; }
+    let trackerInfo = Tracker.metaInfo(this);
+    let rollbackData = Tracker.rollbackData(this, trackerInfo);
+    let normalized = Tracker.normalize(this, rollbackData);
+    this.store.push(normalized);
+  },
+
+  // alias for saveChanges method
+  startTrack() {
+    this.initTracking();
+    this.saveChanges();
+  },
+
+  // Ember Data DS.Model events
+  // http://api.emberjs.com/ember-data/3.10/classes/DS.Model/events
+  //
+  // Replaces deprecated Ember.Evented usage:
+  // https://github.com/emberjs/rfcs/blob/master/text/0329-deprecated-ember-evented-in-ember-data.md
+  // Related: https://github.com/emberjs/rfcs/pull/329
+
+  onIsNewChanged() {
+    if (this.isNew === false) {
+      this.saveOnCreate()
+      this.removeObserver('isNew', this, this.onIsNewChanged);
+    }
+  },
+
+  onIsDeletedChanged() {
+    if (this.isDeleted === true) {
+      this.clearSavedAttributes();
+    this.removeObserver('isDeleted', this, this.onIsDeletedChanged);
+    }
+  },
+
+  onIsLoadedChanged() {
+    this.setupTrackerMetaData();
+    this.setupUnknownRelationshipLoadObservers();
+    this.removeObserver('isLoaded', this, this.onIsLoadedChanged);
+  },
+
+  initTracking(){
+    // sync tracker with model on events like create/update/delete/load
+    if (this.isNew) {
+      this.addObserver('isNew', this, this.onIsNewChanged)
+    }
+    this.addObserver('isDeleted', this, this.onIsDeletedChanged)
+
+    if (!this.isLoaded) {
+      this.addObserver('isLoaded', this, this.onIsLoadedChanged);
+    }
+
+    // there is no didUpdate hook anymore and no appropriate model props to base on
+    // saveOnUpdate should be called after model has been saved
+    // right after model
+    Tracker.setupTracking(this);
+  },
+
+  /**
+   * Save the current state of the model
+   *
+   * NOTE: This is needed when manually pushing data
+   * to the store and ussing Ember < 2.10
+   *
+   * options like => {except: 'company'}
+   *
+   * @param {Object} options
+   */
+  saveChanges(options) {
+    Tracker.setupTracking(this);
+    Tracker.saveChanges(this, options);
+    Tracker.triggerIsDirtyReset(this);
+ },
+
+
+  saveTrackerChanges(options) {
+    this.saveChanges(options);
+  },
+
+  /**
+   * Get value of the last known value tracker is saving for this key
+   *
+   * @param {String} key attribute/association name
+   * @returns {*}
+   */
+  savedTrackerValue(key) {
+    return Tracker.lastValue(this, key);
+  },
+
+  // save state when model is loaded or created if using auto save
+  setupTrackerMetaData() {
+    if (Tracker.isIsDirtyEnabled(this)) {
+      // this is experimental
+      Tracker.initializeDirtiness(this);
+    }
+    if (Tracker.isAutoSaveEnabled(this)) {
+      this.saveChanges();
+    }
+  },
+
+  // watch for relationships loaded with data via links
+  setupUnknownRelationshipLoadObservers() {
+    this.eachRelationship((key) => {
+      this.addObserver(key, this, 'observeUnknownRelationshipLoaded');
+    });
+  },
+
+  // when model updates, update the tracked state if using auto save
+  saveOnUpdate() {
+    if (Tracker.isAutoSaveEnabled(this) || Tracker.isIsDirtyEnabled(this)) {
+      this.saveChanges();
+    }
+  },
+
+  // when model creates, update the tracked state if using auto save
+  saveOnCreate() {
+    if (Tracker.isAutoSaveEnabled(this) || Tracker.isIsDirtyEnabled(this)) {
+      this.saveChanges();
+    }
+  },
+
+  // There is no didReload callback on models, so have to override reload
+  reload() {
+    let promise = this._super(...arguments);
+    promise.then(() => {
+      if (Tracker.isAutoSaveEnabled(this)) {
+        this.saveChanges();
+      }
+    });
+    return promise;
+  },
+
+  // when model deletes, remove any tracked state
+  clearSavedAttributes() {
+    Tracker.clear(this);
+  },
+
+  observeUnknownRelationshipLoaded(sender, key/*, value, rev*/) {
+    if (Tracker.trackingIsSetup(this) && Tracker.isTracking(this, key)) {
+      let saved = Tracker.saveLoadedRelationship(this, key);
+      if (saved) {
+        this.removeObserver(key, this, 'observeUnknownRelationshipLoaded');
+      }
+    }
+  }
+});