Native-JSON-DB or JSONDb is a NoSQL database system on your local server. With it, you can store data as JSON objects in a file in your server. native-json-db comes with TypeScript support, in fact using TypeScript is encouraged.

NOTE: This library isn't yet efficient for large-scale applications with large ammount of users writing to the database. Use for personal applications or for your portfolio only.

Installation

npm install native-json-db

Note: native-json-db supports importing with both ES modules and commonjs.

Introduction

native-json-db offers a JSONDB class with methods for structuring, adding, removing, and updating data in the json file. Each instance of this class you create can be considered as a collection. For example, let's create a collection of users, and add a few data:

import { JSONDB } from "native-json-db";

const users = new JSONDB('users'); // creates a "users" collection

const schema = {
  type: 'object',
  properties: {
    username: { type: 'string' },
    age: { type: 'number' }
  }
} 

(async () => {
  await users.connect(schema, { writeSync: true, indentSpace: 2 });
})();

function addNewUser() {
  users.create({ username: 'john_doe', age: 24 }) // creates a user's document
}
addNewUser();

The example above represents a collection of users which in turn automatically creates a json file called users.

Schema

native-json-db uses JSON Schema for validating your JSON data.

Each collection you create can have a different schema, but a schema made for a collection must be followed otherwise an error occurs (614).

Pass in your schema object as the first argument of the connect method.

import { JSONDB } from "native-json-db";

const users = new JSONDB('users');

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: 'number' }
  }
}

users.connect(schema);

Methods

All methods are promises

An example that utilises all methods

import { JSONDB } from "native-json-db";

const users = new JSONDB("users");
const schema = {
  type: 'object',
  required: ['name', 'age', 'id'],
  properties: {
    username: { type: 'string' },
    age: { type: 'number' },
    id: { anyOf: [{ type: "number" }, { type: "string" }] } // id can be of type number or string
  }
}

(async () => {
  await users.connect(schema, { writeSync: false, indentSpace: 3 });
})();

// backend programmer
async function addNewUser() {
  try {
    await users.create({
      username: "john_doe",
      id: 1,
      age: 21,
    });
  } catch (err) {
    console.log(err);
  }
}

async function getAllUsers() {
  const res = await users.allData;
  console.log(res); // [{ username: "john_doe", age: 21, id: 1 }]
}

async function findUser() {
  try {
    const res = await users.findOne({ username: "john_doe" });
    console.log(res); // { username: "john_doe", age: 21, id: 1 } 
  } catch (err) {
    console.log(err);
  }
}

async function findUsers() {
  try {
    const res = await users.findMany({ username: "john_doe" });
    console.log(res); // [{ username: "john_doe", age: 21, id: 1 }] 
  } catch (err) {
    console.log(err);
  }
}

async function updateUser() {
  try {
    const res = await users.findOneAndUpdate(
      { username: "john_doe" },
      { age: "25" }
    );
    console.log(res);
  } catch (err) {
    console.log(err, "error"); // throws a schema 614 error, "age" is of type number
  }
}

async function updateMany() {
  try {
    const res = await users.updateMany(
      { username: "john_doe" },
      {
        $inc: { age: 1 }, // increments "age" by 1
      }
    );
    console.log(res); // [{ username: "john_doe", age: 22, id: 1 }]
  } catch (e) {
    console.log(e);
  }
}

async function findOneAndDelete() {
  try {
    const res = await users.findOneAndDelete({ username: "unknown_user" });
    console.log(res);
  } catch (e) {
    console.log(e); // throws a 612 not found error
  }
}

async function deleteMany() {
  try {
    const res = await users.deleteMany(
      { name: "john_doe" }
    );
    console.log(res); // [{ username: "john_doe", age: 22, id: 1 }]
  } catch (e) {
    console.log(e);
  }
}

Connect

The connect method connects your collection to the database. Connecting is done only once for each collection and without connecting you can't use the other methods.

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: 'number' }
  }
}

