0.12.2 • Public • Published

    underscore-db Build Status NPM version

    Adds functions to Underscore/Lodash 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.



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

    Tip underscore-db is also compatible with underscore

    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'




    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, '/some/path/db.json');


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


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


    How to query?

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

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


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

    How to reduce file size?

    With Lodash, you can create custom builds and include just what you need.

    $ npm install -g lodash-cli
    $ lodash include=find,forEach,indexOf,filter,has

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


    See details changes for each version in the release notes.


    underscore-db is released under the MIT License.


    npm i underscore-db

    DownloadsWeekly Downloads






    Last publish


    • typicode