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!