Adds DB like functions to Underscore/Lo-Dash
JavaScript
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
dist
src Implement new "insert" method that aborts when item is a duplicate Aug 25, 2016
test
.gitignore
.npmignore
.travis.yml
Gruntfile.js
LICENSE
README.md Add documentation for "upsert" method Aug 25, 2016
bower.json
package.json

README.md

underscore-db Build Status NPM version

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

It adds:

  • getById
  • insert
  • upsert
  • updateById
  • updateWhere
  • replaceById
  • removeById
  • removeWhere
  • save
  • load
  • createId

Data can be persisted using the filesystem or localStorage.

Live example

Tip You can extend LowDB with underscore-db.

Install

Node

$ npm install underscore underscore-db
var _   = require('underscore');
var _db = require('underscore-db');

_.mixin(_db);

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 = _.getById(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}
  ]
}

getById(collection, id)

Finds and returns document by id or undefined.

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

insert(collection, document)

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

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

If the document already has an id, and it is the same as an existing document in the collection, an error is thrown.

_.insert(db.posts, {id: 1, body: 'New post'});
_.insert(db.posts, {id: 1, title: 'New title'}); // Throws an error

upsert(collection, document)

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

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

If the document already has an id, it will be used to insert or replace.

_.upsert(db.posts, {id: 1, body: 'New post'});
_.upsert(db.posts, {id: 1, title: 'New title'});
_.getById(db.posts, 1); // {id: 1, title: 'New title'}

updateById(collection, id, attrs)

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

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

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

replaceById(collection, id, attrs)

Finds document by id, replaces properties and returns document or undefined.

var post = _.replaceById(db.posts, 1, {foo: 'bar'});

removeById(collection, id)

Removes document from collection and returns it or undefined.

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

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(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([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(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 custom 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,forEach,indexOf

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

Changelog

See details changes for each version in the release notes.

License

underscore-db is released under the MIT License.