Brainstem.js

Brainstem.js is a companion library for Backbone.js that makes integration with Brainstem APIs a breeze. Brainstem.js adds an identity map and relational models to Backbone.

Brainstem is designed to power rich APIs in Rails. The Brainstem gem provides a presenter library that handles converting ActiveRecord objects into structured JSON and a set of API abstractions that allow users to request sorts, filters, and association loads, allowing for simpler implementations, fewer requests, and smaller responses.

• Speaks natively to Brainstem APIs
• Provides a caching layer to avoid loading already-available records
• Adds relational models in Backbone, allowing you to setup has_one, has_many, and belongs_to relationships
• Supports Brainstem association side-loading of multiple objects for fast, single-request workflows
• Interprets the Brainstem server API results array and hashes for you, abstracting away the Brainstem JSON protocol

npm install --save brainstem-js

Brainstem.js models and collections behave very similarly to Backbone models and collections. However, in Brainstem.js models have the ability to specify associations that map to other Brainstem models in the StorageManager. These associations leverage the power of the Brainstem server API to facilitate side-loading related data in a single fetch.

Sub-class Brainstem.js collections and models for each Brainstem server endpoint to map client-side Brainstem.js models to your Brainstem server-side models.

Assocations are defined as a map in the class property associations to declare the mapping between association names and StorageManager collections where the data can be located.

• Strings inidicate has_one or belongs_to relationships
• Arrays with a single item indicate has_many relationships
• Arrays with multiple items indicate polymorphic belongs_to relationships

Model:

BrainstemModel = require('brainstem-js').Model;

Post = BrainstemModel.extend({
  paramRoot: 'post',
  brainstemKey: 'posts',
  urlRoot: '/api/v1/posts'
}, {
  associations: {
    user: 'users', // has_one
    comments: ['comments'], // has_many
    account: 'accounts', // belongs_to
    parent: ['category', 'post'] // belongs_to (polymorphic)
  }
});

module.exports = Post;

Collection:

BrainstemCollection = require('brainstem-js').Collection;
Post = require('./models/post');

Posts = BrainstemCollection.extend({
  model: Post,
  url: '/api/v1/posts'
});

module.exports = Posts;

Model:

Application.Models.Post = Brainstem.Model.extend({
  paramRoot: 'post',
  brainstemKey: 'posts',
  urlRoot: '/api/v1/posts'
}, {
  associations: {
    user: 'users', // has_one
    comments: ['comments'], // has_many
    account: 'accounts', // belongs_to
    parent: ['category', 'post'] // belongs_to (polymorphic)
  }
});

Collection:

Application.Collections.Posts = Brainstem.Collection.extend({
  model: Application.Models.Post,
  url: '/api/v1/posts'
});

The Brainstem.js StorageManager is the data store in charge of loading data from a Brainstem API as well as managing cached data. The StorageManager should be set up when your application starts.

Use the StorageManager addCollection API to register Brainstem.js collections that map to your Brainstem server API endpoints.

storageManager.addCollection([brainstem key], [collection class])

Note: The StorageManager is implemented as a singleton. The StorageManager instance can be obtained using StorageManager.get(). Once instantiated the manager instance will maintain state and cache throughout the duration of your application's runtime.

StorageManager = require('brainstem-js').StorageManager;
Users = require('./collections/users');
Posts = require('./collections/posts');

storageManager = StorageManager.get();
storageManager.addCollection('users', Users);
storageManager.addCollection('posts', Posts);
storageManager.addCollection('comments', Comments);

Application = {};

Application.storageManager = Brainstem.StorageManager.get();
Application.storageManager.addCollection('users', Application.Collections.Users);
Application.storageManager.addCollection('posts', Application.Collections.Posts);
Application.storageManager.addCollection('comments', Application.Collections.Comments);

Brainstem.js extends the Backbone fetch API so requesting data from a Brainstem API should be familiar to fetching data from any RESTful API using just Backbone.

In addition to basic REST requests, the Brainstem.js model fetch method supports an include option to side-load associated model data.

Post = require('./models/post');

new Post({ id: 1 })
  .fetch({ include: ['user', 'comments'] })
  .done(/* handle result */)
  .fail(/* handle error */);

Brainstem also supports requesting deeply nested associations. Under the hood, Brainstem makes recursive requests for each layer of associations. There are three ways to make this kind of request, using JSON-like Objects, Backbone Collections or BrainstemParams. Using Backbone Collections or BrainstemParams enables expressing additional options for the nested includes / associations.

Post = require('./models/post');

new Post({ id: 1 })
  .fetch({
    include: [
      'user',
      { comments: ['replies', 'ratings'] }
    ]
  })
  .done(/* handle result */)
  .fail(/* handle error */);

Post = require('./models/post');
Comments = require('./collections/comments')

var comments = new Comments(null, {
  include: ['replies', 'ratings'],
  filters: { only_by_user_id: 1 }
});

new Post({ id: 1 })
  .fetch({ include: ['user', { comments: comments }] })
  .done(/* handle result */)
  .fail(/* handle error */);

