🚀 Simplified syntax with db.update, new adapter for more file format, consistent presets, automatic write error retry, and a TS error fix!

What's New

• Simplified Syntax: Introducing db.update for easier updates and writes.
• Flexible Adapters: Added DataFile adapters for supporting various formats like YAML , JSON5, ... and adding features like encryption with minimal code.
• Automatic Retry: Resolves write errors, especially for Windows users.

Breaking Changes

• Node 16 Dropped: discontinued support for Node 16.
• Consistent Naming: Renamed presets for consistency:
  • JSONPreset to JSONFilePreset
  • JSONSyncPreset to JSONFileSyncPreset.

Code Examples

If you were using the JSONPreset, please rename it

- import { JSONPreset } from 'lowdb/node'
+ import { JSONFilePreset } from 'lowdb/node'

Enjoy the simplified syntax with db.update

- db.data.posts.push(newPost)
- await db.write()
+ await db.update(({ posts }) => posts.push(newPost))

Easily support other formats:

const yamlAdapter = new DataFile('db.yaml', {
  parse: YAML.parse,
  stringify: YAML.stringify
})
const db = new Low(yamlAdapter, { posts: [] })

Sponsors

Special thanks to lowdb's current sponsor: Mockend.

Your support is essential, you can sponsor this project on GitHub Sponsors ❤️

• Fix JSONPreset and JSONSyncPreset

New presets

Before

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

const adapter = new JSONFile(file)
const defaultData = { posts: [] }
const db = new Low(adapter, defaultData)

await db.read()

Now

import { JSONPreset } from 'lowdb/node'

const defaultData = { posts: [] }
const db = await JSONPreset('db.json', defaultData)

This will also use the Memory adapter automatically when NODE_ENV=test making tests faster.

TypeScript

Lowdb now supports the broader fs.PathLike type which lets you use URL type in addition to string. This is useful for ESM.

// Read from 'db.json' relatively to the current module path using URL
JSONPreset(new URL('db.json', import.meta.url), defaultData)

What's Changed

• fix: imported subpaths types correctly by @Krak798 in https://github.com/typicode/lowdb/pull/569

New Contributors

• @Krak798 made their first contribution in https://github.com/typicode/lowdb/pull/569

Full Changelog: https://github.com/typicode/lowdb/compare/v6.0.0...v6.0.1

What's Changed

• Drop Node 14 support
• Require defaultData parameter for Low and LowSync constructors to improve TypeScript experience
• Move examples from Markdown to real TypeScript files

How to upgrade:

// v5
const defaultData = { posts: [] }
const db = new Low(adapter)
db.data ||= defaultData

function add() {
  db.data.posts.push('title') // TS error
}

// v6
const defaultData = { posts: [] }
const db = new Low(adapter, defaultData)

function add() {
  db.data.posts.push('title') // No TS error
}

If you like lowdb, please sponsor my work. If you cannot, a star or tweet is always appreciated.
Thank you!

What's Changed

• feat: add SessionStorage adapter by @crashmax-dev in https://github.com/typicode/lowdb/pull/560

New Contributors

• @crashmax-dev made their first contribution in https://github.com/typicode/lowdb/pull/560

Full Changelog: https://github.com/typicode/lowdb/compare/v5.0.4...v5.1.0

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 ❤️ 🦉

• 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 🎉 😄

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