or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

browser.mdcore.mdindex.mdnode.md
tile.json

tessl/npm-lowdb

Tiny local JSON database for Node, Electron and the browser

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/lowdb@7.0.x

To install, run

npx @tessl/cli install tessl/npm-lowdb@7.0.0

index.mddocs/

lowdb

lowdb is a simple, type-safe local JSON database for Node.js, Electron, and browser environments. It provides a minimalist API that leverages native JavaScript Array methods for querying and manipulation, with automatic file persistence and support for multiple storage adapters.

Package Information

  • Package Name: lowdb
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install lowdb

Core Imports

Main Entry Point (Universal)

import { Low, LowSync, Memory, MemorySync } from "lowdb";

Node.js Entry Point

import { JSONFilePreset, JSONFileSyncPreset } from "lowdb/node";
import { JSONFile, JSONFileSync, TextFile, TextFileSync, DataFile, DataFileSync } from "lowdb/node";

CommonJS:

const { JSONFilePreset, JSONFileSyncPreset } = require("lowdb/node");
const { JSONFile, JSONFileSync, TextFile, TextFileSync, DataFile, DataFileSync } = require("lowdb/node");

Browser Entry Point

import { LocalStoragePreset, SessionStoragePreset } from "lowdb/browser";
import { LocalStorage, SessionStorage } from "lowdb/browser";

CommonJS:

const { LocalStoragePreset, SessionStoragePreset } = require("lowdb/browser");
const { LocalStorage, SessionStorage } = require("lowdb/browser");

Basic Usage

Quick Start with Presets

import { JSONFilePreset } from "lowdb/node";

// Read or create db.json with default data
const defaultData = { posts: [] };
const db = await JSONFilePreset("db.json", defaultData);

// Update data using native Array methods and auto-save
await db.update(({ posts }) => posts.push({ id: 1, title: "Hello lowdb" }));

// Query using native Array methods
const { posts } = db.data;
const firstPost = posts.at(0);
const filteredPosts = posts.filter(post => post.title.includes("Hello"));

Manual Setup with Classes

import { Low } from "lowdb";
import { JSONFile } from "lowdb/node";

type Data = {
  posts: Array<{ id: number; title: string; views: number }>;
};

const defaultData: Data = { posts: [] };
const adapter = new JSONFile<Data>("db.json");
const db = new Low<Data>(adapter, defaultData);

// Must read explicitly when using manual setup
await db.read();

// Update and save
db.data.posts.push({ id: 1, title: "lowdb is awesome", views: 100 });
await db.write();

Browser Usage

import { LocalStoragePreset } from "lowdb/browser";

// Create database in localStorage
const db = LocalStoragePreset("myapp-data", { settings: {}, users: [] });

// Use synchronously in browser
db.data.settings.theme = "dark";
db.write(); // Saves to localStorage immediately

Architecture

lowdb is built around a simple adapter pattern with the following key components:

  • Core Classes: Low (async) and LowSync (sync) for database management
  • Adapter System: Pluggable storage backends for different environments and formats
  • Presets: Pre-configured database instances for common use cases
  • Type Safety: Full TypeScript support with generic type preservation
  • Native Array Methods: Direct access to JavaScript Array prototype methods for queries

Capabilities

Core Database Classes

Core async and sync database classes that manage data with configurable storage adapters.

class Low<T = unknown> {
  constructor(adapter: Adapter<T>, defaultData: T);
  adapter: Adapter<T>;
  data: T;
  read(): Promise<void>;
  write(): Promise<void>;
  update(fn: (data: T) => unknown): Promise<void>;
}

class LowSync<T = unknown> {
  constructor(adapter: SyncAdapter<T>, defaultData: T);
  adapter: SyncAdapter<T>;
  data: T;
  read(): void;
  write(): void;
  update(fn: (data: T) => unknown): void;
}

interface Adapter<T> {
  read(): Promise<T | null>;
  write(data: T): Promise<void>;
}

interface SyncAdapter<T> {
  read(): T | null;
  write(data: T): void;
}

Core Database Classes

Node.js File Storage

File-based storage adapters and convenience presets for Node.js environments, supporting JSON, text, and custom data formats.

function JSONFilePreset<Data>(filename: PathLike, defaultData: Data): Promise<Low<Data>>;
function JSONFileSyncPreset<Data>(filename: PathLike, defaultData: Data): LowSync<Data>;

class JSONFile<T> implements Adapter<T> {
  constructor(filename: PathLike);
}

class JSONFileSync<T> implements SyncAdapter<T> {
  constructor(filename: PathLike);
}

Node.js File Storage

Browser Storage

Browser storage adapters and presets for localStorage and sessionStorage integration.

function LocalStoragePreset<Data>(key: string, defaultData: Data): LowSync<Data>;
function SessionStoragePreset<Data>(key: string, defaultData: Data): LowSync<Data>;

class LocalStorage<T> implements SyncAdapter<T> {
  constructor(key: string);
}

class SessionStorage<T> implements SyncAdapter<T> {
  constructor(key: string);
}

Browser Storage

Memory Adapters

In-memory storage adapters for testing and temporary data storage.

class Memory<T> implements Adapter<T> {
  constructor();
}

class MemorySync<T> implements SyncAdapter<T> {
  constructor();
}

Memory adapters store data in RAM only and are automatically used by Node.js presets when NODE_ENV=test. They're perfect for unit testing and temporary data that doesn't need persistence. All data is lost when the process exits, making them ideal for testing scenarios where you want isolated, ephemeral storage.

Types

type PathLike = string | Buffer | URL;

The PathLike type is imported from Node.js fs module and is used in all Node.js file adapters to specify file paths.

Error Handling

lowdb adapters may throw the following types of errors:

  • File System Errors: Node.js ENOENT, EACCES, and other fs errors from file adapters
  • JSON Parse Errors: SyntaxError when reading malformed JSON files
  • Storage Quota Errors: Browser storage quota exceeded errors from localStorage/sessionStorage

When a file doesn't exist, file adapters return null during read operations rather than throwing an error.