🚀 Simplified syntax with db.update
, new adapter for more file format, consistent presets, automatic write error retry, and a TS error fix!
db.update
for easier updates and writes.DataFile
adapters for supporting various formats like YAML
, JSON5
, ... and adding features like encryption with minimal code.JSONPreset
to JSONFilePreset
JSONSyncPreset
to JSONFileSyncPreset
.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: [] })
Special thanks to lowdb's current sponsor: Mockend.
Your support is essential, you can sponsor this project on GitHub Sponsors ❤️
Published by typicode about 1 year ago
JSONPreset
and JSONSyncPreset
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()
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.
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)
Published by typicode over 1 year ago
Full Changelog: https://github.com/typicode/lowdb/compare/v6.0.0...v6.0.1
Published by typicode over 1 year ago
defaultData
parameter for Low
and LowSync
constructors to improve TypeScript experienceHow 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!
Published by typicode over 1 year ago
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.
// Before
import { Low, JSONFile } from 'lowdb'
// After
import { Low } from 'lowdb'
import { JSONFile } from 'lowdb/node'
lowdb/node
exports JSONFile
, JSONFileSync
, TextFile
and TextFileSync
.
// Before
import { LowSync, LocalStorage } from 'lowdb'
// After
import { LowSync } from 'lowdb'
import { LocalStorage } from 'lowdb/browser'
lowdb/browser
exports LocalStorage
.
#
instead of TypeScript private
keyword for adaptersMany thanks to Mockend and everyone on GitHub Sponsors for supporting this project ❤️ 🦉
db.data
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!
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()
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()
The following methods and properties have been removed:
db.getState
(use db.data
instead)db.setState
(use db.data = ...
instead)db._
FileAsync
adapter https://github.com/typicode/lowdb/issues/209
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.
See Examples page for updated code samples.
// 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.
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
}
})
async/await
support.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()
}
writeOnChange
is deprecated as write
is now explicit.lib/storages
(example: lowdb/lib/storages/file-async
).d.ts
file has been removedIn 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)
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
Published by typicode over 8 years ago
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.
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.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()
Since lodash is now a peerDependency, you need to add it to your dependencies.
npm install lowdb lodash@4 --save
// v0.12
var posts = db('posts')
posts.value()
// v0.13
var posts = db.get('posts', [])
posts.value()
// v0.12
posts.push({ title:'foo' })
// v0.13
posts.push({ title:'foo' }).value()
// 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()
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')