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()anddb[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()