async function connectToDb() {
  await users.connect(schema, { writeSync: true, indentSpace: 3 });
}

A 613 connection error is thrown if you try to connect more than once for each collection you create.

Parameter(s)

parameter placeholder name	type	description
schema	string	the schema object of the collection
options	object	an object of options, see below for description

Options Object

key	type	description	default
writeSync	boolean	indicates if writing to the json file (collection) is done synchronously or asynchronously	false
indentSpace	number	the indentation space for the JSON object	2

Response

The connect method returns a string ("connected") as response.

Create

The create method creates a new document and attach the data to the collection.

async function addNewuser() {
  const newUser = { username: 'john_doe', age: 21 }
  const res = await users.create(newUser);
  console.log(res); // done
}

Parameter(s)

parameter placeholder name	type	description
data	object	data for the document

Response

The create method returns a string ("done") as response.

findOne

The findOne method finds a document with a piece of data given as filter and returns the first occurrence found.

async function findUser() {
  const res = await users.findOne({ username: 'john_doe' })
  console.log(res)
}

Parameter(s)

parameter placeholder name	type	description
filter	object	filter through the documents in a collection

Response

• When a result is found, the findOne method returns an object. This object being the first occurrence of the filter object found.

• When no result is found, the findOne method resolves to null.

findMany

The findMany method finds a document with a piece of data given as filter and returns all occurrences found.

async function findUser() {
  const res = await users.findOne({ username: 'john_doe' })
  console.log(res)
}

Parameter(s)

parameter placeholder name	type	description
filter	object	filter through the documents in a collection

Response

• When a result is found, the findMany method returns an array of objects. This array being all occurrences of the filter object found.

• When no result is found, the findMany method resolves with an empty array [].

findOneAndUpdate

The findOneAndUpdate method finds a document with a piece of data given as filter and updates the document with a given data.

async function updateUser() {
  // data/users.json = { "users": [{ "username": "john_doe", "age": 21 }] }
  const res = await users.findOneAndUpdate({ username: 'john_doe' }, { username: 'john_doe4real' });
  console.log(res) // { username: 'john_doe4real', age: 21 }
}

Parameters

parameter placeholder name	type	description
filter	object	filter through the documents in a collection
newData	object	the new data to update document with

While the findOneAndUpdate method can be used for updating existing data in a document, it can also be used to add data to a document as long as the data is valid with your schema.

async function updateUser() {
  // data/users.json = { "users": [{ "username": "john_doe4real", "age": 21 }] }
  const res = await users.findOneAndUpdate({ username: 'john_doe4real' }, { followers: 30 });
  console.log(res) // { username: 'john_doe4real', age: 21, followers: 30 }
}

There are special properties that can be used with the newData object to ease up updates like adding or removing from an array, incrementing and decrementing a number.

Special properties

key	type	description	example
$inc	object	increments a number based on a given object	{ $inc: { age: 1 } } - adds 1 to the age value
$dec	object	decrements a number based on a given object	{ $inc: { age: 1 } } - removes 1 from the age value
$push	object	pushes a value to the end of an array	{ $push: { cars: 'bmw' } } - pushes "bmw" to the list of cars
$pop	object	removes the first (0) or last (-1) item of an array	{ $pop: { cars: -1 } } - removes the last item from the list of cars

async function updateUser() {
  // data/users.json = { "users": [{ "username": "john_doe4real", "age": 21, "followers": 30 }] }
  const res = await users.findOneAndUpdate({ username: 'john_doe4real' }, { $inc: { followers: 5, age: 1 } });
  console.log(res) // { username: 'john_doe4real', age: 22, followers: 35 }
}

Response

• When a result is found, the findOneAndUpdate method returns the updated object.

• When no result is found, a 612 - Not Found error is thrown.

updateMany

The updateMany method finds a group of documents with a piece of data given as filter and updates the documents with a given data.

