json-lightdb

json-lightdb.js

this is a light weight database based on json format, for small projects and who want to include a small and local database in his project to make it more faster

contribute us on github here

How it actually works ?

this db works with a concept of no sql database which means that you use something like mongodb or firebase, and this smalldb works with creating a documents and inside this document is a json file contains indexes included inside an array and every index has a primary id.

what can you make with this library ?

you can make crud with this library, so you can add a new document and you can update the document and insert to it,
you can read the data, update the document or the index, delete the document, delete an index from the document.

Installation ?

1. open your cmd and run this command from your project folder and write :

npm install json-lightdb --save
 

After that you can now use this light weight database in your project.

How to use it ?

require it to your main file of project

 
const jsonDB = require("json-lightdb");

** the library automatically will create a new directory in your project if you didn't create it and will call it as ".data" and this folder will contains the json files of data**

---

to create a new document use this function

 
jsonDB.createDocument(direction, folderName, data, callback);

1. the first parameter is the directory of document, and the library goes automatically to .data folder and the directory which you write will be created inside the .data folder.

2. the second param is the name of document or json file which you want to create

3. the third param (optional param) and this param you write the data which you want to put inside the document and it should be n array and inside this array the objects which you want.

4. the fourth param is a callback function returns with the results of creating document with 2 params the first one is the error to check errors and the second is the data if the proccess run successfully.

---

to read the document

jsonDB.readDocument(dir, file, callback);
 

1. dir: is the directory which contains the document
2. file: is the name of directory
3. callback: is a callback function returns with two params the first one is err to check the errors and the second one is the data of the document if there are no errors.

to update the document

with this function you can update the document with inserting a new index or update and edit a current index

jsonDB.updateDocument(dir, file, callback);

1. dir: is the directory which contains the document
2. file: is the name of directory
3. callback: is a function has two params the first one is error to check if there are errors while updating the document and the second one is a data which exist on the file included inside array and to update a specific index you can chose the index or make a loop to indexes and choose the index, and the data will be edited automatically, and also you can insert a new index to the document with push function like this:

/* to push a new index to document*/
jsonDB.updateDocument(dir, file, function (err, data) {
  data.push({username: "jsondb", "type": "database"});
});
/* end */
/* to update a current index */
  jsonDB.updateDocument(dir, file, function (err, data) {
    // to edit the first index of data array
    data[0].type = "db";
  })
/* end */

to find a specific index and execute it from the document:

We allow to you a good feature to access on a specific index inside the document with function contains some methods like find indexes with id or find indexes with property of index and also you can specify the limit of indexes which you want to execute and the arrangement of indexes from new to old and visa versa.

jsonDB.findIndex(dir, file, get, callback);

dir: is the direction of container folder of document file: is the document name get: is an object contains many properties and the get object contains these methods :

get.way: with this method you specify the way of calling the data and you can write one property of the following:

1.    get.way= "index"

   it means that you want to call a specific index with his number so for example if you want to call the index number four of document so you write :

     get.way = "index";
     get.index = 3

2.    get.way = "prop"

   this method you call it when you want to execute index based on its properties. for example if you want to extract index contains a property called username = "john", so you can write something like this

```javascript
  get.way = "prop"
  get.props = {
    username: "john"
  }
```
 and automatically the library will execute all indexes which contain this username, and you can specify multiple properties to search in indexes.

1. if you want to execute all indexes without search you may not need to specify the way method

2. if you want to execute the indexes from new to old you write the arrange method like this

     get.arrange = "new";

   and the library will execute the data of document from new to old.

3. the data normally executes from old to new

4. if you want to execute a random data so you can define the arrange method to "random" like this:

     get.arrange = "random";

   and the program will execute a random indexes

5. for all above cases you can specify the limit method to extract a given number of data like this

     // execute 6 indexes for example
     get.limit = 6;

to delete a whole document

you can delete a whole document with this function

  jsonDB.deleteDocument(dir, file, callback);

dir: the name if container folder of document file: the document name whic you wanna delete callback: is a callback function returns with error if there is error while deleting the document and in this function we use the native code of node.js to delete a file with fs.unlink() function.

to remove a specific index from the document

  jsonDB.removeIndex(dir, file, index, callback);

dir: the name if container folder of document
file: the document name whic you wanna delete
index:you can specify in this parameters one of the following :

1. you can specify the number of indiex inside the data array for example remove the index number one so you define the index to 0

2. specify a whole objec so the index could be defined as an onject like that {username: "john doe"} and the similar object which exists inside the array only will be deleted.

3. define the id of the index which you want to delete.

callback: is a callback function returns with two params:
error: to check if there is error while removing the index
success: this param returns with removed message to make sure that the index removed successfully

Example

  const jsonDB = require("json-lightdb");
 
  // create a new document called users in the directory called test
 
  jsonDB.createDocument("test", "users", function (err, data) {
    if (err) {
      console.log(err)
    }
    if (data) {
      // if you didnt passed an array of data to the function the data param returns with an empty array
      console.log(data)
    }
  });
 
  // to update a document with inserting a new index
  jsonDB.updateDocument("test", "users", function (err, data) {
    // check if there are error while uploading the data
    if (err) {
      console.log(err)
    }
    if (data) {
      // returns with array of data indexes
 
      // to push a new index to data array
      var newUser = {
        username: "john doe",
        email: "[e-mail]",
        "password": "johnDoe2",
        country: "USA"
      }
      data.push(newUser);
    }
  });
 
  // to update a current index
  jsonDB.updateDocument("test", "users", function (err, data) {
     // choose the index
    data[0].username = "tarek salem";
    // data saved automatically
  });
 
  // to read a document
  jsonDB.readDocument("test", "users", function (err, data) {
    // check errors
    if (err) {
      console.log(err)
    }
    if (data) {
 
      console.log(data)
 
    // will output an array of data
    }
  })
 
  // to find a specific indexes
 
  // define an object with methods of execution
  var get = {
 
  // define the way of getting the indexes
 
  way: "prop",
 
  // define the properties of users to search in
 
  props: {
      username: "john",
      email: "[e-mail]"
    }
 
  // get 10 indexes of users
 
  limit: 10
  }
  jsonDB.findIndex("test", "users", get, function (err, data) {
 
        // check errors
    if (err) {
      console.log(err)
    }
    if (data) {
 
      console.log(data)
 
    // will output an array of data
    }
 
  })
 
  // to remove  the whole document
  jsonDB.deleteDocument("test", "users", function (err) {
      // check the error while removing the document
      if (err) {
        console.log(err)
      }
  });
 
  // remove a specific index
    // we will delete the user based on its index in the array so we will delete the user number one
 
  jsonDB.removeIndex("test", "users", 0, function (err) {
       // check the error while removing the index
      if (err) {
        console.log(err)
      }
  });
 
  // remove the user based on its id, so for example we have the following user
  var user = {username:"john",_id:"_zjlx8trim3c",_index:0};
  jsonDB.removeIndex("test", "users", user._id, function (err) {
       // check the error while removing the index
      if (err) {
        console.log(err)
      }
  });
 
    // remove the user based on the whole index, so for example we have the following user
  var user = {username:"john",_id:"_zjlx8trim3c",_index:0};
  jsonDB.removeIndex("test", "users", user, function (err) {
       // check the error while removing the index
      if (err) {
        console.log(err)
      }
  });