📖 jsondb

Easy, fast local database system with JSON.

🧧 Table of contents

• 📖 jsondb
  • 🙇‍♂️ Motivation
  • 🔗 Installation
  • 👉 Usage
  • ⚙️ Methods
  • 🔗 Examples
  • ✏️ Formatting
  • 🚀 Publish
  • 💁 License

🙇‍♂️ Motivation

We may need a lightweight database when developing simple applications. We use local database packages to avoid having to connect to any database. That's why I wanted to develop a JSON database application that works as a key-value. In this way, we can store data with keys as if creating a table in a single database file.

🔗 Installation

yarn add @aytacmallkoc/jsondb

or

npm install @aytacmalkoc/jsondb

👉 Usage

Please refer to the table below for the parameters of the methods.

JsonDB uses root directory as default database path.

const JsonDB = require('@aytacmalkoc/jsondb');
const db = new JsonDB('database/db.json');

➡️ Using with options

const db = new JsonDB('database/db.json', {
    uuid: true,
    primaryKey: 'id',
    timestamp: true,
});

⚙️ Options

| Option | Type | Default | Description | |------------|----------|-------------|------------------------------------------| | uuid | boolean | true | Generate unique id for each record. | | primaryKey | string | 'id' | Define identity key | | timestamp | boolean | true | Add created_at and updated_at fields. |

Methods

Methods return different values depending on usage. The add and update, findById, findAll methods return the object or array it affects. The delete, deleteAll, and clear methods return true or false.

add

The add method adds the objects given as parameters.

const user = db.add('users', {
    name: 'Aytac',
    surname: 'Malkoc',
    age: 22,
    email: '[email protected]'
});

console.log(user); // Prints the user object

update

The update method is used to update data by id. Only given keys are updated. For example, we can only update the age of the user created in the add method.

const user = db.update('users', 1, {
    age: 23,
});

where

The where method finds items based on their key-value using comparison operators.

const users = db.where('users', 'age', '>', 18); // return array of users with age greater than 18

Operators

| Operator | Description | Accepted types | |--------------|--------------------------------|-------------------------| | = | Equal | string, number, boolean | | != | Not equal | string, number, boolean | | > | Greater than | string, number, boolean | | < | Less than | string, number, boolean | | >= | Greater than or equal | string, number, boolean | | <= | Less than or equal | string, number, boolean | | like | Like | string, number, boolean | | not like | Not like | string, number, boolean | | between | Between (only numbers) | number[] | | not between | Not between (only numbers) | number[] |

findById

const user = db.findById('users', 1);

findAll

const users = db.findAll('users');

delete

const deleteUser = db.delete('users', 1);

deleteAll

const deleteAll = db.deleteAll('users');

clear

Changes the database file to its default.

const clear = db.clear();

timeAgo

The timeAgo method can be used to convert the timestamp values of the data into readable format.

const user = db.findById('users', 1);
const ago = db.timeAgo(user.created_at);

console.log(ago); // 30 minutes ago

getDatabaseSize

The getDatabaseSize method returns an object containing the values of bytes, kilobytes, megabytes, and gigabytes.

const size = db.getDatabaseSize(); // return size object

console.log(`${size.kb} KB`); // 1.5 KB

⚙️ Method Parameters

| Method | Parameters | |-----------------|---------------------------------| | add | key, value | | where | modelName, key, operator, value | | findById | key, id | | findAll | key | | update | key, id, value | | delete | key, id | | deleteAll | key | | clear | - | | timeAgo | date | | getDatabaseSize | toFixed (default: 2) |

🔗 Examples

You can check the postman workspace collections for detailed examples.

• [ ] NodeJS
• [x] Express
• [ ] React
• [ ] Vue

✏️ Formatting

📝 Lint

yarn lint

👀 Watch changes

yarn prettier-watch

✒️ Format Document

yarn prettier-format

🚀 Publish

yarn publish

or

npm run publish

💁 License

MIT license, Copyright (c) Aytac Malkoc. For more information see LICENSE.