• Out of the box and improved TypeScript support.
• Uses new steno version for fast async file writes.
• Uses ECMAScript modules.
• Plain JS can now be used to modify and query db.data
• Reduced install size.
• With native JavaScript improvements, lodash is now optional (you can still use it though as it provides powerful utilities).

To help with OSS funding, lowdb v2 is released under Parity license for a limited time. It'll be released under MIT license once the goal of 100 sponsors is reached (currently at 55) or in five months. See README for complete explanation.

You can sponsor me on GitHub Sponsors.

Thank you!

Migrate

Lowdb v1

const low = require('lowdb')
const FileSync = require('lowdb/adapters/FileSync')

const adapter = new FileSync('db.json')
const db = low(adapter)

// Set some defaults
db.defaults({ posts: [], user: {} })
  .write()

// Add a post
db.get('posts')
  .push({ id: 1, title: 'lowdb is awesome'})
  .write()

// Set a user name using Lodash shorthand syntax
db.set('user.name', 'typicode')
  .write()

Lowdb v2

import { Low, FileSync } from 'lowdb'

const adapter = new FileSync('db.json')
const db = new Low(adapter)

// Set some defaults
db.data ||= { posts: [], user: {} })
db.write()

// Add a post
db.data
  .posts
  .push({ id: 1, title: 'lowdb is awesome'})
db.write()

// Set a user name using plain JS
db.data.user.name = 'typicode'
db.write()

If you're using TypeScript, data can now be typed:

type Post = {
  id: number
  title: string
}

type Data = {
  posts: Post[]
}

const db = new Low<Data>(adapter)

To continue using lodash with lowdb:

npm install lodash

import lodash from 'lodash'

// Set a user name using Lodash shorthand syntax
db.chain = lodash.chain(db.data)
db.chain
  .set('user.name', 'typicode')
  .value()
db.write()

Breaking changes

The following methods and properties have been removed:

• db.getState (use db.data instead)
• db.setState (use db.data = ... instead)
• db._

First stable release :tada: :smile:

Thanks to all the people who have contributed to lowdb!

If you've already updated Lowdb to v0.17, you have nothing to change.

• Fix FileAsync adapter https://github.com/typicode/lowdb/issues/209

Breaking changes

low() function has been updated to be more explicit and fully storage agnostic. It now expects an adapter to be passed.

Also, when using async file storage, low() will now return a Promise, making it truely asyncrhonous, rather than the database instance.

tl;dr

See Examples page for updated code samples.

Migration guide

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

// 0.17
const low = require('lowdb')
const FileSync = require('lowdb/adapters/FileSync')

const adapter = new FileSync('db.json')
const db = low(adapter)

The rest of lowdb API is unchanged, database instance creation is the only part of your code that needs to be updated.

Adapters

Lowdb comes bundled with 4 adapters:

• lowdb/adapters/FileSync
• lowdb/adapters/FileAsync
• lowdb/adapters/LocalStorage
• lowdb/adapters/Memory

Special thanks to @yeskunall for the help!

In this release, json-parse-helpfulerror is not included by default anymore due to issues with WebPack https://github.com/typicode/lowdb/issues/153.

That said, you can still configure lowdb to use it:

const low = require('lowdb')
const jph = require('json-parse-helpfulerror');

const db = low('db.json', {
  format: {
    stringify: JSON.stringify,
    parse: jph.parse
  }
})

Improvements

• Smaller core
• Faster by default
• Better async/await support

Breaking changes

.value() doesn't persist database anymore, instead .write() should be used after you modify the database:

// before
const result = db.get('posts')
  .push(post)
  .value()

// after
const result = db.get('posts')
  .push(post)
  .write()

This change makes using async/await syntax easier:

// before
function create(post) {
  const result = db.get('posts')
    .push(post)
    .value()

  return db.write()
    .then(() => result)
}

// after
async function create (post) {
  const result = await db.get('posts')
    .push(post)
    .write()
}

Other changes

• writeOnChange is deprecated as write is now explicit.
• storages are available under lib/storages (example: lowdb/lib/storages/file-async)
• .d.ts file has been removed

Why?

In v0.14.0, every time .value was called, JSON.stringify was run to detect changes. Although this worked for small databases, it wasn't efficient for bigger ones.

Alternatively, it was possible to disable this behaviour using writeOnChange: false and improve performances but its usage wasn't obvious.

Additionally, it makes clearer when data is written and when not.

To make things easier for people installing lowdb and because there's not much value in having lodash as a peer dependency, this version moves lodash back to dependencies (see https://github.com/typicode/lowdb/issues/127)

How to migrate?

If you're not requiring lodash in your code, run the following command:

npm uninstall lodash --save

Or simply remove lodash from your dependencies in package.json

This release contains breaking changes, please read the migration guide. In particular, db('name') is removed in favor of lodash _.get() and it's possible now to use _.set() to update database.

Overall, this version lets you use more of lodash API and is more flexible.

Changes

• db('name') has been removed. It was redundant with _.get().
• .value() won't return a promise anymore. There was a bug with it and it wasn't clear when a promise would be returned or not.
• db.object has been replaced by db.getState() and db.setState(). Future versions of lowdb should support arrays and not only objects as root structures.
• _.set() support makes it simpler to replace collections compared to db.object.prop = newValue; db.write().
• low() signature has changed, writeOnChange param is now part of the option param.
• lodash is now a peerDependency so you can have more control on which version is used.

In this release, you MUST ALWAYS call .value() at the end of a query to execute it

// won't be executed and won't create posts array in database
const chain = db.get('posts', []) 

// posts array will be created
chain.value() 

Migration guide

Installation

Since lodash is now a peerDependency, you need to add it to your dependencies.

npm install lowdb lodash@4 --save

Getting a collection

// v0.12
var posts = db('posts')
posts.value()

// v0.13
var posts = db.get('posts', [])
posts.value()

Pushing an item

// v0.12
posts.push({ title:'foo' })

// v0.13
posts.push({ title:'foo' }).value()

Replacing a collection

// v0.12
var filteredPosts = posts.filter({ published: true })

db.objects.posts = filteredPosts
db.write()

// v0.13
var filteredPosts = posts
  .filter({ published: true })
  .value()

db.set('posts', filteredPosts)
  .value()

If you're using file-async

// v0.12
var db = low('db.json', { storage: fileAsync })

db('posts')
  .push({ title: 'foo' })
  .then(() => console.log('done'))

// v0.13
var db = low('db.json', { storage: fileAsync })

// data is persisted in the background now
db.get('posts')
  .push({ title: 'foo' })
  .value()

If you need to control/know when data is written, disable writeOnChange and call db.write() manually:

var db = low('db.json', {
  storage: fileAsync,
  writeOnChange: false
})

db('posts')
  .push({ title: 'foo' })
  .value()

db.write()
  .then(() => console.log('done')

Bug fix: UMD build