simple-json-db
Version:
A simple, no-frills, JSON storage engine for Node.JS
78 lines (48 loc) • 3.9 kB
Markdown
# Simple JSONdb [](https://www.npmjs.com/package/simple-json-db) [](https://www.npmjs.com/package/simple-json-db) [](https://www.npmjs.com/package/simple-json-db) [](https://libraries.io/npm/simple-json-db/dependents) 
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.