@erxprojects/syntx-db

A simple, lightweight JSON-based database for Discord bots. Built for Syntx.js, but usable in any Node.js project.

Installation

npm i github:erxproject/syntx-db

Table of contents

• Setup
• Creating variables
• Scopes
• Reading and writing
• Array and number helpers
• Expiring values
• Database utilities

Setup

const { Database } = require("@erxprojects/syntx-db")

const db = new Database({
    path: "./database",
    cache: true,
    backup: true,
    pretty: false
})

| Option | Type | Default | Description | | ----------- | --------- | ------- | -------------------------------------------------- | | path | string | — | Folder where the data will be stored. Required. | | cache | boolean | true | Enables in-memory cache for faster reads. | | cacheMax | number | 0 | Max number of cached entries. 0 = unlimited. | | cacheTTL | number | 0 | Cache TTL in milliseconds. 0 = no expiry. | | backup | boolean | true | Creates .bak backups before overwriting files. | | pretty | boolean | false | Pretty-prints the JSON files. |

Creating variables

Before reading or writing, you must create a variable and define its scope and default value.

await db.create("coins", { scope: "user", default: 0 })
await db.create("welcome", { scope: "guild", default: true })
await db.create("maintenance", { scope: "global", default: false })

Scopes

Every variable has a scope that determines what key it's stored under.

| Scope | Access method | Keyed by | | -------- | --------------------------| --------------------- | | user | db.user(userId, guildId)| User + guild pair | | guild | db.guild(guildId) | Guild | | global | db.global(userId) | User (across guilds) |

// User scope — per user per server
const handle = db.user(message.author.id, message.guild.id)

// Guild scope — per server
const handle = db.guild(message.guild.id)

// Global scope — per user across all servers
const handle = db.global(message.author.id)

Reading and writing

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

// Get the current value (returns default if not set)
const coins = await handle.get("coins")

// Set a value
await handle.set("coins", 100)

// Check if a value has been set
const hasCoins = await handle.has("coins")

// Reset to the default value
await handle.reset("coins")

// Delete the entry entirely
await handle.delete("coins")

Array and number helpers

These methods are atomic — safe to use in concurrent environments.

const handle = db.user(userId, guildId)

// Add to a number
await handle.add("coins", 50)   // coins += 50
await handle.add("coins", -10)  // coins -= 10

// Append to an array
await handle.push("inventory", "sword")

// Remove all occurrences of a value from an array
await handle.pull("inventory", "sword")

add() requires the variable's default to be a number. push() and pull() require it to be an array.

Expiring values

Store a value that automatically resets to its default after a set time.

// Stores "boosted" as true for 1 hour, then reverts to default
await db.guild(guildId).setExpiring("boosted", true, 60 * 60 * 1000)

Database utilities

// Check if a variable exists
await db.exists("coins")             // true | false

// Get metadata about a variable
await db.info("coins")
// → { name, scope, default, createdAt }

// Get all stored entries for a variable (useful for leaderboards)
await db.getAll("coins")
// → { "u_123-g_456": 200, "u_789-g_456": 50, ... }

// List all registered variable names
await db.list()                      // ["coins", "welcome", ...]

// Remove a variable and all its data
await db.remove("coins")

// Get database stats
await db.stats()
// → { variables: 3, size: "12.4 KB" }

// Clear the in-memory cache
db.clearCache()