Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including node-json-db with all npm packages installed. Try it out:

var nodeJsonDb = require("node-json-db")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

node-json-db v1.0.3

Database using JSON file as storage for Node.JS

Build Status Coverage Status Greenkeeper badge FOSSA Status


A simple "database" that use JSON file for Node.JS.


Add node-json-db to your existing Node.js project.

yarn add node-json-db


Auto Generated

Inner Working


The module store the data using JavaScript Object directly into a JSON file. You can easily traverse the data to reach directly the interesting property using the DataPath. The principle of DataPath is the same as XMLPath.


    test: {
        data1 : {
            array : ['test','array']
        data2 : 5

If you want to fetch the value of array, the DataPath is /test/data1/array To reach the value of data2 : /test/data2 You can of course get also the full object test : /test Or even the root : /


See test for more usage details.

import { JsonDB } from 'node-json-db';
import { Config } from 'node-json-db/dist/lib/JsonDBConfig'

// The second argument is used to tell the DB to save after each push
// If you put false, you'll have to call the save() method.
// The third argument is to ask JsonDB to save the database in an human readable format. (default false)
// The last argument is the separator. By default it's slash (/)
var db = new JsonDB(new Config("myDataBase", true, false, '/'));

// Pushing the data into the database
// With the wanted DataPath
// By default the push will override the old value
db.push("/test1","super test");

// It also create automatically the hierarchy when pushing new data for a DataPath that doesn't exists

// You can also push directly objects
db.push("/test3", {test:"test", json: {test:["test"]}});

// If you don't want to override the data but to merge them
// The merge is recursive and work with Object and Array.
db.push("/test3", {
    json: {
        important : 5
}, false);

This give you this results :

// You can't merge primitive.
// If you do this:

// The data will be overriden

// Get the data from the root
var data = db.getData("/");

// From a particular DataPath
var data = db.getData("/test1");

// If you try to get some data from a DataPath that doesn't exists
// You'll get an Error
try {
    var data = db.getData("/test1/test/dont/work");
} catch(error) {
    // The error will tell you where the DataPath stopped. In this case test1
    // Since /test1/test does't exist.

// Deleting data

// Save the data (useful if you disable the saveOnPush);

// In case you have a exterior change to the databse file and want to reload it
// use this method

TypeScript Support


As of v0.8.0, TypeScript types are included in this package, so using @types/node-json-db is no longer required.


JsonDB isn't exported as default any more. You'll need to change how you load the library.

This change is done to follow the right way to import module.

import { JsonDB } from 'node-json-db';
import { Config } from 'node-json-db/dist/lib/JsonDBConfig'

const db = new JsonDB(new Config("myDataBase", true, false, '/'));

Array Support

You can also access the information stored into arrays and manipulate them.

import { JsonDB } from 'node-json-db';
import { Config } from 'node-json-db/dist/lib/JsonDBConfig'
// The second argument is used to tell the DB to save after each push
// If you put false, you'll have to call the save() method.
// The third argument is to ask JsonDB to save the database in an human readable format. (default false)
const db = new JsonDB(new Config("myDataBase", true, false, '/'));

// This will create an array 'myarray' with the object '{obj:'test'}' at index 0
db.push("/arraytest/myarray[0]", {
}, true);

// You can retrieve a property of an object included in an array
// testString = 'test';
var testString = db.getData("/arraytest/myarray[0]/obj");

// Doing this will delete the object stored at the index 0 of the array.
// Keep in mind this won't delete the array even if it's empty.

Appending in Array

// You can also easily append new item to an existing array
// This set the next index with {obj: 'test'}
db.push("/arraytest/myarray[]", {
}, true);

// The append feature can be used in conjuction with properties
// This will set the next index as an object {myTest: 'test'}
db.push("/arraytest/myarray[]/myTest", 'test', true);

Last Item in Array

// Add basic array
db.push("/arraytest/lastItemArray", [1, 2, 3], true);

// You can easily get the last item of the array with the index -1
// This will return 3

// You can delete the last item of an array with -1
// This will remove the integer "3" from the array

// This will return 2 since 3 just got removed



DataErrorWhen the error is linked to the Data Given
DatabaseErrorLinked to a problem with the loading or saving of the Database.


The Data Path can't be emptyDataErrorThe Database expect to minimum receive the root separator as DataPath.
Can't find dataPath: /XXX. Stopped at YYYDataErrorWhen the full hierarchy of the DataPath given is not present in the Database. It tells you until where it's valid. This error can happen when using getData and delete
Can't merge another type of data with an ArrayDataErrorIf you chose to not override the data (merging) when pushing and the new data is an array but the current data isn't an array (an Object by example).
Can't merge an Array with an ObjectDataErrorSame idea as the previous message. You have an array as current data and ask to merge it with an Object.
DataPath: /XXX. YYY is not an array.DataErrorWhen trying to access an object as an array.
DataPath: /XXX. Can't find index INDEX in array YYYDataErrorWhen trying to access a non-existent index in the array.
Only numerical values accepted for array indexDataErrorAn array can only use number for its indexes. For this use the normal object.
The entry at the path (/XXX) needs to be either an Object or an ArrayDataErrorWhen using the find method, the rootPath need to point to an object or an array to search into it for the wanted value.
Can't Load Database: XXXXDatabaseErrorJsonDB can't load the database for "err" reason. You can find the nested error in error.inner
Can't save the database: XXXDatabaseErrorJsonDB can't save the database for "err" reason. You can find the nested error in error.inner
DataBase not loaded. Can't writeDatabaseErrorSince the database hasn't been loaded correctly, the module won't let you save the data to avoid erasing your database.


Object with seperator in key

Object pushed with key containing the seperator character won't be reachable. See #75.

Please consider the seperator as a reserved character by node-json-db.


James Davis for helping to fix a regular expression vulnerable to catastrophic backtracking.


FOSSA Status

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free