LowDB

Flat JSON file database for Node

• Serverless
• Speedy
• Evented
• 50+ methods coming from Lo-Dash

LowDB is built on Lo-Dash, this makes it quite different and unique compared to other serverless databases often based on MongoDB API.

LowDB powers JSON Server and JSONPlaceholder.

If you need something similar for the browser, check Underscore.db.

Usage

var low = require('lowdb')
low('songs').insert({title: 'low!'})

Database is automatically created and saved to db.json in a readable format.

{
  "songs": [
    {
      "title": "low!",
      "id": "e31aa48c-a9d8-4f79-9fce-ded4c16c3c4c"
    }
  ]
}

To query data, you can use Lo-Dash methods.

var songs = low('songs').where({ title: 'low!' }).value()

Or LowDB equivalent short syntax.

var songs = low('songs', { title: 'low!' })

Changes can also be monitored.

low.on('add', function(name, object) {
  console.log(object + 'added to' + name)
})

Benchmark

get    x 1000    0.837708 ms
update x 1000    4.433322 ms
insert x 1000    11.78481 ms
remove x 1000    24.60179 ms

To run the benchmark on your machine, clone the project and run npm install && npm run benchmark.

API

low(collection)

Returns or create a Lo-Dash wrapped array.

You can then use methods like: where, find, filter, sortBy, groupBy, ... and also methods from Underscore.db.

var topFiveSongs = low('songs')
  .where({published: true})
  .sortBy('views')
  .first(5)
  .value();
  
var songTitles = low('songs')
  .pluck('titles')
  .value()
  
var total = low('songs').size()

If you just want to modify the database, without getting the returned array or object, you can omit .value()

low.save([path])

Saves database to path or low.path. By default db.json.

low.load([path])

Loads database from path or low.path. By default db.json.

low.path

Database location. By default db.json.

low.path = '/some/path/file.json'

autoSave

Set to false to disable save on change, this turns LowDB into a read-only in-memory database. By default true.

low.autoSave = true

Events

• add(collectionName, insertedDoc)
• update(collectionName, updatedDoc, previousDoc)
• remove(collectionName, removedDoc)
• change()

Short syntax

LowDB short syntax covers only the most common operations but lets you write really concise code.

low('songs', id)
// -> low('songs').get(id).value()

low('songs', {title: 'low!'})
// -> low('songs').where({title: 'low!'}).value()

low('songs', {title: 'low!'}, +1)
// -> low('songs').insert({title: 'low!'}).value()

low('songs', {title: 'low!'}, -1)
// -> low('songs').removeWhere({title: 'low!'}).value()

low('songs', id, -1)
// -> low('songs').remove(id).value()

low('songs', id, {title: 'new title'})
// -> low('songs').update(id, {title: 'new title'}).value()

low('songs', {published: false}, {published: true})
// -> low('songs').updateWhere({published: false}, {published: true}).value()

License

LowDB is released under the MIT License.