native-json-db
TypeScript icon, indicating that this package has built-in type declarations

1.0.3 • Public • Published

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

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.

Package Sidebar

Install

npm i native-json-db

Weekly Downloads

1

Version

1.0.3

License

MIT

Unpacked Size

38.1 kB

Total Files

7

Last publish

Collaborators

  • elijahtrillionz