Database — v1.0.0

The Database class (exported from syntx.js as SyntxDB) is syntx.js's built-in store for bot data: balances, settings, warnings, anything you'd normally reach for a small database for. It lives in its own package, @erxprojects/syntx-db, but syntx.js already lists it as a dependency, so it installs automatically the moment you run npm install syntx.js; there's nothing extra to add to your project.

const { SyntxDB, Scope } = require("syntx.js");

// equivalent, straight from the package syntx.js depends on:
const { Database, Scope } = require("@erxprojects/syntx-db");

Data is stored as plain JSON files on disk, one folder per variable, so there's no external service to run or connect to.

Creating a database

const { SyntxDB } = require("syntx.js");

const db = new SyntxDB({
  path: "./data",
});

Options

Connecting it to your client

Pass the instance as database when creating your ERXClient. It then becomes reachable everywhere as client.database, or its shorter alias, client.db.

const { ERXClient, SyntxDB, Intents } = require("syntx.js");

const db = new SyntxDB({ path: "./data" });

const client = new ERXClient({
  token: process.env.TOKEN,
  intents: Intents.Fast,
  database: db,
});

Scopes

A variable's scope decides who "owns" each value: a value can belong to a member inside one specific server, to a whole server, or to a user across every server the bot is in.

Defining a variable

Before reading or writing anything, create the variable once with a scope and an optional default value. Calling create() is what get(), set(), and the rest of the handle methods check against.

db.create(name, options)

await db.create("balance", { scope: "user", default: 0 });
await db.create("prefix", { scope: "guild", default: "!" });
await db.create("level", { scope: "global", default: 1 });

Getting a scope handle

db.user(), db.guild(), and db.global() don't touch the disk themselves; they just return a small handle bound to the right scope and ids. The actual reads and writes happen when you call a method on that handle.

db.user(userId, guildId)

A handle scoped to one member inside one specific server.

const handle = db.user(message.author.id, message.guild.id);

db.guild(guildId)

A handle scoped to one server, shared by every member in it.

const handle = db.guild(message.guild.id);

db.global(userId)

A handle scoped to one user, shared across every server the bot is in.

const handle = db.global(message.author.id);

Handle methods

Every method below is async and resolves once the change is saved to disk (and to the in-memory cache, if enabled). They all throw a ScopeError if the variable was created with a different scope than the handle you're calling them on.

handle.get(name)

Returns the stored value, or the variable's default if nothing has been set yet.

const balance = await db.user(userId, guildId).get("balance");

handle.set(name, value)

Overwrites the stored value. value must be a number, string, boolean, plain object, array, or null; anything else (functions, undefined, circular references) throws a ValidationError.

await db.user(userId, guildId).set("balance", 250);

handle.has(name)

Returns true only if a value has actually been stored for this key, as opposed to still sitting at its default.

const hasClaimedDaily = await db.user(userId, guildId).has("lastDaily");

handle.reset(name)

Deletes the stored value and returns the default value it was reset to.

await db.user(userId, guildId).reset("warnings");

handle.delete(name)

Removes the stored record entirely and returns true. Functionally similar to reset(); the difference is reset() gives back the new (default) value, while delete() gives back a boolean.

await db.user(userId, guildId).delete("warnings");

handle.add(name, amount)

Atomically adds amount to a numeric variable and returns the new total. Use a negative number to subtract.

const newBalance = await db.user(userId, guildId).add("balance", -50);

handle.push(name, item)

Atomically appends item to an array variable and returns the updated array.

await db.guild(guildId).push("mutedRoles", roleId);

handle.pull(name, item)

Atomically removes every occurrence of item from an array variable and returns the updated array. Plain objects are matched by deep equality; everything else is matched with ===.

await db.guild(guildId).pull("mutedRoles", roleId);

handle.setExpiring(name, value, ttlMs)

Stores value like set(), but it automatically reverts to the variable's default once ttlMs milliseconds have passed; no need to clear it yourself.

const ms = require("ms");
await db.user(userId, guildId).setExpiring("cooldown", true, ms("10s"));

Database-wide methods

These read across the whole variable at once, instead of through a single scope handle.

db.exists(name)

Returns whether a variable with this name has been created at all.

if (!(await db.exists("balance"))) {
  await db.create("balance", { scope: "user", default: 0 });
}

db.info(name)

Returns the variable's metadata: its name, scope, default, and createdAt timestamp.

const info = await db.info("balance");
// { name: "balance", scope: "user", default: 0, createdAt: 1716000000000 }

db.getAll(name)

Returns every stored value for a variable, across every user or guild it's been set for; ideal for building a leaderboard.

const balances = await db.getAll("balance");
// { "u_123-g_456": 250, "u_789-g_456": 80 }

db.list()

Returns the names of every variable that has been created so far.

const variables = await db.list();
// ["balance", "prefix", "level"]

db.remove(name)

Permanently deletes a variable's definition and every value ever stored under it. There's no undo; back up first if you're not sure.

await db.remove("oldFeatureFlag");

db.stats()

Returns how many variables exist and how much disk space the whole database is using.

const { variables, size } = await db.stats();
// { variables: 3, size: "12.4 KB" }

db.clearCache()

Clears the in-memory cache, forcing the next read of every variable to come straight from disk.

db.clearCache();

Errors

Every problem SyntxDB raises extends SyntxDBError, so a single catch can handle all of them, or you can branch on the specific subclass.

const { ScopeError, ValidationError } = require("@erxprojects/syntx-db");

try {
  await db.guild(guildId).add("balance", 10);
} catch (error) {
  if (error instanceof ScopeError) {
    // "balance" was created with a different scope than "guild"
  } else if (error instanceof ValidationError) {
    // "balance" isn't a number, or the amount wasn't valid
  }
}

Full example

A simple per-server, per-member balance system:

const { ERXClient, SyntxDB, Intents } = require("syntx.js");

const db = new SyntxDB({ path: "./data" });

const client = new ERXClient({
  token: process.env.TOKEN,
  intents: Intents.Fast,
  prefix: "!",
  database: db,
});

client.ready(async () => {
  await db.create("balance", { scope: "user", default: 0 });
  console.log(`Logged in as ${client.bot.user.tag}`);
});

client.command({
  name: "balance",
  content: async (message) => {
    const balance = await db.user(message.author.id, message.guild.id).get("balance");
    message.reply(`Your balance is ${balance} coins.`);
  },
});

client.command({
  name: "daily",
  content: async (message) => {
    const newBalance = await db.user(message.author.id, message.guild.id).add("balance", 100);
    message.reply(`Daily claimed. New balance: ${newBalance} coins.`);
  },
});

client.registerCommands();
client.start();

See also

• Client for the database option and the client.db / client.database shortcuts.
• Bringing your own database instead of SyntxDB? Pass any object exposing your own methods as database and reach it through client.db the same way.