lowdb

Since db.data is a plain JavaScript object, you can use native Array methods to query your data without any special syntax.

const { posts } = db.data

posts.at(0) // Get first post
posts.filter((post) => post.title.includes('lowdb')) // Filter
posts.find((post) => post.id === 1) // Find by ID
posts.toSorted((a, b) => a.views - b.views) // Sort

The easiest way to start is using JSONFilePreset. It reads an existing file or creates a new one with the provided defaultData if it doesn't exist. Note that lowdb is a pure ESM package.

import { JSONFilePreset } from 'lowdb/node'

// Read or create db.json
const defaultData = { posts: [] }
const db = await JSONFilePreset('db.json', defaultData)

You can update the database in two ways:

1. Using db.update(fn): This is a single-step method that executes the provided function on the data and automatically calls db.write() to persist changes.
2. Manual update: Modify db.data directly and then call await db.write() explicitly to save the changes to storage.

// Option 1: One-step update
await db.update(({ posts }) => posts.push('hello world'))

// Option 2: Manual update
db.data.posts.push('hello world')
await db.write()

Install the lowdb package using npm to get started with a lightweight, type-safe local JSON database.

npm install lowdb

Keep the following limitations in mind when using lowdb:

• No Cluster Support: Lowdb does not support Node's cluster module.
• Serialization Overhead: Every time db.write() is called, the entire db.data object is serialized via JSON.stringify. For large objects (~10-100MB), this can cause performance issues.
• Mitigation: Perform batch operations and call db.write() only when necessary.
• Scaling: If your data requirements grow beyond what a local JSON file can efficiently handle, migrate to a dedicated database like PostgreSQL or MongoDB.

For unit tests or scenarios where you need high performance and do not need to persist data to disk, use the in-memory adapter. This is ideal for writing fast, isolated tests.

// Based on in-memory.ts
// Uses in-memory adapter for fast testing

When building a server (e.g., using Express), use the asynchronous JSONFile adapter. This ensures that file I/O does not block the event loop, which is critical for server performance.

// Based on server.ts
// Uses JSONFile adapter for Express server examples

To use lowdb in a browser environment, use the LocalStorage adapter. This allows you to persist your database state directly in the user's browser storage.

// Based on browser.ts
// Uses LocalStorage adapter for browser-based usage

You can achieve full type safety by passing a type parameter to the preset functions. This ensures that operations on db.data are checked against your defined schema.

type Data = {
  messages: string[]
}

const defaultData: Data = { messages: [] }
const db = await JSONPreset<Data>('db.json', defaultData)

db.data.messages.push('foo') // ✅ Success
db.data.messages.push(1)    // ❌ TypeScript error

To use a format other than JSON, you can use TextFile as a base and implement read and write methods that handle the parsing and stringifying logic.

import { Adapter, Low } from 'lowdb'
import { TextFile } from 'lowdb/node'
import YAML from 'yaml'

class YAMLFile {
  constructor(filename) {
    this.adapter = new TextFile(filename)
  }

  async read() {
    const data = await this.adapter.read()
    return data === null ? null : YAML.parse(data)
  }

  write(obj) {
    return this.adapter.write(YAML.stringify(obj))
  }
}

const adapter = new YAMLFile('file.yaml')
const db = new Low(adapter, {})

To use libraries like Lodash, you must use the lower-level Low class instead of presets. You can extend the Low class to add new properties (like a Lodash chain) to the database instance.

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

type Post = { id: number; title: string }
type Data = { posts: Post[] }

class LowWithLodash<T> extends Low<T> {
  chain: lodash.ExpChain<this['data']> = lodash.chain(this).get('data')
}

const defaultData: Data = { posts: [] }
const adapter = new JSONFile<Data>('db.json')
const db = new LowWithLodash(adapter, defaultData)
await db.read()

// Use db.chain instead of db.data for lodash operations
const post = db.chain.get('posts').find({ id: 1 }).value() 

For simple CLI tools where synchronous file operations are acceptable, use the JSONFileSync adapter. This allows you to persist data to a local JSON file synchronously.

// Based on cli.ts
// Uses JSONFileSync adapter for simple CLI usage