backbone-model-factory

KO | EN

gitlite — search

#typescript #ai-agents #deepseek-harness #dsh-plugin #open-source #ai #cli #dsh #claude-code #codex #developer-tools #react

backbone-model-factory

★ 68 Open GitHub ↗

Provides a factory for generating model constructors that will never produce multiple instances of a model with the same unique identifier.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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`.

```js
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.

## Dependencies

`Backbone.ModelFactory` 1.2.0+ depends on the following libraries:

- Underscore: 1.2.0+
- 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:

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

2. AMD/[RequireJS](http://requirejs.org):

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

3. Browser Globals:

```html
  <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:

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

...do this:

```js
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:

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

### Consequences of Extending Models

Models created with `ModelFactory` will __not__ share their unique-enforcement behavior 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:

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

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

Subclassing to achieve different `defaults` is usually a bad idea. The `User`/`Admin` example models are not intended to be an example of good practices. :)

## Potential Gotchas

### Relationships and Recursion

If you are using any sort of nested relationships (models or collections within models) and operating on those relationships in a recursive manner, it can cause an infinite loop if an identical model instance exists in its own relationship graph.

For example, let's say a User has a collection of Posts and each Post has a User. Having an infinite path of object references (User -> Posts -> Post -> User -> Posts -> ad infinitum) is not harmful, but if you do any _automated/recursive serialization_ of these relationships (into JSON, etc), you might encounter an infinite loop if the serialization is unchecked.

This entirely depends on how you're using Backbone and what you've built upon it.

### 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:

```js
var User = Backbone.ModelFactory();

// 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! To manage _your_ references to models, hook into the various wipe events...

#### Cleaning up Your References with Wipe Events

Inspired by an issue raised by GitHub user @niksy, starting in `ModelFactory` 1.3.0, developers can clean up their own model references easily using wipe events. These are triggered with the following logic:

- Calling `model.wipe()` will trigger `"wipe"` on that instance. The instance is passed as an argument to any callback(s).
  - Calling `model.wipe()` will also trigger the model/constructor-level events (see below).
- Calling `MyModel.wipe()` will trigger individual `"wipe"` events on every instance being wiped and...
  - If no models are wiped, no events are fired.
  - If wiping all instances (one or more), trigger `"wipe:all"`.
  - If wiping fewer than all, trigger `"wipe:some"`.
  - In both cases, callbacks receive the following arguments:
    - `Constructor`: The model constructor on which the event was triggered. In this case, `MyModel`.
    - `models`: An array of models that were removed from the cache.
    - `remainder`: An array of models remaining in the cache (empty in the case of `"wipe:all"`).

In all cases, `{silent: true}` will be respected.

```js
var User = Backbone.ModelFactory();

var jake = new User({id: 1});
var jane = new User({id: 2});
var jen = new User({id: 3});
var josh = new User({id: 4});

// Triggers "wipe" on jake.
// Triggers "wipe" and "wipe:some" on User with arguments:
//   - [User, [jake], [jane, jen, josh]]
jake.wipe();

// Triggers individual "wipe" events on jane, jen, and josh. 
// Triggers "wipe" and  "wipe:all" on User with arguments:
//   - [User, [jane, jen, josh], []];
User.wipe([jane, jen, josh]);
```

## 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 dependencies and run `node test/inclusion/node-module.js`.

### Unit

[Mocha](http://mochajs.org/) tests exist in `test/test.js`.

To run the tests, make sure development dependencies are installed and use `npm test`.

To test against different versions of Backbone (or Underscore), install the version desired (e.g., `npm install backbone@~1.0.0`).

## Inspriation

This is inspired by SoundCloud's approach detailed in [Building the Next SoundCloud](http://backstage.soundcloud.com/2012/06/building-the-next-soundcloud/) under "Sharing Models between Views."

backbone-model-factory

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README