{"id":31441296,"url":"https://github.com/marcuwynu23/mingledb","last_synced_at":"2025-09-30T16:41:08.799Z","repository":{"id":316399230,"uuid":"1033539058","full_name":"marcuwynu23/mingledb","owner":"marcuwynu23","description":"Lightweight file based NoSQL DB","archived":false,"fork":false,"pushed_at":"2025-09-24T10:54:56.000Z","size":116,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-24T12:08:27.945Z","etag":null,"topics":["bson","compressed","database","embedded","flatfile","local","tinydb"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcuwynu23.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-07T01:26:01.000Z","updated_at":"2025-09-24T10:54:51.000Z","dependencies_parsed_at":"2025-09-25T23:18:02.365Z","dependency_job_id":null,"html_url":"https://github.com/marcuwynu23/mingledb","commit_stats":null,"previous_names":["marcuwynu23/mingledb"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/marcuwynu23/mingledb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcuwynu23%2Fmingledb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcuwynu23%2Fmingledb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcuwynu23%2Fmingledb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcuwynu23%2Fmingledb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcuwynu23","download_url":"https://codeload.github.com/marcuwynu23/mingledb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcuwynu23%2Fmingledb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277722881,"owners_count":25865940,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-30T02:00:09.208Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bson","compressed","database","embedded","flatfile","local","tinydb"],"created_at":"2025-09-30T16:41:05.174Z","updated_at":"2025-09-30T16:41:08.785Z","avatar_url":"https://github.com/marcuwynu23.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003e MingleDB \u003c/h1\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/stars/marcuwynu23/mingledb.svg\" alt=\"Stars Badge\"/\u003e\n  \u003cimg src=\"https://img.shields.io/github/forks/marcuwynu23/mingledb.svg\" alt=\"Forks Badge\"/\u003e\n  \u003cimg src=\"https://img.shields.io/github/issues/marcuwynu23/mingledb.svg\" alt=\"Issues Badge\"/\u003e\n  \u003cimg src=\"https://img.shields.io/github/license/marcuwynu23/mingledb.svg\" alt=\"License Badge\"/\u003e\n\u003c/p\u003e\n\n**MingleDB** is a lightweight, file-based NoSQL database built on top of the [BSON](https://bsonspec.org/) serialization format with support for:\n\n- 🔐 Basic authentication\n- ✅ Schema validation\n- 🔎 Query filters (including regex, range, `$in`, etc.)\n- 📦 BSON + Zlib compression\n- 💾 Flat file-based persistence\n\nDesigned for fast prototyping, embedded use, CLI apps, or offline-first environments.\n\n---\n\n## 📦 Installation\n\n```bash\nnpm install mingledb\n```\n\n---\n\n## 🚀 Features\n\n| Feature                         | Description                                                          |\n| ------------------------------- | -------------------------------------------------------------------- |\n| 🔐 **User Authentication**      | Register, login, logout, and session tracking using SHA256 hashing   |\n| 🧾 **Schema Definition**        | Define required fields, types, and unique constraints per collection |\n| 🧠 **Smart Querying**           | Supports advanced query filters like `$gt`, `$in`, `$regex`, etc.    |\n| 💨 **Compression**              | Uses zlib + BSON to store entries compactly                          |\n| 📁 **Flatfile Storage**         | Saves data in `.mingleDB` files with a binary header and metadata    |\n| 🔄 **Update/Delete Operations** | Simple CRUD support with updateOne and deleteOne                     |\n| 📃 **Minimal Dependencies**     | Zero external DB needed, runs anywhere Node.js runs                  |\n\n---\n\n## 🧪 Example Usage\n\n```js\nimport MingleDB from \"mingledb\"; // For ES Modules\n// const MingleDB = require(\"mingledb\"); // For CommonJS\n\nconst db = new MingleDB(); // Optional: pass custom directory path\n\n// 🔐 1. Register \u0026 Login\ndb.registerUser(\"admin\", \"secure123\");\ndb.login(\"admin\", \"secure123\");\n\n// ✅ 2. Define schema\ndb.defineSchema(\"users\", {\n  name: { type: \"string\", required: true },\n  email: { type: \"string\", required: true, unique: true },\n  age: { type: \"number\" },\n});\n\n// 📥 3. Insert documents\ndb.insertOne(\"users\", {\n  name: \"Wayne\",\n  email: \"wayne@mingle.com\",\n  age: 25,\n});\n\n// 🔎 4. Read operations\nconsole.log(db.findAll(\"users\")); // All documents\nconsole.log(db.findOne(\"users\", { email: \"wayne@mingle.com\" })); // Exact match\nconsole.log(db.find(\"users\", { age: { $gte: 18, $lt: 30 } })); // Range filter\n\n// 📝 5. Update a document\ndb.updateOne(\"users\", { name: \"Wayne\" }, { age: 26 });\n\n// 🗑️ 6. Delete a document\ndb.deleteOne(\"users\", { email: \"wayne@mingle.com\" });\n\n// 🚪 7. Logout\ndb.logout(\"admin\");\n```\n\n---\n\n## 🧠 Query Operators Supported\n\n| Operator                     | Description                                                             |\n| ---------------------------- | ----------------------------------------------------------------------- |\n| `$gt`, `$gte`, `$lt`, `$lte` | Greater/Less Than (or Equal)                                            |\n| `$eq`, `$ne`                 | Equals / Not Equals                                                     |\n| `$in`, `$nin`                | Matches any in list / not in list                                       |\n| `$regex`                     | Regular Expression matching (case-insensitive supported via `$options`) |\n\n---\n\n## 🔐 Authentication API\n\n```ts\nregisterUser(username: string, password: string): void\nlogin(username: string, password: string): boolean\nisAuthenticated(username: string): boolean\nlogout(username: string): void\n```\n\n---\n\n## 📂 Schema Example\n\n```js\ndb.defineSchema(\"posts\", {\n  title: { type: \"string\", required: true },\n  slug: { type: \"string\", unique: true },\n  views: { type: \"number\" },\n});\n```\n\n\u003e `required` will throw error if missing  \n\u003e `unique` will scan the whole collection to ensure no duplicates\n\n---\n\n## 💡 Use Cases\n\n- Embedded/local-first database\n- Desktop apps (Electron)\n- CLI tools or utilities\n- Offline PWA storage simulation\n- Rapid prototyping with schema validation\n- Lightweight admin panel backend\n\n---\n\n## 🔧 Configuration\n\n```js\nconst db = new MingleDB(\"./data\"); // Change default directory\n```\n\nEach collection will be stored as a `.mingleDB` binary file with compressed records.\n\n---\n\n## 📁 File Format\n\nEach collection file contains:\n\n1. Header (`MINGLEDBv1`)\n2. JSON metadata (collection name, version)\n3. Repeated entries of:\n   - 4-byte length\n   - zlib-compressed BSON document\n\n---\n\n## ✅ Roadmap (Future Ideas)\n\n- [ ] Auto-indexing for faster unique validation\n- [ ] Nested field queries\n- [ ] Export/import data as JSON\n- [ ] File-level locking for concurrent writes\n- [ ] Optional encryption\n- [ ] WebSocket sync module\n\n---\n\n## 👨‍💻 Development\n\n```bash\nnpm install\nnpm run test\n```\n\n---\n\n## 📜 License\n\nMIT © 2025 Mark Wayne Menorca\n\n---\n\n## 💬 Feedback\n\nFeel free to open issues or submit pull requests to suggest improvements or report bugs!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcuwynu23%2Fmingledb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcuwynu23%2Fmingledb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcuwynu23%2Fmingledb/lists"}