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.