Napoleonic Political Magnificence
    Wondering what’s next for npm?Check out our public roadmap! »

    diskdb

    0.1.17 • Public • Published

    diskDB Build Status NPM version Gitter

    NPM

    A Lightweight Disk based JSON Database with a MongoDB like API for Node.

    You will never know that you are interacting with a File System

    Contents

    Getting Started

    Install the module locally :

    $ npm install diskdb
    var db = require('diskdb');
    db = db.connect('/path/to/db-folder', ['collection-name']);
    // you can access the traditional JSON DB methods here

    Documentation

    Connect to DB

    db.connect(pathToFolder, ['filename']);

    Filename will be the name of the JSON file. You can omit the extension, diskDB will take care of it for you.

    var db = require('diskdb');
    db = db.connect('/examples/db', ['articles']);
    // or simply
    db.connect('/examples/db', ['articles']);

    This will check for a directory at given path, if it does not exits, diskDB will throw an error and exit.

    If the directory exists but the file/collection does not exist, diskDB will create it for you.

    Note : If you have manually created an empty JSON file, please make sure that it contains at least an empty array.

    []

    Else it will throw an error like

    undefined:0
     
    ^
    SyntaxError: Unexpected end of input

    Load Collections

    Alternatively you can also load collections like

    var db = require('diskdb');
    // this
    db = db.connect('/examples/db');
    db.loadCollections(['articles']);
    //or
    db.connect('/examples/db');
    db.loadCollections(['articles']);
    //or
    db.connect('/examples/db')
      .loadCollections(['articles']);
    //or
    db.connect('/examples/db', ['articles']);

    Load Multiple Collections

    var db = require('diskdb');
    db.connect('/examples/db', ['articles','comments','users']);

    Write/Save to Collection

    db.collectionName.save(object);

    Once you have loaded a collection, you can access the collection's methods using the dot notation like

    db.[collectionName].[methodname]

    To save the data, you can use

    var db = require('diskdb');
    db.connect('db', ['articles']);
    var article = {
        title : "diskDB rocks",
        published : "today",
        rating : "5 stars"
    }
    db.articles.save(article);
    // or
    db.articles.save([article]);

    The saved data will be

    [
        {
            "title": "diskDB rocks",
            "published": "today",
            "rating": "5 stars",
            "_id": "0f6047c6c69149f0be0c8f5943be91be"
        }
    ]

    You can also save multiple objects at once like

    var db = require('diskdb');
    db.connect('db', ['articles']);
    var article1 = {
        title : 'diskDB rocks',
        published : 'today',
        rating : '5 stars'
    }
     
    var article2 = {
        title : 'diskDB rocks',
        published : 'yesterday',
        rating : '5 stars'
    }
     
    var article3 = {
        title : 'diskDB rocks',
        published : 'today',
        rating : '4 stars'
    }
    db.articles.save([article1, article2, article3]);

    And this will return the inserted objects

    [ { title: 'diskDB rocks',
        published: 'today',
        rating: '4 stars',
        _id: 'b1cdbb3525b84e8c822fc78896d0ca7b' },
      { title: 'diskDB rocks',
        published: 'yesterday',
        rating: '5 stars',
        _id: '42997c62e1714e9f9d88bf3b87901f3b' },
      { title: 'diskDB rocks',
        published: 'today',
        rating: '5 stars',
        _id: '4ca1c1597ddc4020bc41b4418e7a568e' } ]

    Read from Collection

    There are 2 methods available for reading the JSON collection

    • db.collectionName.find(query)
    • db.collectionName.findOne(query)

    db.collectionName.find()

    var db = require('diskdb');
    db.connect('/examples/db', ['articles']);
    db.articles.find();

    This will return all the records

    [{
        title: 'diskDB rocks',
        published: 'today',
        rating: '5 stars',
        _id: '0f6047c6c69149f0be0c8f5943be91be'
    }]

    You can also query with a criteria like

    var db = require('diskdb');
    db.connect('/examples/db', ['articles']);
    db.articles.find({rating : "5 stars"});

    This will return all the articles which have a rating of 5.

    Find can take multiple criteria

    var db = require('diskdb');
    db.connect('/examples/db', ['articles']);
    db.articles.find({rating : "5 stars", published: "yesterday"});

    This will return all the articles with a rating of 5, published yesterday.

    Nested JSON :

    var articleComments = {
        title: 'diskDB rocks',
        published: '2 days ago',
        comments: [{
            name: 'a user',
            comment: 'this is cool',
            rating: 2
        }, {
            name: 'b user',
            comment: 'this is ratchet',
            rating: 3
        }, {
            name: 'c user',
            comment: 'this is awesome',
            rating: 2
        }]
    }
    var savedArticle = db.articles.save([articleComments);
    foundArticles = db.articles.find({rating : 2});

    Since diskDB is mostly for light weight data storage, avoid nested structures and huge datasets.

    db.collectionName.findOne(query)

    var db = require('diskdb');
    db.connect('/examples/db', ['articles']);
    db.articles.findOne();

    If you do not pass a query, diskDB will return the first article in the collection. If you pass a query, it will return first article in the filtered data.

    var db = require('diskdb');
    db.connect('/examples/db', ['articles']);
    db.articles.findOne({_id: '0f6047c6c69149f0be0c8f5943be91be'});

    Update Collection

    db.collectionName.update(query, data, options);

    You can also update one or many objects in the collection

    options = {
        multi: false, // update multiple - default false
        upsert: false // if object is not found, add it (update-insert) - default false
    }

    Usage

    var db = require('diskdb');
    db.connect('/examples/db', ['articles']);
     
    var query = {
      title : 'diskDB rocks'
    };
     
    var dataToBeUpdate = {
      title : 'diskDB rocks again!',
    };
     
    var options = {
       multi: false,
       upsert: false
    };
     
    var updated = db.articles.update(query, dataToBeUpdate, options);
    console.log(updated); // { updated: 1, inserted: 0 }

    Remove Collection

    db.collectionName.remove(query, multi);

    You can remove the entire collection (including the file) or you can remove the matched objects by passing in a query. When you pass a query, you can either delete all the matched objects or only the first one by passing multi as false. The default value of multi is true.

    var db = require('diskdb');
    db.connect('/examples/db', ['articles']);
    db.articles.remove({rating : "5 stars"});
    var db = require('diskdb');
    db.connect('/examples/db', ['articles']);
    db.articles.remove({rating : "5 stars"}, true); // remove all matched. Default - multi = true
    var db = require('diskdb');
    db.connect('/examples/db', ['articles']);
    db.articles.remove({rating : "5 stars"}, false); // remove only the first match

    Using remove without any params will delete the file and will remove the db instance.

    var db = require('diskdb');
    db.connect('/examples/db', ['articles']);
    db.articles.remove();

    After the above operation db.articles is undefined.


    Count

    db.collectionName.count();

    Will return the count of objects in the Collection

    var db = require('diskdb');
    db.connect('/examples/db', ['articles']);
    db.articles.count(); // will give the count

    Examples

    Refer to the examples folder.

    Performance

    To validate diskDB's performance and to check if it meets your needs, you can clone this repo and run

    $ node performance/time.js

    An average of few tests (run on OS X - 10.9.3 | 2.9GHZ i7 | 8GB 1600MHz DDR3) can be found below

    Time taken to process x number of objects (in ms) vs Action Performed

    # of objects 1 1000 10000 100000 1000000
    Save 1 ms 15 ms 137 ms 1728 ms 14425 ms
    Find all without query 0 ms 2 ms 12 ms 204 ms 2923 ms
    Find all with query 0 ms 2 ms 17 ms 738 ms 1985 ms
    Find one without query 0 ms 1 ms 9 ms 791 ms 1676 ms
    Find one with query 0 ms 1 ms 8 ms 219 ms 1410 ms
    Update all records 1 ms 7 ms 61 ms 206 ms 48035 ms
    Get count 0 ms 3 ms 11 ms 260 ms 2420 ms
    Remove with query 0 ms 7 ms 59 ms 984 ms 48191 ms
    Remove collection 0 ms 1 ms 4 ms 52 ms 154 ms
    File size 0.000111 MB 0.116671 MB 1.196671 MB 12.26667 MB 125.66667 MB

    Contributing

    See the CONTRIBUTING Guidelines

    Release History

    • 0.1.x
      • Base Module with
        • Connect to a Folder
        • Access a Collection/File
        • Create Read Update Delete on JSON object
        • Minor fixes and tests
        • Performance improvements

    License

    Copyright (c) 2014 Arvind Ravulavaru. Licensed under the MIT license.

    Install

    npm i diskdb

    DownloadsWeekly Downloads

    389

    Version

    0.1.17

    License

    MIT

    Last publish

    Collaborators

    • avatar