DarkDB V3.4.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.
• Configurable Indexing (index any field).
• Schema Validation (enforce types).
• Hooks/Middleware (pre and post events).
• Advanced Querying (sort, limit, skip).

📦 Installation

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

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

// 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}`);
});

// Configurable Indexing
const dbIndexed = new DarkDB({
  name: "indexed_db",
  indexFields: ["name", "role", "email"]
});

// Schema Validation
const dbSchema = new DarkDB({
  name: "schema_db",
  schema: {
    name: String,
    age: Number,
    active: Boolean
  }
});

// Hooks
db.pre("set", async ({ key, value }) => {
  console.log(`Saving ${key}...`);
});
db.post("delete", async ({ key }) => {
  console.log(`${key} deleted.`);
});

// 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}`);
});

// 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

await db.transaction(async (tx) => {
  await tx.set("balance", 100);
  await tx.decr("balance");
});

Query Engine

await db.set("users.1", { name: "Alice", age: 25 });
await db.set("users.2", { name: "Bob", age: 30 });

// Basic Query
const adults = await db.query("users", { age: { $gte: 18 } });

// Advanced Query (Sort, Limit, Skip)
const sorted = await db.query("users", { age: { $gte: 18 } }, {
  sort: { age: -1 }, // Descending
  limit: 10,
  skip: 0
});

🛠 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 | | indexFields| ['title', 'description'] | Fields to index | | schema | null | Schema definition object |

🔑 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)
• pre(action, callback)
• post(action, callback)

📌 Events

• set
• delete
• reset
• change