1 | # lowdb [![](http://img.shields.io/npm/dm/lowdb.svg?style=flat)](https://www.npmjs.org/package/lowdb) [![Node.js CI](https://github.com/typicode/lowdb/actions/workflows/node.js.yml/badge.svg)](https://github.com/typicode/lowdb/actions/workflows/node.js.yml)
|
2 |
|
3 | > Simple to use local JSON database. Use native JavaScript API to query. Written in TypeScript. 🦉
|
4 |
|
5 | ```js
|
6 | // Edit db.json content using native JS API
|
7 | db.data
|
8 | .posts
|
9 | .push({ id: 1, title: 'lowdb is awesome' })
|
10 |
|
11 | // Save to file
|
12 | db.write()
|
13 | ```
|
14 |
|
15 | ```js
|
16 | // db.json
|
17 | {
|
18 | "posts": [
|
19 | { "id": 1, "title": "lowdb is awesome" }
|
20 | ]
|
21 | }
|
22 | ```
|
23 |
|
24 | If you like lowdb, see also [xv](https://github.com/typicode/xv) (test runner) and [steno](https://github.com/typicode/steno) (fast file writer).
|
25 |
|
26 | ## Sponsors
|
27 |
|
28 | <br>
|
29 | <br>
|
30 |
|
31 | <p align="center">
|
32 | <a href="https://mockend.com/" target="_blank">
|
33 | <img src="https://jsonplaceholder.typicode.com/mockend.svg" height="70px">
|
34 | </a>
|
35 | </p>
|
36 |
|
37 | <br>
|
38 | <br>
|
39 |
|
40 | [Become a sponsor and have your company logo here](https://github.com/sponsors/typicode).
|
41 |
|
42 | Please help me build OSS 👉 [GitHub Sponsors](https://github.com/sponsors/typicode)
|
43 |
|
44 | ## Features
|
45 |
|
46 | - __Lightweight__
|
47 | - __Minimalist__
|
48 | - __TypeScript__
|
49 | - __plain JS__
|
50 | - Atomic write
|
51 | - Hackable:
|
52 | - Change storage, file format (JSON, YAML, ...) or add encryption via [adapters](#adapters)
|
53 | - Add lodash, ramda, ... for super powers!
|
54 |
|
55 | ## Install
|
56 |
|
57 | ```sh
|
58 | npm install lowdb
|
59 | ```
|
60 |
|
61 | ## Usage
|
62 |
|
63 | _Lowdb is a pure ESM package. If you're having trouble importing it in your project, please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c)._
|
64 |
|
65 | ```js
|
66 | import { join, dirname } from 'node:path'
|
67 | import { fileURLToPath } from 'node:url'
|
68 |
|
69 | // Data will be saved to a local JSON file
|
70 | // For browser usage, see examples/ directory
|
71 | import { Low } from 'lowdb'
|
72 | import { JSONFile } from 'lowdb/node'
|
73 |
|
74 | const __dirname = dirname(fileURLToPath(import.meta.url));
|
75 |
|
76 | const file = join(__dirname, 'db.json')
|
77 | const adapter = new JSONFile(file)
|
78 | const db = new Low(adapter)
|
79 |
|
80 | // Read data from JSON file, this will set db.data content
|
81 | await db.read()
|
82 |
|
83 | // If db.json doesn't exist, db.data will be null
|
84 | // Set default data
|
85 | // db.data = db.data || { posts: [] } // Node < v15.x
|
86 | db.data ||= { posts: [] } // Node >= 15.x
|
87 |
|
88 | // Create and query items using native JS API
|
89 | db.data.posts.push('hello world')
|
90 | const firstPost = db.data.posts[0]
|
91 |
|
92 | // Alternatively, you can also use this syntax if you prefer
|
93 | const { posts } = db.data
|
94 | posts.push('hello world')
|
95 |
|
96 | // Finally write db.data content to file
|
97 | await db.write()
|
98 | ```
|
99 |
|
100 | ```js
|
101 | // db.json
|
102 | {
|
103 | "posts": [ "hello world" ]
|
104 | }
|
105 | ```
|
106 |
|
107 | ### TypeScript
|
108 |
|
109 | You can use TypeScript to type check your data.
|
110 |
|
111 | ```ts
|
112 | type Data = {
|
113 | words: string[]
|
114 | }
|
115 |
|
116 | const adapter = new JSONFile<Data>('db.json')
|
117 | const db = new Low(adapter)
|
118 |
|
119 | db.data
|
120 | .words
|
121 | .push('foo') // ✅
|
122 |
|
123 | db.data
|
124 | .words
|
125 | .push(1) // ❌
|
126 | ```
|
127 |
|
128 | ### Lodash
|
129 |
|
130 | You can also add lodash or other utility libraries to improve lowdb.
|
131 |
|
132 | ```ts
|
133 | import lodash from 'lodash'
|
134 |
|
135 | type Post = {
|
136 | id: number;
|
137 | title: string;
|
138 | }
|
139 |
|
140 | type Data = {
|
141 | posts: Post[]
|
142 | }
|
143 |
|
144 | // Extend Low class with a new `chain` field
|
145 | class LowWithLodash<T> extends Low<T> {
|
146 | chain: lodash.ExpChain<this['data']> = lodash.chain(this).get('data')
|
147 | }
|
148 |
|
149 | const adapter = new JSONFile<Data>('db.json')
|
150 | const db = new LowWithLodash(adapter)
|
151 | await db.read()
|
152 |
|
153 | // Instead of db.data use db.chain to access lodash API
|
154 | const post = db.chain
|
155 | .get('posts')
|
156 | .find({ id: 1 })
|
157 | .value() // Important: value() must be called to execute chain
|
158 | ```
|
159 |
|
160 | ### More examples
|
161 |
|
162 | For CLI, server and browser usage, see [`examples/`](/examples) directory.
|
163 |
|
164 | ## API
|
165 |
|
166 | ### Classes
|
167 |
|
168 | Lowdb has two classes (for asynchronous and synchronous adapters).
|
169 |
|
170 | #### `new Low(adapter)`
|
171 |
|
172 | ```js
|
173 | import { Low } from 'lowdb'
|
174 | import { JSONFile } from 'lowdb/node'
|
175 |
|
176 | const db = new Low(new JSONFile('file.json'))
|
177 | await db.read()
|
178 | await db.write()
|
179 | ```
|
180 |
|
181 | #### `new LowSync(adapterSync)`
|
182 |
|
183 | ```js
|
184 | import { LowSync } from 'lowdb'
|
185 | import { JSONFileSync } from 'lowdb/node'
|
186 |
|
187 | const db = new LowSync(new JSONFileSync('file.json'))
|
188 | db.read()
|
189 | db.write()
|
190 | ```
|
191 |
|
192 | ### Methods
|
193 |
|
194 | #### `db.read()`
|
195 |
|
196 | Calls `adapter.read()` and sets `db.data`.
|
197 |
|
198 | **Note:** `JSONFile` and `JSONFileSync` adapters will set `db.data` to `null` if file doesn't exist.
|
199 |
|
200 | ```js
|
201 | db.data // === null
|
202 | db.read()
|
203 | db.data // !== null
|
204 | ```
|
205 |
|
206 | #### `db.write()`
|
207 |
|
208 | Calls `adapter.write(db.data)`.
|
209 |
|
210 | ```js
|
211 | db.data = { posts: [] }
|
212 | db.write() // file.json will be { posts: [] }
|
213 | db.data = {}
|
214 | db.write() // file.json will be {}
|
215 | ```
|
216 |
|
217 | ### Properties
|
218 |
|
219 | #### `db.data`
|
220 |
|
221 | Holds your db content. If you're using the adapters coming with lowdb, it can be any type supported by [`JSON.stringify`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify).
|
222 |
|
223 | For example:
|
224 |
|
225 | ```js
|
226 | db.data = 'string'
|
227 | db.data = [1, 2, 3]
|
228 | db.data = { key: 'value' }
|
229 | ```
|
230 |
|
231 | ## Adapters
|
232 |
|
233 | ### Lowdb adapters
|
234 |
|
235 | #### `JSONFile` `JSONFileSync`
|
236 |
|
237 | Adapters for reading and writing JSON files.
|
238 |
|
239 | ```js
|
240 | new Low(new JSONFile(filename))
|
241 | new LowSync(new JSONFileSync(filename))
|
242 | ```
|
243 |
|
244 | #### `Memory` `MemorySync`
|
245 |
|
246 | In-memory adapters. Useful for speeding up unit tests.
|
247 |
|
248 | ```js
|
249 | new Low(new Memory())
|
250 | new LowSync(new MemorySync())
|
251 | ```
|
252 |
|
253 | #### `LocalStorage`
|
254 |
|
255 | Synchronous adapter for `window.localStorage`.
|
256 |
|
257 | ```js
|
258 | new LowSync(new LocalStorage(name))
|
259 | ```
|
260 |
|
261 | #### `TextFile` `TextFileSync`
|
262 |
|
263 | Adapters for reading and writing text. Useful for creating custom adapters.
|
264 |
|
265 | ### Third-party adapters
|
266 |
|
267 | If you've published an adapter for lowdb, feel free to create a PR to add it here.
|
268 |
|
269 | ### Writing your own adapter
|
270 |
|
271 | You may want to create an adapter to write `db.data` to YAML, XML, encrypt data, a remote storage, ...
|
272 |
|
273 | An adapter is a simple class that just needs to expose two methods:
|
274 |
|
275 | ```js
|
276 | class AsyncAdapter {
|
277 | read() { /* ... */ } // should return Promise<data>
|
278 | write(data) { /* ... */ } // should return Promise<void>
|
279 | }
|
280 |
|
281 | class SyncAdapter {
|
282 | read() { /* ... */ } // should return data
|
283 | write(data) { /* ... */ } // should return nothing
|
284 | }
|
285 | ```
|
286 |
|
287 | For example, let's say you have some async storage and want to create an adapter for it:
|
288 |
|
289 | ```js
|
290 | import { api } from './AsyncStorage'
|
291 |
|
292 | class CustomAsyncAdapter {
|
293 | // Optional: your adapter can take arguments
|
294 | constructor(args) {
|
295 | // ...
|
296 | }
|
297 |
|
298 | async read() {
|
299 | const data = await api.read()
|
300 | return data
|
301 | }
|
302 |
|
303 | async write(data) {
|
304 | await api.write(data)
|
305 | }
|
306 | }
|
307 |
|
308 | const adapter = new CustomAsyncAdapter()
|
309 | const db = new Low(adapter)
|
310 | ```
|
311 |
|
312 | See [`src/adapters/`](src/adapters) for more examples.
|
313 |
|
314 | #### Custom serialization
|
315 |
|
316 | To create an adapter for another format than JSON, you can use `TextFile` or `TextFileSync`.
|
317 |
|
318 | For example:
|
319 |
|
320 | ```js
|
321 | import { Adapter, Low } from 'lowdb'
|
322 | import { TextFile } from 'lowdb/node'
|
323 | import YAML from 'yaml'
|
324 |
|
325 | class YAMLFile {
|
326 | constructor(filename) {
|
327 | this.adapter = new TextFile(filename)
|
328 | }
|
329 |
|
330 | async read() {
|
331 | const data = await this.adapter.read()
|
332 | if (data === null) {
|
333 | return null
|
334 | } else {
|
335 | return YAML.parse(data)
|
336 | }
|
337 | }
|
338 |
|
339 | write(obj) {
|
340 | return this.adapter.write(YAML.stringify(obj))
|
341 | }
|
342 | }
|
343 |
|
344 | const adapter = new YAMLFile('file.yaml')
|
345 | const db = new Low(adapter)
|
346 | ```
|
347 |
|
348 | ## Limits
|
349 |
|
350 | Lowdb doesn't support Node's cluster module.
|
351 |
|
352 | If you have large JavaScript objects (`~10-100MB`) you may hit some performance issues. This is because whenever you call `db.write`, the whole `db.data` is serialized using `JSON.stringify` and written to storage.
|
353 |
|
354 | Depending on your use case, this can be fine or not. It can be mitigated by doing batch operations and calling `db.write` only when you need it.
|
355 |
|
356 | If you plan to scale, it's highly recommended to use databases like PostgreSQL or MongoDB instead.
|