JSON-SyncDB

JSON-SyncDB is a lightweight, zero-dependency Node.js library that provides a simple, file-based database solution for small projects. It uses a JSON file as a data store and automatically synchronizes any changes to an in-memory object back to the file.

Features

• Simple API: Easy to get started with minimal setup.
• Automatic Synchronization: Changes to the data object are instantly written to the JSON file.
• Zero Dependencies: Lightweight and easy to integrate.
• Human-Readable Option: Can format the JSON output for easy inspection.

Installation

npm install json-syncdb

Usage

Initialization

First, import the JSONDB class and create a new instance. If the specified JSON file doesn't exist, it will be created automatically.

const { JSONDB } = require("json-syncdb");

// Create a new database instance, linked to './db.json'
const db = new JSONDB("./db.json");

// To create a human-readable (indented) JSON file, pass `true` as the second argument:
// const db_readable = new JSONDB("./db_readable.json", true);

Reading and Writing Data

All data is accessed and manipulated through the db.data property. Any modification (adding, updating, or deleting properties) is automatically saved to the corresponding JSON file.

const { JSONDB } = require("json-syncdb");

// Initialize the database with a readable format
var db = new JSONDB("./users.json", true);

// Check if data exists, if not, initialize it
if (!db.data.users) {
  db.data.users = [];
  console.log("Initialized users array.");
}

// Add a new user object to the array
db.data.users.push({ id: 1, name: "Alice", age: 30 });
console.log("Added Alice.");
// The 'users.json' file is now automatically updated.

// Add another user
db.data.users.push({ id: 2, name: "Bob", age: 25 });
console.log("Added Bob.");

// Update data
const userToUpdate = db.data.users.find(user => user.id === 1);
if (userToUpdate) {
  userToUpdate.age = 31; // This change triggers a file write
  console.log("Updated Alice's age.");
}

// Add a new top-level property
db.data.settings = { theme: "dark" };
console.log("Added settings.");

After running the code above, the users.json file will contain:

{
  "users": [
    {
      "id": 1,
      "name": "Alice",
      "age": 31
    },
    {
      "id": 2,
      "name": "Bob",
      "age": 25
    }
  ],
  "settings": {
    "theme": "dark"
  }
}

API

new JSONDB(filePath, readable)

Creates a new database instance.

• filePath (String, Optional): The path to the JSON file you want to use for storage. Default: './data.json'.
• readable (Boolean, Optional): If true, the JSON file will be written in a human-readable, indented format. Default: false.

How It Works

The library loads the JSON file content into an object upon initialization. This object is then wrapped in a recursive JavaScript Proxy. The proxy's set handler intercepts any property assignments, and upon each change, it rewrites the entire data object to the specified JSON file using fs.writeFileSync.

License

This project is licensed under the MIT License. See the LICENSE file for details.