native-json-db v1.0.3

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.

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

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)

Options Object

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)

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)

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)

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

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

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

Options Object

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

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

Options Object

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

Contributing

Docs on contributing coming soon.