quartz.db v1.0.0

!IMPORTANT quartz.db is based on quick.db version 9.1.7 This project is licensed under the GPL 3.0 License. For more details, please refer to the LICENSE file.

quartz.db

A lightweight, user-friendly database wrapper for Node.js that provides persistent data storage with multiple driver options.

Features

• 🔧 Simple API - Intuitive methods
• 💾 Persistent Storage - Data persists between restarts
• 🗄️ Multiple Storage Options - Support for SQLite, MySQL, MongoDB, JSON and in-memory storage
• ⚡ Zero Configuration - Works out of the box with SQLite
• 🛡️ Type Safe - Written in TypeScript with full type definitions
• 🌱 Beginner Friendly - Straightforward documentation and examples

Installation

npm install --global node-gyp

node-gyp --python /path/to/python

To install quartz.db, run the following command in your terminal:

# Using bun
bun add quartz.db

# Using pnpm
pnpm add quartz.db

# Using yarn
yarn add quartz.db

# Using npm
npm install quartz.db

Ensure you have Node.js and npm installed on your machine. You can verify your installation by running:

node -v
npm -v

If you encounter any issues during installation, please refer to the troubleshooting guide for assistance. Windows users may need to do additional steps listed here.

Examples

const { Database } = require('quartz.db');
const db = new Database(); // will make a quarkdb.json in the root folder
// if you want to specify a path you can do so like this
// const db = new Database({ filePath: 'source/to/path/data.json' });

(async () => {
    // self calling async function just to get async
    // Setting an object in the database:
    await db.set('userInfo', { difficulty: 'Easy' });
    // -> { difficulty: 'Easy' }

    // Getting an object from the database:
    await db.get('userInfo');
    // -> { difficulty: 'Easy' }

    // Getting an object property from the database:
    await db.get('userInfo.difficulty');
    // -> 'Easy'

    // Setting an object in the database:
    await db.set('userInfo', { difficulty: 'Easy' });
    // -> { difficulty: 'Easy' }

    // Pushing an element to an array (that doesn't exist yet) in an object:
    await db.push('userInfo.items', 'Sword');
    // -> { difficulty: 'Easy', items: ['Sword'] }

    // Adding to a number (that doesn't exist yet) in an object:
    await db.add('userInfo.balance', 500);
    // -> { difficulty: 'Easy', items: ['Sword'], balance: 500 }

    // Repeating previous examples:
    await db.push('userInfo.items', 'Watch');
    // -> { difficulty: 'Easy', items: ['Sword', 'Watch'], balance: 500 }
    await db.add('userInfo.balance', 500);
    // -> { difficulty: 'Easy', items: ['Sword', 'Watch'], balance: 1000 }

    // Fetching individual properties
    await db.get('userInfo.balance'); // -> 1000
    await db.get('userInfo.items'); // ['Sword', 'Watch']
})();

Example With MySQLDriver

# Using bun
bun add quartz.db mysql2

# Using pnpm
pnpm add quartz.db mysql2

# Using yarn
yarn add quartz.db mysql2

# Using npm
npm install quartz.db mysql2

const { Database, MySQLDriver } = require('quartz.db');
(async () => {
    const mysqlDriver = new MySQLDriver({
        host: 'localhost',
        user: 'me',
        password: 'secret',
        database: 'my_db',
    });

    await mysqlDriver.connect(); // connect to the database **this is important**

    const db = new Database({ driver: mysqlDriver });
    // Now you can use quartz.db as normal

    await db.set('userInfo', { difficulty: 'Easy' });
    // -> { difficulty: 'Easy' }
})();

Example With MongoDriver

# Using bun
bun add quartz.db mongoose

# Using pnpm
pnpm add quartz.db mongoose

# Using yarn
yarn add quartz.db mongoose

# Using npm
npm install quartz.db mongoose

const { Database, MongoDriver } = require('quartz.db');
(async () => {
    const mongoDriver = new MongoDriver('mongodb://localhost/quarkdb');

    await mongoDriver.connect();

    const db = new Database({ driver: mongoDriver });
    // Now you can use quartz.db as normal

    await db.set('userInfo', { difficulty: 'Easy' });
    // -> { difficulty: 'Easy' }

    await driver.close();
    // disconnect from the database
})();

Example With JSONDriver

const { Database, JSONDriver } = require('quartz.db');
const jsonDriver = new JSONDriver();
const db = new Database({ driver: jsonDriver });

await db.set('userInfo', { difficulty: 'Easy' });

Example With BsonDriver

# Using bun
bun add quartz.db bson

# Using pnpm
pnpm add quartz.db bson

# Using yarn
yarn add quartz.db bson

# Using npm
npm install quartz.db bson

const { Database, BsonDriver } = require('quartz.db');
const bsonDriver = new BsonDriver();
const db = new Database({ driver: bsonDriver });

await db.set('userInfo', { difficulty: 'Easy' });

Example With MemoryDriver

Note: In-memory database is not persistent and is suitable for temporary caching.

const { Database, MemoryDriver } = require('quartz.db');
const memoryDriver = new MemoryDriver();
const db = new Database({ driver: memoryDriver });

await db.set('userInfo', { difficulty: 'Easy' });