ef4 / ember-data-relationship-tracker

Ember-data-relationship-tracker

Track ember data relationships to know if records are dirty.

Problem

isDirty works great on ember data records if any of the attributes have changed. But it doesn't track relationship changes at all. This is because relationships are very complex and it's very hard to know if they are actually dirty or if they've just changed to reflect server state, e.g. because a new related record has been loaded.

Solution

ember-data-relationship-tracker allows you to explicitly mark pieces of code where you might change relationships. This gives you a hasDirtyFields property on your models that lets you know if any attributes or relationships have changed so you can reflect this in your UI.

In order to safely distinguish new versions from the server vs new edits in the client, you must provide a relationshipTrackerVersion field on your model. It can be a computed property or a real field, but it must be a unique value that changes whenever the server provides a new version.

Example

// ../models/post.js
export default class PostModel extends Model {
  @hasMany('comment') comments;
  @attr('version') version;

  // Add alias for relationship tracker 
  @alias('version') relationshipTrackerVersion;
}

// watch a section of code that might change relationships
post.watchRelationship('comments', () => {
  post.set('comments', someComments);
});

post.get('hasDirtyFields'); // true if comments has changed (or any other attribute has changed)

// rollback relationships to previous state
post.rollbackRelationships();

Works for belongsTo and hasMany relationships, and also knows if you set the relationships back to the original state and sets the property to false again.

See the tests for more examples.

Installation

• git clone <repository-url> this repository
• cd ember-data-relationship-tracker
• npm install

Linting

• npm run lint:js
• npm run lint:js -- --fix

Running tests

• ember test – Runs the test suite on the current Ember version
• ember test --server – Runs the test suite in "watch mode"
• ember try:each – Runs the test suite against multiple Ember versions

Running the dummy application

• ember serve
• Visit the dummy application at http://localhost:4200.

For more information on using ember-cli, visit https://ember-cli.com/.

License

This project is licensed under the MIT License.

ember-data-relationship-tracker's Issues

Improvement: Add an example model setup to README

Overview

Add an example model setup to README

Why is this needed?

Currently there is some misleading information in the README. First, the README states that you need a version field on your model, when you really need a relationshipTrackerVersion variable.

Second, I think the documentation could be improved by providing users with an example model setup.

As an edrt user I need a way to clear all relationships on save regardless of whether my relationshipTrackerVersion updates

Overview

As an edrt user I need a way to clear all relationships on save regardless of whether my relationshipTrackerVersion updates.

Why is this needed?

Let's say we have a Post model and a Comment model. The Post model has a hasMany relationship on comments. In my case when I save a post with related comments, and a comment changes, the version of the changed comments increments, while the Post version stays the same. The problem is that this causes the Post model to remain in a state where hasDirtyFields is true.

Implementation Details

I think we need a way to allow the user to indicate that the relationshipTracker should be reset after a save. For example, I am doing this in a current model that is being affected by this issue:

clearRelationshipTracking() {
    this._relationshipTracker = Object.create(null);
    this.notifyPropertyChange('relationshipTrackerVersion');
  },

I am then calling clearRelationshipTracking any time I perform a save on the Post model.

Depends on server-provided "changed" version

This addon was an extraction from an app, and I've realized that it is depending on some behavior of that app's particular server: it expects the server to set a changed timestamp on each record.

We can it adjust it to not depend on that, but as it is it won't work right with servers that don't do this.