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

Breaking changes since v1.x.x

v2.0.0

JsonDB is now using the concept of async/await for all its calls since we read from the database file on demand and depending on how the database is configured, we might write at each push.

• You're now forced to use the Config object to setup JsonDB
• Every method is now asynchronous

Installation

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

YARN:

1yarn add node-json-db

NPM:

1npm i node-json-db

Documentation

Auto Generated

Inner Working

Data

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

Example

1{
2    test: {
3        data1 : {
4            array : ['test','array']
5        },
6        data2 : 5
7    }
8}

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 also get the full object test : /test Or even the root : /

Usage

See test for more usage details.

1import { JsonDB, Config } from 'node-json-db';
2
3// The first argument is the database filename. If no extension is used, '.json' is assumed and automatically added.
4// The second argument is used to tell the DB to save after each push
5// If you set the second argument to false, you'll have to call the save() method.
6// The third argument is used to ask JsonDB to save the database in a human readable format. (default false)
7// The last argument is the separator. By default it's slash (/)
8var db = new JsonDB(new Config("myDataBase", true, false, '/'));
9
10// Pushing the data into the database
11// With the wanted DataPath
12// By default the push will override the old value
13await db.push("/test1","super test");
14
15// When pushing new data for a DataPath that doesn't exist, it automatically creates the hierarchy
16await db.push("/test2/my/test",5);
17
18// You can also push objects directly
19await db.push("/test3", {test:"test", json: {test:["test"]}});
20
21// If you don't want to override the data but to merge them
22// The merge is recursive and works with Object and Array.
23await db.push("/test3", {
24    new:"cool",
25    json: {
26        important : 5
27    }
28}, false);
29
30/*
31This give you this results :
32{
33   "test":"test",
34   "json":{
35      "test":[
36         "test"
37      ],
38      "important":5
39   },
40   "new":"cool"
41}
42*/
43
44// You can't merge primitives.
45// If you do this:
46await db.push("/test2/my/test/",10,false);
47
48// The data will be overriden
49
50// Get the data from the root
51var data = await db.getData("/");
52
53// Or from a particular DataPath
54var data = await db.getData("/test1");
55
56// If you try to get some data from a DataPath that doesn't exist
57// You'll get an Error
58try {
59    var data = await db.getData("/test1/test/dont/work");
60} catch(error) {
61    // The error will tell you where the DataPath stopped. In this case test1
62    // Since /test1/test does't exist.
63    console.error(error);
64};
65
66// Easier than try catch when the path doesn't lead to data
67// This will return `myDefaultValue` if `/super/path` doesn't have data, otherwise it will return the data
68var data = await db.getObjectDefault<string>("/super/path", "myDefaultValue");
69
70// Deleting data
71await db.delete("/test1");
72
73// Save the data (useful if you disable the saveOnPush)
74await db.save();
75
76// In case you have an exterior change to the databse file and want to reload it
77// use this method
78await db.reload();
79

TypeScript Support

v0.8.0

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

v1.0.0

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.

1import { JsonDB, Config } from 'node-json-db';
2
3const db = new JsonDB(new Config("myDataBase", true, false, '/'));

Typing

With TypeScript, you have access to a new method: getObject that will take care of typing your return object.

1import { JsonDB, Config } from 'node-json-db';
2
3const db = new JsonDB(new Config("myDataBase", true, false, '/'));
4
5interface FooBar {
6    Hello: string
7    World: number
8}
9const object = {Hello: "World", World: 5} as FooBar;
10
11await db.push("/test", object);
12
13// Will be typed as FooBar in your IDE
14const result = await db.getObject<FooBar>("/test");

Array Support

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

1import { JsonDB, Config } from 'node-json-db';
2
3// The first argument is the database filename. If no extension is used, '.json' is assumed and automatically added.
4// The second argument is used to tell the DB to save after each push
5// If you set the second argument to false, you'll have to call the save() method.
6// The third argument is used to ask JsonDB to save the database in a human readable format. (default false)
7const db = new JsonDB(new Config("myDataBase", true, false, '/'));
8
9// This will create an array 'myarray' with the object '{obj:'test'}' at index 0
10await db.push("/arraytest/myarray[0]", {
11    obj:'test'
12}, true);
13
14// You can retrieve a property of an object included in an array
15// testString = 'test';
16var testString = await db.getData("/arraytest/myarray[0]/obj");
17
18// Doing this will delete the object stored at the index 0 of the array.
19// Keep in mind this won't delete the array even if it's empty.
20await db.delete("/arraytest/myarray[0]");

