Better support for front-end tools like Vite, CodeSandbox, ...

To achieve this, Node and Browser (localStorage) adapters are now split in two. Besides that, there are no other breaking changes.

Node

// Before
import { Low, JSONFile } from 'lowdb'

// After
import { Low } from 'lowdb'
import { JSONFile } from 'lowdb/node'

lowdb/node exports JSONFile, JSONFileSync, TextFile and TextFileSync.

Browser

// Before
import { LowSync, LocalStorage } from 'lowdb'

// After
import { LowSync } from 'lowdb'
import { LocalStorage } from 'lowdb/browser'

lowdb/browser exports LocalStorage.

• Drop Node 12 support
• Update dependencies

• Switch license from "Sponsors and OSS Only" to MIT
• Use native # instead of TypeScript private keyword for adapters
• Update dependencies
• No breaking change in terms of code

Many thanks to Mockend and everyone on GitHub Sponsors for supporting this project :heart: :owl:

• Add TextFile and TextFileSync adapters to simplify writing to different formats (YAML, XML, ...) and make encryption easier.

• 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

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:/

New features

Version 0.4.0 is a complete rewrite of the project in order to achieve:

• Better fault tolerancy
  • Writing is now atomic. Even if your process crashes, you won't have half written corrupted JSON files.
• Better asynchronism
  • Writing is now fully asynchronous.
• Better flexibility
  • Custom functions and third-party libraries can now be added using low.mixin().
  • Underscore.db dependency was removed, LowDB is now pure Lo-Dash. Underscore.db can still be added though using low.mixin().
• Better API
  • Database is now automatically loaded when calling low(filename)
• Multiple database support
  • You can work with multiple JSON files.

Breaking changes

During the process, some compromises needed to be made. Here's the list of the breaking changes:

• API

v0.3.x

var low = require('lowdb').load() // loads db.json (by default)
var posts = low('posts').sortBy('title').value()

v0.4.0

var low = require('lowdb')
var db = low('db.json') // loads db.json (must be explicit)

var posts = db('posts').sortBy('title').value()

• Events

Removed to simplify code. You can use Watch.js to monitor database object or similar projects.

Also Object.observe() will be available in Node 0.12, so it's just a matter of time before you can have database object events back.

• options

Removed. Use low() instead.

var db = low()          // same as autoSave: false
var db = low('db.json') // same as autoSave: true and path: 'db.json'

• short syntax

Removed. Short syntax was mainly an experiment. If you need it back, please create an issue.

• Underscore.db methods

Underscore.db dependency was removed. You can use Lo-Dash methods to query or manipulate data like push(), where(), ... instead of insert(), get(), ...

Or you can use mixin() to add Underscore.db back .

See README for informations about how to extend LowDB.

Initial public release.