express-db

A lightweight local key-value store that integrates with your express.js application.

npm install express-db
2 downloads in the last week
9 downloads in the last month

Build Status

express-db 0.0.2

A lightweight local key-value store that integrates with your express.js application.

WARNING This module is in very early stage of development. Serious issues, like performance, scalability or security may occur. Use at your OWN RISK! If you want to help improve express-db, feel free to contribute by forking and sending pull requests!

Installation

npm install express-db

Usage

Create you own db file

The first thing to do is to create your own db file for backup. It will need to be a json file, with the following default structure:

{
  "info": {
    "version": "0.0.2",
    "name": "demo DB"
  },
  "data": {

  }
}

'version' should be set to the version of express-db you are using, and 'name' should be the name of you db.

You will then need to define it in the express-db constructor:

xdb.init("my custom DB", {
    file: './my.custom.db.json'
});

Integrate with express.js 3.x

var express = require('express'),
    app = express(),
    xdb = require('express-db'),
    server = require('http')
        .createServer(app)
        .listen(8081);

app.use(xdb.init("demo DB", {
    file: './db/demo.db.json', //your db file
    restrictAccess: false, //restrict access via browser
    autoSave: true, //autosave enabled
    backupInterval: 60000, //interval in ms,
    viewCaching: true //cache views then requested
}));

API Reference

init(options)

the init method, to be passed to express for hook.

Options:

  • file: (required) path to your own db file
  • restrictAccess: (optional) true or false, restricts the access to the db on the client side
  • autoSave: (optional) enables automatic backup of the databse
  • backupInterval: (optional) the frequency (in ms) of backups
  • viewCaching: (optional) true or false, caches the view result on browser call

Example:

xdb.init("demo DB", {
    file: './db/demo.db.json', //your db
    restrictAccess: false, //restrict access via browser
    autoSave: true, //autosave enabled
    backupInterval: 60000, //interval in ms,
    viewCaching: true //cache views then requested
});

info()

Returns info on the current database.

xdb.info() // => {"version" : "0.0.2", "name": "demo DB"}

get(key)

Gets the value for a given key.

xdb.get('foo'); // => 'bar'

set(key, value)

Sets a value for a give key.

xdb.set('foo', 'bar');

remove(key)

Removes a given key.

xdb.remove('foo');

backup(callback)

Forces an immediate backup to file of the current database.

xdb.backup(function(err) {
    if(err) throw err;
    else console.log('DB backed up at %s', new Date().toString());
});

search(query)

Search through the JSON structure. Read the json-query documentation for more details on query possibilities.

xdb.search('stats.comments_lookup[{stats.page.id}]', function(res) {
    console.log("search result: ", res);
});

createView(name, query)

Creates a view exposbale to the client side of the express.js application. Query system is also based on json-query.

xdb.createView('comments', 'stats.comments_lookup[{stats.page.id}]');

getViews()

Returns the views defined for the current database.

xdb.getViews(); // => {'comments': {'query': 'stats.comments_lookup[{stats.page.id}]', cache: null}, ...}

Test

npm test

Performance

Tested on MacBook Air (1.7 Ghz Intel Core i5, 4Gb 1600Mhz DDR3):

STARTED SET TEST: 1373816191605
FINISHED SET TEST: 1373816192791
100,000 records set in : 1186 milliseconds
slept for 2 seconds
STARTED GET TEST: 1373816194793
FINISHED GET TEST: 1373816195584
100,000 records get in : 791 milliseconds

You can run the test on your own computer by typing: node demo/test.js

License

The MIT License (MIT)

Copyright (c) 2013 Stephane P. Pericat

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

npm loves you