jodb
Version:
Flat JSON file database with promise
229 lines (153 loc) • 5.16 kB
Markdown
# jodb [](http://badge.fury.io/js/jodb) [](https://travis-ci.org/fatea/jodb)
> Need a quick way to get a local database?
## Example
```javascript
var jodb = require('jodb')
var db = jodb('db.json')
db('posts').push({ title: 'jodb is awesome'})
```
Database is __automatically__ saved to `db.json`
```javascript
{
"posts": [
{ "title": "jodb is awesome" }
]
}
```
You can query and manipulate it using __any__ [lodash](https://lodash.com/docs) __method__
```javascript
db('posts').find({ title: 'jodb is awesome' })
```
## Install
```bash
npm install jodb --save
```
## Features
* Small
* Serverless
* lodash rich API
* In-memory or disk-based
* __Hackable__ (mixins, id, encryption, ...)
It's also __very easy to learn and use__ since it has __only 8 methods and properties__.
## API
__jodb([filename, options])__
Creates a disk-based or in-memory database instance. If a filename is provided, it loads or creates it.
```javascript
var db = jodb() // in-memory
var db = jodb('db.json') // disk-based
```
When a filename is provided you can set options.
```javascript
var db = jodb('db.json', {
autosave: true, // automatically save database on change (default: true)
async: true, // asynchronous write (default: true)
promise: false //promise write(default: false)
})
```
__jodb.stringify(obj)__ and __jodb.parse(str)__
Overwrite these methods to customize JSON stringifying and parsing.
__db.___
Database lodash instance. Use it for example to add your own utility functions or third-party libraries.
```javascript
db._.mixin({
second: function(array) {
return array[1]
}
})
var song1 = db('songs').first()
var song2 = db('songs').second()
```
__db.object__
Use whenever you want to access or modify the underlying database object.
```javascript
if (db.object.songs) console.log('songs array exists')
```
__db.save([filename])__
Saves database to file.
```javascript
var db = jodb('db.json')
db.save() // saves to db.json
db.save('copy.json')
```
Note: In case you directly modify the content of the database object, you'll need to manually call `save`
```javascript
delete db.object.songs
db.save()
```
__db.saveSync([filename])__
Synchronous version of `db.save()`
## Guide
### Operations
With jodb you get access to the entire [lodash API](http://lodash.com/), so there's many ways to query and manipulate data. Here are a few examples to get you started.
Please note that data is returned by reference, this means that modifications to returned objects may change the database. To avoid such behaviour, you need to use `.cloneDeep()`.
Also, the execution of chained methods is lazy, that is, execution is deferred until `.value()` is called.
Sort the top five songs.
```javascript
db('songs')
.chain()
.where({published: true})
.sortBy('views')
.take(5)
.value()
```
Retrieve song titles.
```javascript
db('songs').pluck('title')
```
Get the number of songs.
```javascript
db('songs').size()
```
Make a deep clone of songs.
```javascript
db('songs').cloneDeep()
```
Update a song.
```javascript
db('songs')
.chain()
.find({ title: 'jodb!' })
.assign({ title: 'hi!'})
.value()
```
Remove songs.
```javascript
db('songs').remove({ title: 'jodb!' })
```
### Id support
Being able to retrieve data using an id can be quite useful, particularly in servers. To add id-based resources support to jodbdb, you have 2 options.
[underscore-db](https://github.com/typicode/underscore-db) provides a set of helpers for creating and manipulating id-based resources.
```javascript
var db = jodb('db.json')
db._.mixin(require('underscore-db'))
var songId = db('songs').insert({ title: 'jodb!' }).id
var song = db('songs').getById(songId)
```
[uuid](https://github.com/broofa/node-uuid) returns a unique id.
```javascript
var uuid = require('uuid')
var songId = db('songs').push({ id: uuid(), title: 'jodb!' }).id
var song = db('songs').find({ id: songId })
```
### Encryption support
In some cases, you may want to make it harder to read database content. By overwriting, `jodb.stringify` and `jodb.parse`, you can add custom encryption.
```javascript
var crypto = require('crypto')
var cipher = crypto.createCipher('aes256', secretKey)
var decipher = crypto.createDecipher('aes256', secretKey)
jodb.stringify = function(obj) {
var str = JSON.stringify(obj)
return cipher.update(str, 'utf8', 'hex') + cipher.final('hex')
}
jodb.parse = function(encrypted) {
var str = decipher.update(encrypted, 'hex', 'utf8') + decipher.final('utf8')
return JSON.parse(str)
}
```
## Changelog
See details changes for each version in the [release notes](https://github.com/fatea/jodbdb/releases).
## Limits
jodbdb is a convenient method for storing data without setting up a database server. It's fast enough and safe to be used as an embedded database.
However, if you need high performance and scalability more than simplicity, you should stick to databases like MongoDB.
## License
MIT - [Typicode](https://github.com/typicode)