In this example we are able to specify a filter for the comments association. With the filter, we can request comments for the post filtered by user_id 1. Here, comments needs to be the name of the association

Post = require('./models/post');

var commentsParams = {
  brainstemParams: true,
  include: ['replies', 'ratings'],
  filters: { only_by_user_id: 1 }
};

new Post({ id: 1 })
  .fetch({ include: ['user', { comments: commentsParams }] })
  .done(/* handle result */)
  .fail(/* handle error */);

Similar to the Backbone Collection example, again with brainstemParams, we can include additional options for any association.

In addition to basic REST requests, the Brainstem.js model fetch method supports additional Brainstem options:

• Pagination using page and perPage, or offset and limit
• Filtering using filters object
• Ordering user order string

Posts = require('./collections/posts');

new Posts().fetch({
  page: 1,
  perPage: 10,
  order: 'date:desc',
  filters: {
      title: 'collections',
      description: 'fetching'
    }
  })
  .done(/* handle result */)
  .fail(/* handle error */);

Post = require('./models/post');
User = require('./models/user');

var user;
var comments;
var reviews;
var userCollection = new User([], { include: 'reviews' });

new Post({ id: 1 }).fetch({ include: ['comments', { user: userCollection }] })
  .done(function (post) {
  	user = post.get('user');
  	reviews = user.get('reviews');
  	comments = post.get('comments');
  });

console.log(user);
// User [BackboneModel]

console.log(comments);
// Comments [BackboneCollection]

console.log(reviews);
// Reviews [BackboneCollection]

Brainstem.js collections provide a filter scoping mechanism that allows a base scope to be defined either by providing base filter and order options to the Brainstem.js Collection constructor, or by passing said options to the first fetch call.

The collection can be restored to the original base scope by simply invoking fetch on the collection without passing any options.

The base scope is stored in the firstFetchOptions property on the collection and the current filter scope is stored in the lastFetchOptions property on the collection.

Posts = require('./collections/posts');

posts = new Posts([], { filters: { account_id: 1 } });

console.log(posts.firstFetchOptions);
// { filters: { account_id: 1 } }

// Base scope fetch

posts.fetch()
  .done(function (posts) {
  	console.log(posts);
  	// Posts [Brainstem Collection] – all posts filtered by `account_id`
  });

// Further scoped fetch

posts.fetch({ filters: { user_id: 1 }, order: 'updated_at:desc' })
  .done(function (posts) {
  	console.log(posts);
  	// Posts [Brainstem Collection] – all posts filtered by `account_id` and `user_id` ordered by `updated_at`
  });

// Restoring base scope

posts.fetch()
  .done(function (posts) {
  	console.log(posts);
  	// Posts [Brainstem Collection] – all posts filtered by `account_id` in default order
  });

Backbone.js collections support pagination natively. The default page size is 20.

As mentioned, collections support both page and perPage options or offset and limit options. If no pagination options are specified, collections will default to page and perPage options. The offset and limit paginations options can be substitued in any of the following examples.

Supported pagination methods:

• getNextPage()
• getPreviousPage()
• getFirstPage()
• getLastPage()
• getPage([page number])

Posts = require('./collections/posts');

posts = new Posts([], page: 1, perPage: 10);

console.log(posts.firstFetchOptions);
// { page: 1, perPage: 10 }

posts.fetch()
  .done(function (posts) {
  	console.log(posts.pluck('id');
  	// [1, 2, 3, 4, 5, 6, 7, 8, 9 , 10]
  });

posts.getNextPage()
  .done(function (posts) {
  	console.log(posts.pluck('id');
  	// [11, 12, 13, 14, 15, 16, 17, 18, 19 , 20]
  });

posts.getPreviousPage()
  .done(function (posts) {
  	console.log(posts.pluck('id');
  	// [1, 2, 3, 4, 5, 6, 7, 8, 9 , 10]
  });

// The Backbone.Collection `add` option can be utilized for "load more" style pagination

posts.getNextPage({ add: true })
  .done(function (posts) {
  	console.log(posts.pluck('id');
  	// [1, 2, 3, 4, 5, 6, 7, 8, 9 , 10, 11, 12, 13, 14, 15, 16, 17, 18, 19 , 20]
  });

We're always open to pull requests!

• Node

yarn install

To use this module as a symbolic link, run:

yarn install

which runs yarn prepublish.

To run the specs on the command line, run:

yarn test

To run the specs in a server with live code reloading and compilation:

yarn test-watch

1. Use an NPM account (with 2FA enabled) on the Mavenlink organization
2. Run yarn install to update dependencies
3. Modify the semantic version appropriately as a commit
4. Make a pull request with said changes
5. If using a pre-release tag, run yarn publish to publish the alpha version to NPM
6. Request a review (and merge accordingly)
7. Run yarn publish on master to publish the latest release version to NPM

Note: it might be worthwhile to publish a prerelease tag during normal development to test changes sooner rather than later.

Brainstem and Brainstem.js were created by Mavenlink, Inc. and are available under the MIT License.