TypeScript icon, indicating that this package has built-in type declarations

2.0.0 • Public • Published

Simple JSONdb npm npm Minimum NodeJS version Dependents (via npm bundle size

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?


npm install simple-json-db



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 section for more details.


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


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


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


The key parameter must be a string. The function returns as per the delete operator if the key exists, else it returns undefined.

Sync to disk


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

Access JSON storage


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.


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

Package Sidebar


npm i simple-json-db

Weekly Downloads






Unpacked Size

16.9 kB

Total Files


Last publish


  • nmaggioni