underscore.db

Underscore.db

Adds functions to Underscore/Lo-Dash for manipulating database-like objects.

It adds get, insert, update, updateWhere, remove, removeWhere, save, load and createId and can be used in Node and the browser.

Data can be persisted using the filesystem or localStorage.

Live example

For a full JSON database built on Lo-Dash and Underscore.db, check LowDB.

Install

Node

$ npm install underscore underscore.db

var _ = require('underscore');
require('underscore.db').mixWith(_);

Browser

$ bower install underscore underscore.db

<script src="underscore.js" type="text/javascript"></script>
<script src="underscore.db.js" type="text/javascript"></script>

To use Underscore.db with Lo-Dash, just replace underscore with lodash

Usage example

Create an empty database object

var db = {
  posts: []
}

Create a post

var newPost = _.insert(db.posts, {title: 'foo'});

Display database console.log(db)

{ 
  posts: [
    {title: "foo", id: "5ca959c4-b5ab-4336-aa65-8a197b6dd9cb"}
  ]
}

Retrieve post using underscore.db get or underscore find method

var post = _.get(db.posts, newPost.id);

var post = _.find(db.posts, function(post) {
  return post.title === 'foo'
});

Persist

_.save(db);

API

The following database object is used in API examples.

var db = {
  posts: [
    {id: 1, body: 'one', published: false},
    {id: 2, body: 'two', published: true}
  ],
  comments: [
    {id: 1, body: 'foo', postId: 1},
    {id: 2, body: 'bar', postId: 2}
  ]
}

get

get(collection, id)

Finds and returns document by id or undefined.

var post = _.get(db.posts, 1);

insert

insert(collection, document)

Adds document to collection, sets an id and returns created document.

var post = _.insert(db.posts, {body: 'New post'});

update

update(collection, id, attrs)

Finds document by id, copies properties to it and returns updated document or undefined.

var post = _.update(db.posts, 1, {body: 'Updated body'});

updateWhere

updateWhere(collection, whereAttrs, attrs)

Finds documents using _.where, updates documents and returns updated documents or an empty array.

// Publish all unpublished posts
var posts = _.updateWhere(db.posts, {published: false}, {published: true});

remove

remove(collection, id)

Removes document from collection and returns it or undefined.

var comment = _.remove(db.comments, 1);

removeWhere

removeWhere(collection, whereAttrs)

Removes documents from collection using _.where and returns removed documents or an empty array.

var comments = _.removeWhere(db.comments, {postId: 1});

save

save(db, [destination])

Persists database using localStorage or filesystem. If no destination is specified it will save to db or ./db.json.

_.save(db);
_.save(db, '/some/path/db.json');

load

load([source])

Loads database from localStorage or filesystem. If no source is specified it will load from db or ./db.json.

var db = _.load();
var db = _.load('/some/path/db.json');

id

Overwrite it if you want to use another id property.

_.id = '_id';

createId

createId(collectionName, doc)

Called by Underscore.db when a document is inserted. Overwrite it if you want to change id generation algorithm.

_.createId = function(collectionName, doc) {
  return collectionName + '-' + doc.name + '-' + _.random(1, 9999);
}

FAQ

How to query?

Everything you need for querying is present in Underscore and Lo-Dash: where, find, map, reduce, filter, reject, sortBy, groupBy, countBy, ...

See http://underscorejs.org/ or http://lodash.com/docs.

Example:

// Using Underscore
var topFivePosts = _(db.posts)
  .chain()
  .where({published: true})
  .sortBy(function(post) {
     return post.views;   
   })
  .first(5)
  .value();

// Using Lo-Dash
var topFivePosts = _(db.posts)
  .where({published: true})
  .sortBy('views')
  .first(5)
  .value();

How to reduce file size?

With Lo-Dash, you can create optimal builds and include just what you need.

Minimal build for Underscore.db to work (~2kb min gzipped):

$ npm install -g lodash-cli
$ lodash underscore include=find,where,clone,indexOf

For more build options, see http://lodash.com/custom-builds.

License

Underscore.db is released under the MIT License.