https://github.com/marcuwynu23/mingledb
Lightweight file based NoSQL DB
https://github.com/marcuwynu23/mingledb
bson compressed database embedded flatfile local tinydb
Last synced: 8 months ago
JSON representation
Lightweight file based NoSQL DB
- Host: GitHub
- URL: https://github.com/marcuwynu23/mingledb
- Owner: marcuwynu23
- Created: 2025-08-07T01:26:01.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-09-24T10:54:56.000Z (8 months ago)
- Last Synced: 2025-09-24T12:08:27.945Z (8 months ago)
- Topics: bson, compressed, database, embedded, flatfile, local, tinydb
- Language: JavaScript
- Homepage:
- Size: 113 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
MingleDB
**MingleDB** is a lightweight, file-based NoSQL database built on top of the [BSON](https://bsonspec.org/) serialization format with support for:
- 🔐 Basic authentication
- ✅ Schema validation
- 🔎 Query filters (including regex, range, `$in`, etc.)
- 📦 BSON + Zlib compression
- 💾 Flat file-based persistence
Designed for fast prototyping, embedded use, CLI apps, or offline-first environments.
---
## 📦 Installation
```bash
npm install mingledb
```
---
## 🚀 Features
| Feature | Description |
| ------------------------------- | -------------------------------------------------------------------- |
| 🔐 **User Authentication** | Register, login, logout, and session tracking using SHA256 hashing |
| 🧾 **Schema Definition** | Define required fields, types, and unique constraints per collection |
| 🧠 **Smart Querying** | Supports advanced query filters like `$gt`, `$in`, `$regex`, etc. |
| 💨 **Compression** | Uses zlib + BSON to store entries compactly |
| 📁 **Flatfile Storage** | Saves data in `.mingleDB` files with a binary header and metadata |
| 🔄 **Update/Delete Operations** | Simple CRUD support with updateOne and deleteOne |
| 📃 **Minimal Dependencies** | Zero external DB needed, runs anywhere Node.js runs |
---
## 🧪 Example Usage
```js
import MingleDB from "mingledb"; // For ES Modules
// const MingleDB = require("mingledb"); // For CommonJS
const db = new MingleDB(); // Optional: pass custom directory path
// 🔐 1. Register & Login
db.registerUser("admin", "secure123");
db.login("admin", "secure123");
// ✅ 2. Define schema
db.defineSchema("users", {
name: { type: "string", required: true },
email: { type: "string", required: true, unique: true },
age: { type: "number" },
});
// 📥 3. Insert documents
db.insertOne("users", {
name: "Wayne",
email: "wayne@mingle.com",
age: 25,
});
// 🔎 4. Read operations
console.log(db.findAll("users")); // All documents
console.log(db.findOne("users", { email: "wayne@mingle.com" })); // Exact match
console.log(db.find("users", { age: { $gte: 18, $lt: 30 } })); // Range filter
// 📝 5. Update a document
db.updateOne("users", { name: "Wayne" }, { age: 26 });
// 🗑️ 6. Delete a document
db.deleteOne("users", { email: "wayne@mingle.com" });
// 🚪 7. Logout
db.logout("admin");
```
---
## 🧠 Query Operators Supported
| Operator | Description |
| ---------------------------- | ----------------------------------------------------------------------- |
| `$gt`, `$gte`, `$lt`, `$lte` | Greater/Less Than (or Equal) |
| `$eq`, `$ne` | Equals / Not Equals |
| `$in`, `$nin` | Matches any in list / not in list |
| `$regex` | Regular Expression matching (case-insensitive supported via `$options`) |
---
## 🔐 Authentication API
```ts
registerUser(username: string, password: string): void
login(username: string, password: string): boolean
isAuthenticated(username: string): boolean
logout(username: string): void
```
---
## 📂 Schema Example
```js
db.defineSchema("posts", {
title: { type: "string", required: true },
slug: { type: "string", unique: true },
views: { type: "number" },
});
```
> `required` will throw error if missing
> `unique` will scan the whole collection to ensure no duplicates
---
## 💡 Use Cases
- Embedded/local-first database
- Desktop apps (Electron)
- CLI tools or utilities
- Offline PWA storage simulation
- Rapid prototyping with schema validation
- Lightweight admin panel backend
---
## 🔧 Configuration
```js
const db = new MingleDB("./data"); // Change default directory
```
Each collection will be stored as a `.mingleDB` binary file with compressed records.
---
## 📁 File Format
Each collection file contains:
1. Header (`MINGLEDBv1`)
2. JSON metadata (collection name, version)
3. Repeated entries of:
- 4-byte length
- zlib-compressed BSON document
---
## ✅ Roadmap (Future Ideas)
- [ ] Auto-indexing for faster unique validation
- [ ] Nested field queries
- [ ] Export/import data as JSON
- [ ] File-level locking for concurrent writes
- [ ] Optional encryption
- [ ] WebSocket sync module
---
## 👨💻 Development
```bash
npm install
npm run test
```
---
## 📜 License
MIT © 2025 Mark Wayne Menorca
---
## 💬 Feedback
Feel free to open issues or submit pull requests to suggest improvements or report bugs!