\n\n \n \n\n[Become a sponsor and have your company logo here](https://github.com/sponsors/typicode) 👉 [GitHub Sponsors](https://github.com/sponsors/typicode)\n\n## Features\n\n- **Lightweight**\n- **Minimalist**\n- **TypeScript**\n- **Plain JavaScript**\n- Safe atomic writes\n- Hackable:\n - Change storage, file format (JSON, YAML, ...) or add encryption via [adapters](#adapters)\n - Extend it with lodash, ramda, ... for super powers!\n- Automatically switches to fast in-memory mode during tests\n\n## Install\n\n```sh\nnpm install lowdb\n```\n\n## Usage\n\n_Lowdb is a pure ESM package. If you're having trouble using it in your project, please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c)._\n\n```js\nimport { JSONFilePreset } from 'lowdb/node'\n\n// Read or create db.json\nconst defaultData = { posts: [] }\nconst db = await JSONFilePreset('db.json', defaultData)\n\n// Update db.json\nawait db.update(({ posts }) => posts.push('hello world'))\n\n// Alternatively you can call db.write() explicitely later\n// to write to db.json\ndb.data.posts.push('hello world')\nawait db.write()\n```\n\n```js\n// db.json\n{\n \"posts\": [ \"hello world\" ]\n}\n```\n\n### TypeScript\n\nYou can use TypeScript to check your data types.\n\n```ts\ntype Data = {\n messages: string[]\n}\n\nconst defaultData: Data = { messages: [] }\nconst db = await JSONPreset('db.json', defaultData)\n\ndb.data.messages.push('foo') // ✅ Success\ndb.data.messages.push(1) // ❌ TypeScript error\n```\n\n### Lodash\n\nYou can extend lowdb with Lodash (or other libraries). To be able to extend it, we're not using `JSONPreset` here. Instead, we're using lower components.\n\n```ts\nimport { Low } from 'lowdb'\nimport { JSONFile } from 'lowdb/node'\nimport lodash from 'lodash'\n\ntype Post = {\n id: number\n title: string\n}\n\ntype Data = {\n posts: Post[]\n}\n\n// Extend Low class with a new `chain` field\nclass LowWithLodash extends Low {\n chain: lodash.ExpChain = lodash.chain(this).get('data')\n}\n\nconst defaultData: Data = {\n posts: [],\n}\nconst adapter = new JSONFile('db.json', defaultData)\n\nconst db = new LowWithLodash(adapter)\nawait db.read()\n\n// Instead of db.data use db.chain to access lodash API\nconst post = db.chain.get('posts').find({ id: 1 }).value() // Important: value() must be called to execute chain\n```\n\n### CLI, Server, Browser and in tests usage\n\nSee [`src/examples/`](src/examples) directory.\n\n## API\n\n### Presets\n\nLowdb provides four presets for common cases.\n\n- `JSONFilePreset(filename, defaultData)`\n- `JSONFileSyncPreset(filename, defaultData)`\n- `LocalStoragePreset(name, defaultData)`\n- `SessionStoragePreset(name, defaultData)`\n\nSee [`src/examples/`](src/examples) directory for usage.\n\nLowdb is extremely flexible, if you need to extend it or modify its behavior, use the classes and adapters below instead of the presets.\n\n### Classes\n\nLowdb has two classes (for asynchronous and synchronous adapters).\n\n#### `new Low(adapter, defaultData)`\n\n```js\nimport { Low } from 'lowdb'\nimport { JSONFile } from 'lowdb/node'\n\nconst db = new Low(new JSONFile('file.json'), {})\nawait db.read()\nawait db.write()\n```\n\n#### `new LowSync(adapterSync, defaultData)`\n\n```js\nimport { LowSync } from 'lowdb'\nimport { JSONFileSync } from 'lowdb/node'\n\nconst db = new LowSync(new JSONFileSync('file.json'), {})\ndb.read()\ndb.write()\n```\n\n### Methods\n\n#### `db.read()`\n\nCalls `adapter.read()` and sets `db.data`.\n\n**Note:** `JSONFile` and `JSONFileSync` adapters will set `db.data` to `null` if file doesn't exist.\n\n```js\ndb.data // === null\ndb.read()\ndb.data // !== null\n```\n\n#### `db.write()`\n\nCalls `adapter.write(db.data)`.\n\n```js\ndb.data = { posts: [] }\ndb.write() // file.json will be { posts: [] }\ndb.data = {}\ndb.write() // file.json will be {}\n```\n\n#### `db.update(fn)`\n\nCalls `fn()` then `db.write()`.\n\n```js\ndb.update((data) => {\n // make changes to data\n // ...\n})\n// files.json will be updated\n```\n\n### Properties\n\n#### `db.data`\n\nHolds 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).\n\nFor example:\n\n```js\ndb.data = 'string'\ndb.data = [1, 2, 3]\ndb.data = { key: 'value' }\n```\n\n## Adapters\n\n### Lowdb adapters\n\n#### `JSONFile` `JSONFileSync`\n\nAdapters for reading and writing JSON files.\n\n```js\nimport { JSONFile, JSONFileSync } from 'lowdb/node'\n\nnew Low(new JSONFile(filename), {})\nnew LowSync(new JSONFileSync(filename), {})\n```\n\n#### `Memory` `MemorySync`\n\nIn-memory adapters. Useful for speeding up unit tests. See [`src/examples/`](src/examples) directory.\n\n```js\nimport { Memory, MemorySync } from 'lowdb'\n\nnew Low(new Memory(), {})\nnew LowSync(new MemorySync(), {})\n```\n\n#### `LocalStorage` `SessionStorage`\n\nSynchronous adapter for `window.localStorage` and `window.sessionStorage`.\n\n```js\nimport { LocalStorage, SessionStorage } from 'lowdb/browser'\nnew LowSync(new LocalStorage(name), {})\nnew LowSync(new SessionStorage(name), {})\n```\n\n### Utility adapters\n\n#### `TextFile` `TextFileSync`\n\nAdapters for reading and writing text. Useful for creating custom adapters.\n\n#### `DataFile` `DataFileSync`\n\nAdapters for easily supporting other data formats or adding behaviors (encrypt, compress...).\n\n```js\nimport { DataFile } from 'lowdb'\nnew DataFile(filename, {\n parse: YAML.parse,\n stringify: YAML.stringify\n})\nnew DataFile(filename, {\n parse: (data) => { decypt(JSON.parse(data)) },\n stringify: (str) => { encrypt(JSON.stringify(str)) }\n})\n```\n\n### Third-party adapters\n\nIf you've published an adapter for lowdb, feel free to create a PR to add it here.\n\n### Writing your own adapter\n\nYou may want to create an adapter to write `db.data` to YAML, XML, encrypt data, a remote storage, ...\n\nAn adapter is a simple class that just needs to expose two methods:\n\n```js\nclass AsyncAdapter {\n read() {\n /* ... */\n } // should return Promise\n write(data) {\n /* ... */\n } // should return Promise\n}\n\nclass SyncAdapter {\n read() {\n /* ... */\n } // should return data\n write(data) {\n /* ... */\n } // should return nothing\n}\n```\n\nFor example, let's say you have some async storage and want to create an adapter for it:\n\n```js\nimport { api } from './AsyncStorage'\n\nclass CustomAsyncAdapter {\n // Optional: your adapter can take arguments\n constructor(args) {\n // ...\n }\n\n async read() {\n const data = await api.read()\n return data\n }\n\n async write(data) {\n await api.write(data)\n }\n}\n\nconst adapter = new CustomAsyncAdapter()\nconst db = new Low(adapter)\n```\n\nSee [`src/adapters/`](src/adapters) for more examples.\n\n#### Custom serialization\n\nTo create an adapter for another format than JSON, you can use `TextFile` or `TextFileSync`.\n\nFor example:\n\n```js\nimport { Adapter, Low } from 'lowdb'\nimport { TextFile } from 'lowdb/node'\nimport YAML from 'yaml'\n\nclass YAMLFile {\n constructor(filename) {\n this.adapter = new TextFile(filename)\n }\n\n async read() {\n const data = await this.adapter.read()\n if (data === null) {\n return null\n } else {\n return YAML.parse(data)\n }\n }\n\n write(obj) {\n return this.adapter.write(YAML.stringify(obj))\n }\n}\n\nconst adapter = new YAMLFile('file.yaml')\nconst db = new Low(adapter)\n```\n\n## Limits\n\nLowdb doesn't support Node's cluster module.\n\nIf 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.\n\nDepending 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.\n\nIf you plan to scale, it's highly recommended to use databases like PostgreSQL or MongoDB instead.\n","readmeFilename":"README.md","users":{"irj":true,"detj":true,"nuer":true,"zeke":true,"demod":true,"fedor":true,"injms":true,"razr9":true,"sbskl":true,"stany":true,"timdp":true,"dkblay":true,"duncup":true,"edobry":true,"foogao":true,"ggeter":true,"hubbly":true,"ierceg":true,"jhx4mp":true,"mestar":true,"phuego":true,"rexpan":true,"tcrowe":true,"wickie":true,"xzlash":true,"yuch4n":true,"ahmehri":true,"croogie":true,"dar5hak":true,"gpuente":true,"jin5354":true,"kezhang":true,"kidfiji":true,"naugtur":true,"xingtao":true,"yanghcc":true,"fabioper":true,"fredcorn":true,"jamchill":true,"lifecube":true,"nukisman":true,"piascikj":true,"roadlabs":true,"ronin161":true,"slowmove":true,"wendellm":true,"zuojiang":true,"heartnett":true,"kkk123321":true,"mondalaci":true,"ahmetertem":true,"aitorllj93":true,"arthurwdev":true,"ashish.npm":true,"bkimminich":true,"brainpoint":true,"donvercety":true,"isaacvitor":true,"jrobinsonc":true,"lius971125":true,"qqqppp9998":true,"rocket0191":true,"vicsandoli":true,"flumpus-dev":true,"frankwinter":true,"michalskuza":true,"cshutchinson":true,"damonoverboe":true,"davidbwaters":true,"jamescostian":true,"natterstefan":true,"nickeltobias":true,"tobiasnickel":true,"calvindurrant":true,"lassevolkmann":true,"stone_breaker":true,"bedriva-magnus":true,"jonniespratley":true,"shanewholloway":true,"icodeforcookies":true,"wstowersguestdna":true,"programmer.severson":true,"cyubahiro":true}}
![](\"https://jsonplaceholder.typicode.com/mockend.svg\")
\n \n