0
# lowdb
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: lowdb
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install lowdb`
10
11
## Core Imports
12
13
### Main Entry Point (Universal)
14
15
```typescript
16
import { Low, LowSync, Memory, MemorySync } from "lowdb";
17
```
18
19
### Node.js Entry Point
20
21
```typescript
22
import { JSONFilePreset, JSONFileSyncPreset } from "lowdb/node";
23
import { JSONFile, JSONFileSync, TextFile, TextFileSync, DataFile, DataFileSync } from "lowdb/node";
24
```
25
26
CommonJS:
27
28
```javascript
29
const { JSONFilePreset, JSONFileSyncPreset } = require("lowdb/node");
30
const { JSONFile, JSONFileSync, TextFile, TextFileSync, DataFile, DataFileSync } = require("lowdb/node");
31
```
32
33
### Browser Entry Point
34
35
```typescript
36
import { LocalStoragePreset, SessionStoragePreset } from "lowdb/browser";
37
import { LocalStorage, SessionStorage } from "lowdb/browser";
38
```
39
40
CommonJS:
41
42
```javascript
43
const { LocalStoragePreset, SessionStoragePreset } = require("lowdb/browser");
44
const { LocalStorage, SessionStorage } = require("lowdb/browser");
45
```
46
47
## Basic Usage
48
49
### Quick Start with Presets
50
51
```typescript
52
import { JSONFilePreset } from "lowdb/node";
53
54
// Read or create db.json with default data
55
const defaultData = { posts: [] };
56
const db = await JSONFilePreset("db.json", defaultData);
57
58
// Update data using native Array methods and auto-save
59
await db.update(({ posts }) => posts.push({ id: 1, title: "Hello lowdb" }));
60
61
// Query using native Array methods
62
const { posts } = db.data;
63
const firstPost = posts.at(0);
64
const filteredPosts = posts.filter(post => post.title.includes("Hello"));
65
```
66
67
### Manual Setup with Classes
68
69
```typescript
70
import { Low } from "lowdb";
71
import { JSONFile } from "lowdb/node";
72
73
type Data = {
74
posts: Array<{ id: number; title: string; views: number }>;
75
};
76
77
const defaultData: Data = { posts: [] };
78
const adapter = new JSONFile<Data>("db.json");
79
const db = new Low<Data>(adapter, defaultData);
80
81
// Must read explicitly when using manual setup
82
await db.read();
83
84
// Update and save
85
db.data.posts.push({ id: 1, title: "lowdb is awesome", views: 100 });
86
await db.write();
87
```
88
89
### Browser Usage
90
91
```typescript
92
import { LocalStoragePreset } from "lowdb/browser";
93
94
// Create database in localStorage
95
const db = LocalStoragePreset("myapp-data", { settings: {}, users: [] });
96
97
// Use synchronously in browser
98
db.data.settings.theme = "dark";
99
db.write(); // Saves to localStorage immediately
100
```
101
102
## Architecture
103
104
lowdb is built around a simple adapter pattern with the following key components:
105
106
- **Core Classes**: `Low` (async) and `LowSync` (sync) for database management
107
- **Adapter System**: Pluggable storage backends for different environments and formats
108
- **Presets**: Pre-configured database instances for common use cases
109
- **Type Safety**: Full TypeScript support with generic type preservation
110
- **Native Array Methods**: Direct access to JavaScript Array prototype methods for queries
111
112
## Capabilities
113
114
### Core Database Classes
115
116
Core async and sync database classes that manage data with configurable storage adapters.
117
118
```typescript { .api }
119
class Low<T = unknown> {
120
constructor(adapter: Adapter<T>, defaultData: T);
121
adapter: Adapter<T>;
122
data: T;
123
read(): Promise<void>;
124
write(): Promise<void>;
125
update(fn: (data: T) => unknown): Promise<void>;
126
}
127
128
class LowSync<T = unknown> {
129
constructor(adapter: SyncAdapter<T>, defaultData: T);
130
adapter: SyncAdapter<T>;
131
data: T;
132
read(): void;
133
write(): void;
134
update(fn: (data: T) => unknown): void;
135
}
136
137
interface Adapter<T> {
138
read(): Promise<T | null>;
139
write(data: T): Promise<void>;
140
}
141
142
interface SyncAdapter<T> {
143
read(): T | null;
144
write(data: T): void;
145
}
146
```
147
148
[Core Database Classes](./core.md)
149
150
### Node.js File Storage
151
152
File-based storage adapters and convenience presets for Node.js environments, supporting JSON, text, and custom data formats.
153
154
```typescript { .api }
155
function JSONFilePreset<Data>(filename: PathLike, defaultData: Data): Promise<Low<Data>>;
156
function JSONFileSyncPreset<Data>(filename: PathLike, defaultData: Data): LowSync<Data>;
157
158
class JSONFile<T> implements Adapter<T> {
159
constructor(filename: PathLike);
160
}
161
162
class JSONFileSync<T> implements SyncAdapter<T> {
163
constructor(filename: PathLike);
164
}
165
```
166
167
[Node.js File Storage](./node.md)
168
169
### Browser Storage
170
171
Browser storage adapters and presets for localStorage and sessionStorage integration.
172
173
```typescript { .api }
174
function LocalStoragePreset<Data>(key: string, defaultData: Data): LowSync<Data>;
175
function SessionStoragePreset<Data>(key: string, defaultData: Data): LowSync<Data>;
176
177
class LocalStorage<T> implements SyncAdapter<T> {
178
constructor(key: string);
179
}
180
181
class SessionStorage<T> implements SyncAdapter<T> {
182
constructor(key: string);
183
}
184
```
185
186
[Browser Storage](./browser.md)
187
188
### Memory Adapters
189
190
In-memory storage adapters for testing and temporary data storage.
191
192
```typescript { .api }
193
class Memory<T> implements Adapter<T> {
194
constructor();
195
}
196
197
class MemorySync<T> implements SyncAdapter<T> {
198
constructor();
199
}
200
```
201
202
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.
203
204
## Types
205
206
```typescript { .api }
207
type PathLike = string | Buffer | URL;
208
```
209
210
The `PathLike` type is imported from Node.js `fs` module and is used in all Node.js file adapters to specify file paths.
211
212
## Error Handling
213
214
lowdb adapters may throw the following types of errors:
215
216
- **File System Errors**: Node.js `ENOENT`, `EACCES`, and other fs errors from file adapters
217
- **JSON Parse Errors**: `SyntaxError` when reading malformed JSON files
218
- **Storage Quota Errors**: Browser storage quota exceeded errors from localStorage/sessionStorage
219
220
When a file doesn't exist, file adapters return `null` during read operations rather than throwing an error.