# simple-json-db

> A simple, no-frills, JSON storage engine for Node.JS

Latest version **2.0.0** (published 2022-03-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install simple-json-db
pnpm add simple-json-db
yarn add simple-json-db
bun add simple-json-db
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2022-03-07 |
| First published | 2016-07-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=10.0 |
| Dependencies | 0 |
| Unpacked size | 16.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 82 |
| Author | Niccolò Maggioni |
| Maintainers | nmaggioni |
| Keywords | json, db, database, storage, engine, simple, node, nodejs |

## Links

- npm: https://www.npmjs.com/package/simple-json-db
- Repository: https://github.com/nmaggioni/Simple-JSONdb
- Homepage: https://github.com/nmaggioni/Simple-JSONdb#readme
- Issues: https://github.com/nmaggioni/Simple-JSONdb/issues
- npm.io page: https://npm.io/package/simple-json-db

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 2.0.0 (latest) — 2022-03-07
- 1.3.0 — 2022-03-04
- 1.2.3 — 2021-02-18
- 1.2.2 — 2020-01-17
- 1.2.1 — 2016-09-06
- 1.2.0 — 2016-08-25
- 1.1.0 — 2016-07-14

## README

# Simple JSONdb [![npm](https://img.shields.io/npm/v/simple-json-db)](https://www.npmjs.com/package/simple-json-db) [![npm](https://img.shields.io/npm/dw/simple-json-db)](https://www.npmjs.com/package/simple-json-db) [![Minimum NodeJS version](https://img.shields.io/node/v/simple-json-db)](https://www.npmjs.com/package/simple-json-db) [![Dependents (via libraries.io)](https://img.shields.io/librariesio/dependents/npm/simple-json-db)](https://libraries.io/npm/simple-json-db/dependents) ![npm bundle size](https://img.shields.io/bundlephobia/min/simple-json-db)

A simple, no-frills, JSON **key-value** storage engine for Node.JS with full test coverage.

> [What is a key-value storage and when to use it?](https://redislabs.com/nosql/key-value-databases/)

## Installation

`npm install simple-json-db`

## Usage

### Instantiation
```javascript
const JSONdb = require('simple-json-db');
const db = new JSONdb('/path/to/your/storage.json');
```

The prototype of the constructor is `new JSONdb(string, [object])`, and you can supply the optional `options` object by giving it as second parameter:

```
const db = new JSONdb('/path/to/your/storage.json', { ... });
```

See the [Options](#options) section for more details.

#### Options

All keys are optional and will default to a safe value.

| **Key**     | **Value type**               | **Description**                                                   | **Default value**                   |
|-------------|------------------------------|-------------------------------------------------------------------|-------------------------------------|
| asyncWrite  | _Boolean_                    | Enables the storage to be asynchronously written to disk.         | _**false**_ (synchronous behaviour) |
| syncOnWrite | _Boolean_                    | Makes the storage be written to disk after every modification.    | _**true**_                          |
| jsonSpaces  | _Number_                     | The number of spaces used for indentation in the output JSON.     | _**4**_                             |
| stringify   | _Function(object) => string_ | A stringifier function to serialize JS objects into JSON strings. | _**JSON.stringify**_                |
| parse       | _Function(string) => object_ | A parser function to deserialize JSON strings into JS objects.    | _**JSON.parse**_                    |

### Set a key
`db.set('key', 'value');`

The `key` parameter must be a string, `value` can be whatever kind of object can be stored in JSON format. _`JSON.stringify()` is your friend!_

### Get a key
`db.get('key');`

The `key` parameter must be a string. If the key exists its value is returned, if it doesn't the function returns `undefined`.

### Check a key
`db.has('key');`

The `key` parameter must be a string. If the key exists `true` is returned, if it doesn't the function returns `false`.

### Delete a key

`db.delete('key');`

The `key` parameter must be a string. The function returns [as per the _delete_ operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/delete#Return_value) if the key exists, else it returns `undefined`.

### Sync to disk
`db.sync();`

This function writes the JSON storage object to the file path specified as the parameter of the main constructor. Consult the [Options](#options) section for usage details; on default options there is no need to manually invoke it.

### Access JSON storage
`db.JSON();`

This will return **a copy** of the internal JSON storage object, for you to tinker with and loop over.

### Replace JSON storage
`db.JSON({ data });`

Giving a parameter to the `JSON` function makes the object passed replace the internal one. _Be careful, as there's no way to recover the old object if the changes have already been written to disk._

## Tests

Run `npm ci` to install the testing dependencies and `npm test` to start the test suite.

---
_Source: https://npm.io/package/simple-json-db · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._