npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

brainstem-js

v0.9.1

Published

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.

Downloads

557

Readme

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.

build status npm version npm downloads Gitter

Why Brainstem.js?

  • 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

Installation

NPM

npm install --save brainstem-js

Usage

Models and Collections

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.

Model associations

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

Examples

CommonJS

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;
Vanilla JavaScript

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'
});

StorageManager

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.

Examples

CommonJS
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);
Vanilla JavaScript
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);

Note: all following examples assume a CommonJS environment, however the same functionality applies to vanilla JavaScript environments


Fetching data

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.

Models

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

Example
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.

JSON-like Object Example
Post = require('./models/post');

new Post({ id: 1 })
  .fetch({
    include: [
      'user',
      { comments: ['replies', 'ratings'] }
    ]
  })
  .done(/* handle result */)
  .fail(/* handle error */);
Backbone Collection Example
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

brainstemParams Example
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.

Collections

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
Example
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 */);

Accessing Model Associations

Example
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]

Manipulating Collections

Filter Scoping

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.

Example
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
  });

Pagination

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])
Example
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]
  });

Development

We're always open to pull requests!

Dependencies

Development Environment

yarn install

yarn link usages

To use this module as a symbolic link, run:

yarn install

which runs yarn prepublish.

Running Specs

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

Publishing

  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.

License

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