Easy JSON Database

1.5.1 · maintenance · verified Wed Apr 22

Easy JSON Database (easy-json-database) is a lightweight, file-system based database solution for Node.js environments. Currently stable at version 1.5.1, it has seen no new releases in approximately three years, suggesting a maintenance-only status without active feature development. This package differentiates itself through its extreme simplicity, storing all data directly within a single JSON file. It offers basic CRUD operations (set, get, delete, has), numerical manipulations (add, subtract), and array operations (push), along with a `clear` and `all` method. Key features include an optional snapshot mechanism for backups. Unlike robust NoSQL databases (e.g., MongoDB, CouchDB) or relational databases with JSON capabilities (e.g., PostgreSQL), easy-json-database operates by loading and saving the entire JSON file to disk for every write operation, making it suitable only for small datasets and low-concurrency scenarios. It is primarily used in projects requiring minimal setup and direct file storage, such as the 'Scratch For Discord' bot.

Common errors

Warnings

Install

Imports

Quickstart

This quickstart demonstrates basic CRUD operations, numerical increments, array pushes, existence checks, and data clearing using `easy-json-database` in a TypeScript environment. It also shows how to configure snapshots and includes file system cleanup for a reproducible example.

import { Database } from 'easy-json-database';
import { join } from 'path';
import { existsSync, unlinkSync, mkdirSync } from 'fs';

const dbPath = join(__dirname, 'my-test-database.json');
const backupsFolder = join(__dirname, 'backups');

// Ensure backups folder exists
if (!existsSync(backupsFolder)) {
    mkdirSync(backupsFolder, { recursive: true });
}

// Clean up previous database file for a fresh start
if (existsSync(dbPath)) {
    unlinkSync(dbPath);
}

const db = new Database(dbPath, {
    snapshots: {
        enabled: true,
        interval: 60 * 60 * 1000, // 1 hour
        folder: backupsFolder
    }
});

async function runExample() {
    console.log('Database initialized.');

    // Set data
    db.set('user:name', 'Alice');
    console.log(`Set 'user:name' to 'Alice'.`);

    // Get data
    let username = db.get('user:name');
    console.log(`Got 'user:name': ${username}`); // Output: Alice

    // Add to a number
    db.set('user:age', 25);
    db.add('user:age', 5);
    let age = db.get('user:age');
    console.log(`User age after adding 5: ${age}`); // Output: 30

    // Push to an array
    db.set('items', ['apple']);
    db.push('items', 'orange');
    let items = db.get('items');
    console.log(`Items after pushing 'orange': ${JSON.stringify(items)}`); // Output: ["apple","orange"]

    // Check if key exists
    console.log(`Does 'user:name' exist? ${db.has('user:name')}`); // Output: true

    // Delete data
    db.delete('user:name');
    console.log(`Deleted 'user:name'. Does it exist now? ${db.has('user:name')}`); // Output: false

    // Get all data
    let allData = db.all();
    console.log('All remaining data:', JSON.stringify(allData));

    // Clear all data
    db.clear();
    console.log('Database cleared. All data:', JSON.stringify(db.all())); // Output: []

    // Ensure cleanup of the database file after example
    if (existsSync(dbPath)) {
        unlinkSync(dbPath);
        console.log(`Cleaned up database file: ${dbPath}`);
    }
}

runExample().catch(console.error);

view raw JSON →