Standalone UMD builds are now available. Check dist directory after installing lowdb.

You can also use npmcdn to access them: http://npmcdn.com/lowdb@^0.12.4/dist/lowdb.min.js

This version uses lodash v4. Lowdb API doesn't change, however you may have to update the lodash methods you're using.

// lowdb v0.11 (with lodash v3)
const low = require('lowdb')
const db = low()

db('posts').where({ title: 'JavaScript' })

// lowdb v0.12 (with lodash v4)
const low = require('lowdb')
const db = low()

// .where() has been replaced by .filter() in lodash v4
// so you need to use the new method
db('posts').filter({ title: 'JavaScript' })

Read lodash breaking changes.

Add db.read()

Add Promise support for storage.read. This makes possible to have fully asynchronous db creation.

const low = require('lowdb')
const storage = require('some-promise-based-storage')

low(source, { storage }).then(db => {
  // db is ready
})

Update with various bug fixes.

Thank you everyone for all the Pull Requests, feedbacks, ideas, issues, questions... it helped a lot!

What's new

• Browser support
• Custom storage support
• Per-db custom format
• Promise support
• Complete rewrite in ES2015+
• Node 0.10 support has been dropped
• ... still as small as ever :)

TL;DR

This is a major release that adds browser and custom storage support.

• low() method has changed.
• .value() and db[lodash-method]() will return a Promise when storage is asynchronous and database is modified.

You can find detailed explanations below and in the README.

Custom storage

For the past few months, there were many requests to support more storage options (LocalStorage, multiple files, MongoDB, ...).

Unfortunatly, despite the fact that there were great ideas, it wasn't possible to extend lowdb and supporting all these storages inside the project would have made it bloated

With this release, it's now possible to tell lowdb how to store data by passing storage.read and storage.write functions when creating database.

const myStorage = {
  read: (source, serialize) => // ...
  // when writing, you can return a Promise for asynchronous operations
  // or undefined if syncrhonous
  write: (source, object, deserialize) => // ...
}

const source = 'db.json'
const db = low(source, { storage })

Lowdb comes bundled with lowdb/file-sync, lowdb/file-async and lowdb/browser storages.

Per-db custom format

const format = {
  serialize: (obj) => // data
  deserialize: (data) => // obj
}

const db = low(source, { format })

If format.serialize or format.deserialize functions are set, lowdb will automatically pass them to storage.write and storage.read functions.

Promise

If storage.write is asynchronous and returns a Promise, when the database is modified .value() and db[lodash-method]() will return a Promise that resolves to the value.

const storage = require('lowdb/file-async')

const db = low('db.json', storage)
const posts = db('posts')

// Return a Promise because writing is asynchronous
posts.push({ title: 'lowdb' }).then(post => /* */)
posts.chain().push({ title: 'lowdb' }).value().then(post => /* */)

// No promise because reading is done in memory and is synchronous
const post = posts.first()

Migration guide

Async mode (don't forget that in async mode, promises will be returned when modifying the database)

// before
const db = low('db.json')

// after
const storage = require('lowdb/file-async')
const db = low('db.json', { storage })

In-memory

// doesn't change
const db = low() 

Sync mode

// before
const db = low('db.json', { async: false }) 

// after
const db = low('db.json', { storage: require('lowdb/file-sync') })

autoSave option is now an argument in low()

// before
const db = low('db.json', { autoSave: false }) 

// after
const db = low('db.json', { storage }, false)

low.parse and low.stringify has been moved too

// before
low.parse = myParse
low.stringify = myStringify

// after
const db = low('db.json', {
  format: { serialize: myStringify, deserialize: myParse }
})

db.save() has been renamed to db.write()

db.saveSync() has been removed, use lowdb/file-sync and call db.write()

Features

• Updated to lodash v3.0.0 (changelog)
• Better performance

Breaking changes

Because of the way chaining works now in lodash, chain() must be explicitly called. In other cases, simply calling the method returns the value.

Before

var songs = db('songs').push({ title: 'some song' }).value()
db('songs')
  .find({ title: 'low!' })
  .assign({ title: 'hi!'})
  .value()

After

var songs = db('songs').push({ title: 'some song' })
db('songs')
  .chain()
  .find({ title: 'low!' })
  .assign({ title: 'hi!'})
  .value()

• Expose stringify and parse methods #25

Fix #19

Fix #19 EXDEV exception on Windows when running LowDB in another partition than C:/