async function updateUsers() {
  // data/users.json = { "users": [{ "username": "john_doe", "age": 21, "student": true }, {"username": "jane_doe", "age": 24, "student": true }] }
  const res = await users.updateMany({ student: true }, { promoted: true });
  console.log(res) // [{ username: 'john_doe', age: 21, student: true, promoted: true }, {username: 'jane_doe', age: 24, student: true, promoted: true }]
}

Parameters

parameter placeholder name	type	description
filter	object	filter through the documents in a collection
newData	object	the new data to update document with
options	object	an object of options for specifying how the update should be

Options Object

key	type	description	default
updateAll	boolean	for updating all documents in a collection	false

The updateAll property when set to true updates all documents in a collection with the new data:

async function updateAllUsers() {
  // data/users.json = { "users": [{ "username": "john_doe", "age": 21, "student": true, "promoted": true }, {"username": "jane_doe", "age": 24, "student": true, "promoted": true }] }
  const res = await users.updateMany({}, { promoted: false }, { updateAll: true });
  console.log(res) // [{ username: 'john_doe', age: 21, student: true, promoted: false }, {username: 'jane_doe', age: 24, student: false }]
}

The special properties available on the findOneAndUpdate method is also available on the updateMany method.

Response

• When a result is found, the updateMany method returns an array of all the updated object.

• When no result is found, a 612 - Not Found error is thrown.

findOneAndDelete

The findOneAndDelete method finds a document with a piece of data given as filter and deletes the document found.

async function deleteUser() {
  // data/users.json = { "users": [{ "username": "john_doe", "age": 21 }] }
  const res = await users.findOneAndDelete({ username: 'john_doe' });
  console.log(res) // { username: 'john_doe4real', age: 21 }
  
  // data/users.json = { "users": [] }
}

Parameters

parameter placeholder name	type	description
filter	object	filter through the documents in a collection

Response

• When a result is found, the findOneAndDelete method returns the deleted object even though it does no longer exist in the collection

• When no result is found, the promise is resolved with an empty object {}.

deleteMany

The deleteMany method finds a group of documents with a piece of data given as filter and deletes the documents.

async function deleteUsers() {
  // data/users.json = { "users": [{ "username": "john_doe", "age": 21 }, {"username": "jane_doe", "age": 24 }] }
  const res = await users.deleteMany({ student: true });
  console.log(res) // [{ username: 'john_doe', age: 21 }, {username: 'jane_doe', age: 24 }]
  
  // data/users.json = { "users": [] }
}

Parameters

parameter placeholder name	type	description
filter	object	filter through the documents in a collection
options	object	an object of options for specifying how the update should be

Options Object

key	type	description	default
deleteAll	boolean	for deleting all documents in a collection	false

The deleteAll property when set to true deletes all documents in a collection:

async function deleteAllUsers() {
  // data/users.json = { "users": [{ "username": "john_doe", "age": 21, "student": true, "promoted": true }, {"username": "jane_doe", "age": 24, "student": true, "promoted": true }] }
  const res = await users.deleteMany({}, { deleteAll: true });
  console.log(res) // [{ username: 'john_doe', age: 21, student: true, promoted: false }, {username: 'jane_doe', age: 24, student: false, promoted: true }]
  
  // data/users.json = { "users": [] }
}

Response

• When a result is found, the deleteMany method returns an array of the deleted objects.

• When no result is found, the promise resolves with an empty array [].

Error Codes

code no	title	description
611	INVALID_DATA_TYPE	error when submitting a new data that isn't an object in JavaScript
612	NOT_FOUND	error when the filter data in any method does not find any occurrence
613	CONNECTION_ERROR	because the schema cannot be compiled more than once, the server must be connected only once in every collection, so this error is thrown if multiple connection is attempted per collection
614	INVALID_SCHEMA_RES:[SCHEMA_ERROR]	all schema data type errors
615	BAD_REQUEST	error when the filter object does not contain key or/and value, exception of the updateMany and deleteMany methods when used to update and/or delete all documents respectively

Contributing

Docs on contributing coming soon.