backbone-model-factory

Backbone.ModelFactory

Provides a function for generating model constructors which will never produce multiple instances with the same unique identifier.

When you create a new instance of a model created with Backbone.ModelFactory and give it an id it will never create duplicate instances of the same model with a given id.

var user1 = new User({id: 1});
var user2 = new User({id: 1});
var user3 = new User({id: 2});

console.log(user1 === user2); // true
console.log(user3 === user1); // false

Benefits

When architecting loosely-coupled web applications, it is generally considered a good practice for modules which control separate pieces of functionality to not rely on each other. ModelFactory helps with that!

Using ModelFactory models, you can eliminate the need to pass model instances between unrelated views.

Additionally, collections using ModelFactory models that fetch data will always be populated by existing model instances if they already exist in the cache. This prevents creating multiple model instances which represent the same resource.

ModelFactory makes sharing models between collections, views, routers, etc. almost completely hands-off.

Demo

Coming soon!

Dependencies

Backbone.ModelFactory 1.2.0+ depends on the following libraries:

• Underscore: tested against 1.5.2, but 1.2.0+ should work
• Backbone: 0.9.9+

Earlier versions of ModelFactory will work with Backbone 0.9.0-1.0.0 and do not depend on Underscore directly.

Inclusion

Backbone.ModelFactory supports three methods of inclusion.

1. Node:

    var Backbone = require('backbone-model-factory');
   

2. AMD/RequireJS:

    require(['backbone-model-factory'], function (Backbone) {
        // Do stuff...
    });
   

3. Browser Globals:

    <script src="path/to/backbone.js"></script>
    <script src="path/to/backbone-model-factory.js"></script>
   

Usage

Rather than extending Backbone.Model, constructors are created by a call to Backbone.ModelFactory. Instead of this:

var User = Backbone.Model.extend({
  defaults: {
    firstName: 'John',
    lastName: 'Doe'
  }
});

...do this:

var User = Backbone.ModelFactory({
    defaults: {
        firstName: 'John',
        lastName: 'Doe',
        isAdmin: false
    }
});

ModelFactory also supports inheritance, so model constructors can extend each other by providing a model constructor (whether generated by ModelFactory or not) as the first argument:

var Admin = Backbone.ModelFactory(User, {
    defaults: _.extend({}, User.prototype.defaults, {
        isAdmin: true
    })
});

Consequences of Extending Models

Models created with ModelFactory will not share their unique-enforcement capabilities with models which they extend or which extend them. For example, using the User and Admin models above giving each the same id would not result in the same object:

var user = new User({id: 1});
var admin = new Admin({id: 1});

console.log(user === admin); // false

Potential Gotchas

Recursion and Relations

If you are doing any sort of recursive relationships (models or collections within models) and then serializing those relationships you can run into some complex recursion-related problems. Also, I have not tried this library with Backbone-Relational, so use at your own risk!

Caching and Wiping

Since model instances are cached, the potential exists for unneeded objects to hang around in memory.

As of ModelFactory 1.2.0 you can wipe model instances once you are done with them. Both the model instances themselves and the constructor function have a wipe method which can be used:

var User = Backbone.ModelFactory();

var jake = new User({id: 1});
var joe1 = new User({id: 2});
var joe2 = new User({id: 2});
var jane = new User({id: 3});
var jen = new User({id: 4});
var josh = new User({id: 5});
var james = new User({id: 6});

// Wipe the instance of User with id: 2 from cache. "jake" will still exist in memory.
jake.wipe();

// Wipe a single cached instance from the model. "joe1" and "joe2" will still exist in memory.
User.wipe(joe);

// Wipe multiple cached instances in an array or a collection. As before, "jane", "jen", "josh", and "james" exist in memory still.
User.wipe([jane, jen]);
User.wipe(new Backbone.Collection([josh, james]));

console.log(_.keys(User._cache).length); // 0

Note: This will only remove them from the internal cache - any references in your views, collections, or elsewhere will not be deleted!

In the example here, all the local variables ("jake", "joe1", etc) will be garbage collected, but it's up to the developer to clean up references from his/her view, collection, etc. objects.

Tests

Inclusion

There are 3 files in /test/inclusion and they account for the 3 supported methods of including this module. To execute these tests, simply open the HTML files in a browser or install the npm module backbone and run node node-module.js.

Unit

Jasmine tests exist in test/test.js. To run, simply open test/index.html in a browser and choose a Backbone version to test against.

Inspriation

This is inspired by SoundCloud's approach detailed in Building the Next SoundCloud under "Sharing Models between Views."