Appending in Array

1// You can also easily append a new item to an existing array
2// This sets the next index with {obj: 'test'}
3await db.push("/arraytest/myarray[]", {
4    obj:'test'
5}, true);
6
7
8// The append feature can be used in conjuction with properties
9// This will set the next index as an object {myTest: 'test'}
10await db.push("/arraytest/myarray[]/myTest", 'test', true);
11

Last Item in Array

1// Add basic array
2await db.push("/arraytest/lastItemArray", [1, 2, 3], true);
3
4// You can easily get the last item of the array with the index -1
5// This will return 3
6await db.getData("/arraytest/lastItemArray[-1]");
7
8
9// You can delete the last item of an array with -1
10// This will remove the integer "3" from the array
11await db.delete("/arraytest/lastItemArray[-1]");
12
13// This will return 2 since 3 just got removed
14await db.getData("/arraytest/lastItemArray[-1]");

Count for Array

1//
2await db.push("/arraytest/list", [{id: 65464646155, name: "test"}], true);
3
4// You can request for the total number of elements, in this case, 1
5let numberOfElements = await db.count("/arraytest/list");

Get Index in Array

1
2// You can have the current index of an object
3await db.push("/arraytest/myarray", [{id: 65464646155, name: "test"}], true);
4await db.getIndex("/arraytest/myarray", 65464646155);
5// The default property is 'id'
6// You can add another property instead
7await db.getIndex("/arraytest/myarray", "test", "name");
8
9// It's useful if you want to delete an object
10await db.delete("/arraytest/myarray[" + await db.getIndex("/arraytest/myarray", 65464646155) + "]");

Nesting in Array

1// You can easily access any nested array and their object
2// You can also append another array to a nested array
3await db.push("/arraytest/myarray",
4[
5  [
6    {
7      obj: 'test'
8    },
9    {
10      obj: 'hello'
11    }
12  ],
13  [
14    {
15      obj: 'world'
16    }
17  ]
18]
19, true);
20
21// This will return the first object (obj: 'test')
22
23await db.getData("/arraytest/myarray[0][0]");
24

Getting Item path in Array by id or Another key

1
2await db.push("/myarray",
3[
4    {
5      id: '1',
6      obj: 'test'
7    },
8    {
9      id: '2',
10      obj: 'hello'
11    },
12    {
13      id: '3',
14      obj: 'hello',
15      children:[
16        {
17          id: '1',
18          desc: 'a sub item'
19        }
20      ]
21    },
22]
23, true);
24
25// You can easily get the path of any nested array and its child object by a property using the route style syntax, the default is the object's "id" property
26
27const itemPath = db.fromPath("/myarray/3/children/1");
28

Exception/Error

Type

Type	Explanation
DataError	When the error is linked to the Data Given
DatabaseError	Linked to a problem with the loading or saving of the Database.

Errors

Error	Type	Explanation
The Data Path can't be empty	DataError	The Database expects to receive at least the root separator as part of the DataPath.
Can't find dataPath: /XXX. Stopped at YYY	DataError	When the full hierarchy of the provided DataPath is not present in the Database, it indicates the extent of its validity. This error can occur when using the getData and delete operations.
Can't merge another type of data with an Array	DataError	This occurs if you chose not to override the data when pushing (merging) and the new data is an array, but the current data isn't an array (an Object for example).
Can't merge an Array with an Object	DataError	Similar to the previous message, you have an array as the current data and request to merge it with an object.
DataPath: /XXX. YYY is not an array.	DataError	When trying to access an object as an array.
DataPath: /XXX. Can't find index INDEX in array YYY	DataError	When trying to access a non-existent index in the array.
Only numerical values accepted for array index	DataError	An 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 Array	DataError	When using the find method, the rootPath needs to point to an object or an array to search within it for the desired value.
Can't Load Database: XXXX	DatabaseError	JsonDB can't load the database for "err" reason. You can find the nested error in error.inner
Can't save the database: XXX	DatabaseError	JsonDB can't save the database for "err" reason. You can find the nested error in error.inner
DataBase not loaded. Can't write	DatabaseError	Since the database hasn't been loaded correctly, the module won't let you save the data to avoid erasing your database.

Limitations

Object with separator in key

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

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

Contributors

Jamie Davis 🛡️	sidblommerswork 💻 ⚠️	Max Huber 💻	Adam 💻 📖	Divine Anum 📖	Michał Fedyna 📖	alex.query 💻
Tony Trupe ⚠️

Special Thanks

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

License