@synchjs/jsondb

A robust, lodash-powered, lightweight JSON database with support for deep nested object manipulation using dot notation.

Features

• 🚀 Lightweight & Fast: Minimal overhead, perfect for small to medium-sized projects or configuration management.
• 🔧 Lodash Powered: Leverages the power of lodash for reliable deep object access and manipulation.
• 🎯 Dot Notation Support: Access, set, delete, and check nested properties easily (e.g., user.settings.theme).
• 💾 Auto-Save: Automatically persists changes to a JSON file on disk.
• 📦 TypeScript Ready: Written in TypeScript with full type definitions included.

Installation

npm install @synchjs/jsondb
# or
bun add @synchjs/jsondb
# or
yarn add @synchjs/jsondb

Usage

import { JsonDB } from "@synchjs/jsondb";
import path from "node:path";

// Initialize the database
const db = new JsonDB(path.join(process.cwd(), "db.json"));

// Set values (supports dot notation)
db.set("user.name", "John Doe");
db.set("user.settings.theme", "dark");
db.set("app.config.port", 8080);

// Get values
const name = db.get<string>("user.name"); // "John Doe"
const theme = db.get("user.settings.theme"); // "dark"
const config = db.get("app.config"); // { port: 8080 }

// Check existence
if (db.has("user.settings")) {
  console.log("Settings exist!");
}

// Delete values
db.delete("user.settings.theme");

// Get all data
console.log(db.getAll());

// Clear database
db.clear();

API

new JsonDB(filePath: string)

Creates a new instance of the database. If the file does not exist, it will be created.

set(key: string, value: any): void

Sets a value in the database.

• key: The path to the property. Supports dot notation (e.g., a.b.c).
• value: The value to set.

get<T>(key: string): T | undefined

Retrieves a value from the database.

• key: The path to the property.
• Returns the value or undefined if not found.

has(key: string): boolean

Checks if a key exists in the database.

• key: The path to the check.

delete(key: string): void

Removes a key and its value from the database.

• key: The path to remove.

getAll(): Record<string, any>

Returns the entire database object.

clear(): void

Clears all data in the database and saves the empty state to the file.

Test Statistics

The library is fully tested with 100% pass rate.

test\JsonDB.test.ts:
✓ JsonDB > should set and get a simple value
✓ JsonDB > should return undefined for non-existent key
✓ JsonDB > should check if key exists with has()
✓ JsonDB > should delete a key
✓ JsonDB > should handle nested objects with dot notation
✓ JsonDB > should has() with dot notation
✓ JsonDB > should delete nested keys with dot notation
✓ JsonDB > should load existing data from file

 8 pass
 0 fail
 16 expect() calls
Ran 8 tests across 1 file. [90.00ms]

License

ISC