mg

Model synchronization / hydration library

npm install mg
32 downloads in the last week
106 downloads in the last month

mg - a model synchronization library

  • Hydrates models with their 1:1 & 1:N associations. Models may be related to one or more other objects, and fetching each associated manually is painful.
  • Ensures that only one instance exists for each model class + id pair. This ensures that updates made to a model in one part of a system are reflected in another.
  • Data type assurance. Ensures that model properties with specific data types such as Dates and Regexps are always of the expected type.
  • Cache preloading. Allows you to transmit a set of models as JSON data with your initial page load. These will be used from the cache, reducing the number of HTTP requests needed during page load.

Getting started

Define model relations

To set up mg hydration, define a rels property. For example, to have Post.author be hydrated as an instance of Person:

var Post = Backbone.Model.extend({
  url: function()  {
    return '/posts/' + this.id;
  },
  collection: 'Posts', // <= collections of Post are created using the associated Collection (or Backbone.Collection by default)
  rels: {
    comment: { type: 'Comment' } // <= convert the comment field to a instance of Comment or a Collection of Comments
  }
});

mg.define('Post', Post);

var Posts = Backbone.Collection.extend({
  url: '/posts'
});

mg.define('Posts', Posts);

The mg.define() call registers the model with hydration, so that relations can find the right model class and metadata.

mg supports both one-to-one, one-to-many and many-to-one relations. You do not need to explicitly define the type of relation, as it will be inferred from the JSON data.

Find models and collections

findById(name, id, rels, onDone): retrieves a model by id. Reads the model from model.url + / + id.

stream(name, rels, onDone): retrieves a model by id. Reads the model from model.url + / + id.

Example:

// Fetch a model
// Note you can specify which related objects to load dynamically.
mg.findById('Project', 1, { rels: 'Script' } function(err, project) {
    // And then retrieve those related objects using .get
    var script = project.get('script');
});

// Fetch a collection
mg.stream('Post', { rels: 'Comment' } function(err, project) {
    // And then retrieve those related objects using .get
    var script = project.get('script');
});

Alternatively, you can use model.fetch() and collection.fetch() and call hydrate on the result.

Example model.fetch()/collection.fetch():

project.fetch({ data: { rels: ['script', 'dataset'] }}).done(function(data) {
  mg.hydrate('Post', post, data);
  var script = project.get('script');
});

The URL is determined using model.url, following the Backbone conventions.

Models are cached in-memory. This means that you should always use .findById(), since it will retrive the model from cache if possible.

Example:

// comment1 and comment2 are instances of Comment
project.link([comment1, comment2], function(err) {
  // comment to project link has been saved
});

Example:

// comment1 is an instance of Comment
project.unlink(comment1, function(err) {
  // comment to project link has been removed
});
npm loves you