diskdb / 0.1.14 last updated a month ago created on Jun 14th 2014

Install

npm install --save diskdb

Clone

git clone git@github.com:arvindr21/diskdb.git

dependencies show all 7

main chalk 0.4.0 MIT
node-uuid 1.4.1 MIT
merge 1.1.3 MIT

maintainers

arvindr21

versions 15 total

0.1.14 a month ago arvindr21
0.1.13 a month ago arvindr21
0.1.12 2 months ago arvindr21
0.1.11 2 months ago arvindr21
0.1.10 2 months ago arvindr21
0.1.9 2 months ago arvindr21
0.1.8 2 months ago arvindr21
0.1.7 2 months ago arvindr21
0.1.6 2 months ago arvindr21
0.1.5 2 months ago arvindr21
0.1.4 2 months ago arvindr21
0.1.3 2 months ago arvindr21
0.1.2 2 months ago arvindr21
0.1.1 2 months ago arvindr21
0.1.0 2 months ago arvindr21

readme

diskDB Build Status NPM version Bitdeli Badge

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 : 

1
$ npm install diskdb

1
2
3
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

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

1
2
3
4
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.

1
[]

Else it will throw an error like

1
2
3
4
undefined:0

^
SyntaxError: Unexpected end of input

Load Collections

Alternatively you can also load collections like 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
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

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

Write/Save to Collection

1
db.collectioName.save(object);

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

1
db.[collectionName].[methodname]

To save the data, you can use

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
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 

1
2
3
4
5
6
7
8
[
    {
        "title": "diskDB rocks",
        "published": "today",
        "rating": "5 stars",
        "_id": "0f6047c6c69149f0be0c8f5943be91be"
    }
]

You can also save multiple objects at once like

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
[ { 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.collectioName.find(query)
  • db.collectioName.findOne(query)

db.collectioName.find()

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

This will return all the records

1
2
3
4
5
6
[{ 
    title: 'diskDB rocks',
    published: 'today',
    rating: '5 stars',
    _id: '0f6047c6c69149f0be0c8f5943be91be' 
}]

You can also query with a criteria like

1
2
3
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.

Nested JSON : 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
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
    }]
}

1
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.collectioName.findOne(query)

1
2
3
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. 

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

Update Collection

1
db.collectioName.update(query, data, options);

You can also update one or many objects in the collection

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

Usage 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
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

1
db.collectioName.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.

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

1
2
3
var db = require('diskdb');
db.connect('/examples/db', ['articles']);
db.articles.remove({rating : "5 stars"}, true); // remove all matched. Default - multi = true

1
2
3
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.

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

After the above operation db.articles is undefined.

Count

1
db.collectioName.count();

Will return the count of objects in the Collection

1
2
3
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

1
$ 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

1 (object) 1000 (objects) 10000 (objects) 100000 (objects) 1000000 (objects)
Save 1 (ms) 15 (ms) 137 (ms) 1782 (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.266671 (MB) 125.666671 (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.

Resolving all dependencies.. This could take a while as our cache is not yet fully warmed up.