darkdb

# DarkDB V3.3.0 A **lightweight, versatile, and high-performance database** for Node.js. Supports multiple data formats, advanced query engine, transactions, TTL, and event system. Designed for **simplicity, performance, and scalability**. --- ## ✨ Features - Store data in **JSON, YAML, TOML OR BINARY** files. - **Advanced search** with full indexing. - **Query engine** with operators: - `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte` - `$in`, `$nin`, `$regex` - `$and`, `$or`, `$not` - **Transaction support** for atomic multi-step operations. - Nested path access with `.` separator (e.g., `user.profile.age`). - Core operations: `set`, `get`, `delete`, `has`. - Array operations: `push`, `unpush`. - Number operations: `add`, `remove`, `incr`, `decr`. - Bulk operations: `all`, `deleteAll`. - TTL (time-to-live) with automatic expiry. - Backup & restore support. - Event system (listen to `set`, `delete`, `reset`, `change`). - Journaling & crash-safe saves. - Debounced writes for performance. - Sharding support for very large datasets. --- ## 📦 Installation ```bash npm install darkdb ``` # DarkDB Benchmark Results | Test | Atomic | Iterations | Elapsed (ms) | Ops/sec | |-------------------|--------|------------|--------------|-------------| | SET ops | true | 10000 | 41.63 | 240,238.51 | | SET ops | false | 10000 | 18.57 | 538,578.37 | | GET ops | true | 10000 | 18.54 | 539,249.26 | | GET ops | false | 10000 | 12.43 | 804,439.92 | | DELETE ops | true | 10000 | 14.68 | 681,426.36 | | DELETE ops | false | 10000 | 14.89 | 671,456.39 | | INCR ops | true | 10000 | 17.76 | 562,936.28 | | INCR ops | false | 10000 | 9.28 | 1,078,132.24| | TRANSACTION ops | true | 1000 | 11.57 | 86,405.03 | | TRANSACTION ops | false | 1000 | 6.94 | 144,048.63 | --- ## 🚀 Usage ### Basic Operations ```js const DarkDB = require("darkdb"); const db = new DarkDB({ name: "darkdb", separator: ".", autoFile: true, jsonSpaces: 4 }); // Basic set & get await db.set("user.name", "Alice"); console.log(await db.get("user.name")); // "Alice" // Delete value await db.delete("user.name"); // Check existence console.log(await db.has("user")); // true ``` ### Advanced Features ```js // Store data in YAML format const yamlDb = new DarkDB({ name: "yaml_db", format: "yaml" }); // Use search with indexing await db.set("documents.1", { title: "A Guide to Node.js", description: "Learn how to build powerful Node.js applications.", }); await db.set("documents.2", { title: "Introduction to JavaScript", description: "A beginner's guide to JavaScript programming.", }); const results = await db.search("Node.js"); console.log(results); // TTL (expires after 5 seconds) await db.set("session.token", "abc123", { ttlMs: 5000 }); // Event system db.on("set", ({ key, value }) => { console.log(`[EVENT] Key set: ${key} = ${value}`); }); ``` ```js // Store data in TOML format const tomlDb = new DarkDB({ name: "toml_db", format: "toml" }); // Use search with indexing await tomlDb.set("documents.1", { title: "A Guide to Node.js", description: "Learn how to build powerful Node.js applications.", }); await tomlDb.set("documents.2", { title: "Introduction to JavaScript", description: "A beginner's guide to JavaScript programming.", }); const tomlResults = await tomlDb.search("JavaScript"); console.log("[TOML Search Results]", tomlResults); // TTL (expires after 3 seconds) await tomlDb.set("session.token", "xyz987", { ttlMs: 3000 }); // Event system tomlDb.on("set", ({ key, value }) => { console.log(`[TOML EVENT] Key set: ${key} = ${value}`); }); ``` ```js // Store data in Binary format const binaryDb = new DarkDB({ name: "binary_db", format: "binary" }); // Use search with indexing await binaryDb.set("documents.1", { title: "Binary Storage Example", description: "Data is stored in a compact binary format.", }); await binaryDb.set("documents.2", { title: "Another Document", description: "Binary files are efficient for large datasets.", }); const binaryResults = await binaryDb.search("Binary"); console.log("[Binary Search Results]", binaryResults); // TTL (expires after 10 seconds) await binaryDb.set("session.token", "bin123", { ttlMs: 10000 }); // Event system binaryDb.on("set", ({ key, value }) => { console.log(`[BINARY EVENT] Key set: ${key} = ${value}`); }); ``` ### Transactions ```js await db.transaction(async (tx) => { await tx.set("balance", 100); await tx.decr("balance"); }); ``` ### Query Engine ```js await db.set("users.1", { name: "Alice", age: 25 }); await db.set("users.2", { name: "Bob", age: 30 }); const adults = await db.query("users", { age: { $gte: 18 } }); console.log(adults); /* [ [ '1', { name: 'Alice', age: 25 } ], [ '2', { name: 'Bob', age: 30 } ] ] */ ``` --- ## 🛠 Options | Option | Default | Description | |--------------|-----------|-------------| | `name` | `darkdb` | Database file name | | `dir` | `.` | Directory to store files | | `format` | `json` | File format: **`json` `yaml` `toml` or `binary` ** | | `separator` | `.` | Separator for nested keys | | `autoFile` | `true` | Save automatically to file | | `jsonSpaces` | `4` | Pretty JSON formatting | | `debounceMs` | `25` | Debounce time for file saves in ms | | `atomic` | `true` | Use atomic file writes for crash safety | | `shard` | `false` | Enable sharding for large datasets | --- ## 🔑 API - `set(path, value, options?)` - `get(path, defaultValue?)` - `delete(path)` - `has(path)` - `all()` - `deleteAll()` - `push(path, value)` - `unpush(path, value)` - `add(path, number)` - `remove(path, number)` - `incr(path)` - `decr(path)` - `keys(path?)` - `values(path?)` - `entries(path?)` - `find(path, predicate)` - `search(query)` - `query(keyPrefix, filter)` - `expire(path, ttlMs)` - `ttl(path)` - `backup(filePath)` - `restore(filePath)` - `export()` - `import(obj)` - `transaction(fn)` - `on(event, callback)` - `off(event, listener)` --- ## 📌 Events - `set` - `delete` - `reset` - `change`