ChordDB

ChordDB is a lightweight, MongoDB-inspired database that uses Discord channels as storage, with end-to-end encryption and optional wrapper-based caching for performance.

It is designed primarily for bots, prototypes, and small-scale systems where simplicity and zero external infrastructure matter.

Features

📦 Discord messages as database records (1 message = 1 document)
🔐 AES-GCM encryption using Node.js crypto
🧠 Mongo-like query & update operators ($set, $inc, $unset, $push)
⚡ Cache-aware fetching (recommended with Discord API wrappers)
🧩 ESM-first with CJS support
🧪 Works with plain JSON data

Installation

npm

npm install chorddb

Importing

ESM (recommended)

import { Chord } from "chorddb";

CommonJS

const { Chord } = require("chorddb");

Initialization

Create a Chord instance

import { Chord, getKey } from "chorddb";

const chord = new Chord({
	token: "YOUR_BOT_TOKEN",
	key: getKey("YOUR_ENCRYPTION_KEY_OR_PASSWORD"),
	collections: [
		{ name: "users", channelId: "1469947881367797825" },
		{ name: "shop", channelId: "1469947881367797826" },
	],
});

Note

You can optionally provide a Discord API wrapper (discord.js, oceanic, bakit, etc.) to enable cache-based reads and reduce REST usage.

Use with Discord API wrappers

import { Chord } from "chorddb";
import { Client, GatewayIntentBits } from "discord.js";

const client = new Client({
	intents: [
		GatewayIntentBits.Guilds,
		GatewayIntentBits.GuildMessages,
		GatewayIntentBits.MessageContent,
	],
});

const chord = new Chord({
	token: "YOUR_BOT_TOKEN",
	key: getKey("YOUR_ENCRYPTION_KEY_OR_PASSWORD"),
	collections: [...]
});

// Listen for gateway payloads to make sure the cache is up-to-date
client.on("raw", (payload) => chord.updateGatewayPayload(payload));

// Enable wrapper mode for caching
// You can either use await it or just let it run
await chord.useWrapper();

await client.login("YOUR_BOT_TOKEN");

Create / Access a Collection

const users = chord.collect("users");
const guilds = chord.collect("guilds");

Basic Usage

Insert a document

await users.insertOne({
	username: "someone",
	coins: 100,
});

let moreUsers = await users.insertMany([
	{ username: "someone else", coins: 200 },
	{ username: "another user", coins: 300 },
]);

Find documents

await users.find({
	username: "someone",
});

await users.findById("123"); // ID is the message ID

or using a predicate:

const richUsers = await users.find((doc) => doc.coins > 500);

Update documents

await users.updateOne(
	{ username: "someone" },
	{
		$inc: { coins: 50 },
		$set: { premium: true },
	},
);

await users.updateMany((doc) => doc["coins"] < 300, {
	$dec: { coins: 20 },
});

Delete Documents

await users.deleteOne({ username: "someone else" });

await users.deleteMany((doc) => doc["coins"] < 150);

Fetch all documents

const allUsers = await users.findAll();

Query & Update Operators

Supported filters

Object matching
Predicate functions

Supported update operators

$set
$inc
$dec
$unset
$push

(Operator behavior is intentionally Mongo-like but simplified.)

Performance Notes

Cache is optional but strongly recommended
Without a wrapper cache, ChordDB falls back to paginated REST fetching
Fetching is lazy and incremental to avoid rate limits

Intended Use Cases

✅ Prototype bots
✅ Startup MVPs
✅ Small persistent data needs
⚠️ Not intended for high-write or large-scale production databases

Roadmap

Image / binary uploads
Indexing helpers
Better schema validation
Query optimization

Contributing

Contributions are welcome! Please open an issue or pull request if you have any suggestions or find any bugs.

Thanks to everyone who helps make ChordDB better!

GeezerVison

Latest commit

History

Folders and files

Repository files navigation