MezmerDB 🚀

MezmerDB is a lightweight, file-persistent JSON database for JavaScript and TypeScript projects. It features a MongoDB-inspired API, making it incredibly easy to use for web apps, CLI tools, prototypes, and small projects.

✨ Features

• 📦 Zero Dependencies: Extremely lightweight and fast.
• 🍃 MongoDB-inspired API: Use familiar methods like insertOne, find, updateOne, and deleteOne.
• 📁 File Persistence: Data is automatically saved to a human-readable JSON file.
• 🛠️ TypeScript Support: Full type safety and generics included out of the box.
• 📂 Collections: Organize your data into logical groups within a single database.
• 🚀 Easy Setup: Start using it in seconds without any complex configuration.

📦 Installation

Since this is a package you created, you can install it locally or use it directly:

npm install mezmerdb

🚀 Quick Start

1. In a Node.js Project (CommonJS)

const { MezmerDB } = require('mezmerdb');

// Initialize the database with a filename
const db = new MezmerDB('my-database.json');

// Access a collection
const users = db.collection('users');

// Insert a document
const newUser = users.insertOne({ name: 'Shib', role: 'Admin' });
console.log('Inserted:', newUser);

// Find documents
const admins = users.find({ role: 'Admin' });
console.log('Admins:', admins);

2. In a TypeScript Project

import { MezmerDB } from 'mezmerdb';

interface User {
  name: string;
  role: string;
}

const db = new MezmerDB('data.json');
const users = db.collection<User>('users'); // Fully typed!

users.insertOne({ name: 'Antigravity', role: 'AI Assistant' });

🔍 API Reference & Examples

MezmerDB Class

The entry point for your database.

| Method | Description | | :--- | :--- | | constructor(filePath) | Initializes the database and loads data from the specified JSON file. | | collection(name) | Returns a Collection instance for the given name. |

Collection Class (The Methods)

insertOne(document)

Adds a new document to the collection.

const user = users.insertOne({ name: 'Shib', role: 'Developer' });
// Returns: { name: 'Shib', role: 'Developer', _id: '...' }

find(query)

Returns an array of all documents that match the query. If query is {} or omitted, returns all documents.

const allUsers = users.find();
const admins = users.find({ role: 'Admin' });

findOne(query)

Returns the first document that matches the query, or null if none found.

const shib = users.findOne({ name: 'Shib' });

updateOne(query, updateData)

Updates the first document matching the query with the new data.

users.updateOne({ name: 'Shib' }, { role: 'Lead Dev' });

deleteOne(query)

Deletes the first document matching the query.

const success = users.deleteOne({ name: 'OldUser' });
// Returns: true or false

count()

Returns the total number of documents in the collection.

const total = users.count();

🛠️ Advanced Usage

Script Environment (Non-Project)

You can use MezmerDB in a simple .js file without a full package.json setup. Just make sure the index.js file is in the same directory:

// simple-script.js
const { MezmerDB } = require('./index'); // Point to the file directly

const db = new MezmerDB('offline-data.json');
const items = db.collection('tasks');

items.insertOne({ task: 'Write README', status: 'Done' });
console.log('All Tasks:', items.find());

Querying with Multiple Fields

const match = users.findOne({ 
    role: 'Admin', 
    status: 'active' 
});

Updating Documents

// Updates the 'role' of the first user named 'Shib'
users.updateOne({ name: 'Shib' }, { role: 'Lead Developer' });

🛡️ Best Practices

1. Human Readable: The .json file generated is human-readable. You can manually inspect or edit it for debugging!
2. Backups: Since it's just a file, you can easily back up your database by copying the .json file.
3. Path Resolution: Use absolute paths or path.join() for the database file if you are running scripts from different directories.

📝 License

ISC © [SHIBSUNDAR CHAKRABORTY]

⚖️ Legal Disclaimer

MongoDB is a trademark of MongoDB Inc. This project is an independent, lightweight database library and is not affiliated with, endorsed by, or sponsored by MongoDB Inc. The term "MongoDB-like" is used here for descriptive purposes only to indicate API compatibility and familiarity.