@hydren/hdb

A super lightweight flat-file JSON database for Node.js.
Stores your data in a single .hdb file, split into logical tables.
Perfect for small projects, bots, or apps that don’t need a heavy SQL/NoSQL server.

📦 Installation

npm install @hydren/hdb

or with yarn:

yarn add @hydren/hdb

⚡ Quick Start

const HDB = require("@hydren/hdb");

const db = new HDB("mydb.hdb", {
  USERS: [],
  SERVERS: [],
  SETTINGS: []
});

// Insert data
db.put("USERS", { id: 1, name: "Alice" });
db.put("USERS", { id: 2, name: "Bob" });

// Get one user
console.log(db.get("USERS", { id: 2 })); 
// -> { id: 2, name: "Bob" }

// Update user
db.update("USERS", { id: 2 }, { name: "Bobby" });

// List all users
console.log(db.list("USERS"));

// Delete user
db.delete("USERS", { id: 1 });

// Count rows
console.log("User count:", db.count("USERS"));

🔑 API Reference

new HDB(file, tables = {})

Create a new database instance.

• file: path to .hdb file
• tables (optional): object with table names as keys (will be created if missing)

list(table)

Returns an array of all rows in a table.

put(table, obj)

Appends a new row (object) to the table. Auto-creates the table if it doesn’t exist.

replace(table, list)

Replaces the entire table with a new array of rows.

get(table, query)

Finds the first row matching query. Example:

db.get("USERS", { id: 1 });

find(table, query)

Finds all rows matching query.

db.find("USERS", { name: "Alice" });

update(table, query, changes)

Updates all rows that match the query.

db.update("USERS", { id: 2 }, { name: "Bobby" });

delete(table, query)

Removes all rows matching query.

db.delete("USERS", { id: 1 });

clear(table)

Wipes all rows from a table.

tablesList()

Returns an array of all table names.

count(table)

Returns the number of rows in a table.

📁 Example .hdb File

--TABLE-USERS--
{"id":1,"name":"Alice"}
{"id":2,"name":"Bobby"}
--TABLE-SERVERS--
{"id":"srv1","owner":1}
--TABLE-SETTINGS--
{"theme":"dark"}

✅ Use Cases

• Discord/Telegram bots
• Small web apps
• CLI tools
• Prototyping without a real DB

⚠️ Notes

• This is not designed for high concurrency or massive datasets.
• Data is stored as plain text; don’t use it for sensitive info.
• Each table is just newline-separated JSON objects.

📜 License

MIT © Hydren