@tryty/easydc-js 1.1.0 → 1.2.0

package/examples/mongo.js

@@ -0,0 +1,44 @@
+// Bot dengan database MongoDB.
+// Pasang dulu: npm install easydc-js discord.js mongodb
+// Jalankan:   TOKEN=token_bot MONGO_URI="mongodb+srv://..." node examples/mongo.js
+const { Bot } = require('easydc-js'); // saat dicoba dari folder ini: require('../src')
+const { mongodb } = require('easydc-js/mongodb'); // saat dicoba dari folder ini: require('../src/plugins/mongodb')
+
+const bot = new Bot({ token: process.env.TOKEN, prefix: '!', timezone: 'Asia/Jakarta' });
+
+bot.use(mongodb({
+  uri: process.env.MONGO_URI,
+  dbName: 'botku',
+  // cache: false,   // aktifkan baris ini jika bot dijalankan di lebih dari satu proses/server
+}));
+
+bot.variables({ uang: 100 });
+
+bot.command({ name: 'uang', code: '💰 $username punya $numberSeparator[$getUserVar[uang];.] koin' });
+
+bot.command({
+  name: 'kerja',
+  code: `
+$cooldown[1m;Istirahat dulu, tunggu %time%.]
+$incUserVar[uang;$random[10;50]]
+Kamu bekerja! Uangmu sekarang $getUserVar[uang]
+`,
+});
+
+bot.command({
+  name: 'kirim',
+  code: `
+$argsCheck[2;Format: !kirim @user jumlah]
+$onlyIf[$mentioned[1]!=;Mention user tujuan.]
+$onlyIf[$isNumber[$message[2]]==true&&$message[2]>0;Jumlah harus angka lebih dari 0.]
+$onlyIf[$getUserVar[uang]>=$message[2];Uangmu tidak cukup.]
+$incUserVar[uang;-$message[2]]
+$incUserVar[uang;$message[2];$mentioned[1]]
+✅ Terkirim $message[2] koin ke <@$mentioned[1]>
+`,
+});
+
+bot.connect().then(() => console.log('Bot online, database terhubung.')).catch((e) => {
+  console.error(e.message);
+  process.exit(1);
+});

package/index.d.ts

@@ -15,7 +15,7 @@ export interface BotOptions {
   handleSignals?: boolean;
   /** Nyalakan $eval / $jsEval / bot.evalCommand (hanya untuk ID di `owners`). Bawaan: false */
   eval?: boolean;
-  database?: { path?: string; memory?: boolean; saveDelay?: number } | Database;
+  database?: { path?: string; memory?: boolean; saveDelay?: number } | DatabaseAdapter;
   messages?: { cooldown?: string; error?: string };
   status?: { text: string; type?: 'Playing' | 'Streaming' | 'Listening' | 'Watching' | 'Competing'; status?: 'online' | 'idle' | 'dnd' | 'invisible' };
   onError?: (error: Error, ctx: Context) => unknown;
@@ -70,7 +70,19 @@ export class Context {
   rawArgs: string;
 }
 
-export class Database {
+/** Adapter database: hanya get/set/delete yang wajib. Nilai balik boleh Promise. */
+export interface DatabaseAdapter {
+  get(key: string): unknown | Promise<unknown>;
+  set(key: string, value: unknown): unknown | Promise<unknown>;
+  delete(key: string): unknown | Promise<unknown>;
+  has?(key: string): boolean | Promise<boolean>;
+  keys?(prefix?: string): string[] | Promise<string[]>;
+  flush?(): unknown | Promise<unknown>;
+  connect?(): Promise<void>;
+  close?(): unknown | Promise<unknown>;
+}
+
+export class Database implements DatabaseAdapter {
   constructor(options?: { path?: string; memory?: boolean; saveDelay?: number });
   get(key: string): unknown;
   set(key: string, value: unknown): void;
@@ -78,12 +90,18 @@ export class Database {
   delete(key: string): boolean;
   keys(prefix?: string): string[];
   flush(): void;
+  close(): void;
 }
 
+export function copyDatabase(from: DatabaseAdapter, to: DatabaseAdapter, options?: { overwrite?: boolean; prefix?: string }): Promise<{ copied: number; skipped: number }>;
+
+export type Plugin = ((bot: Bot, options?: unknown) => void) | { name?: string; install(bot: Bot, options?: unknown): void };
+
 export class Bot {
   constructor(options?: BotOptions);
   client: Client | null;
-  db: Database;
+  db: DatabaseAdapter;
+  plugins: Map<string, unknown>;
   command(def: CommandDef): this;
   slashCommand(def: SlashDef): this;
   button(def: ComponentDef): this;
@@ -117,9 +135,12 @@ export class Bot {
   addFunction(fn: CustomFunction): this;
   loadCommands(dir: string): this;
   validate(): true;
-  getVar(scope: 'user' | 'server' | 'channel' | 'global', name: string, id?: string | null): string;
-  setVar(scope: 'user' | 'server' | 'channel' | 'global', name: string, value: unknown, id?: string | null): void;
-  resetVar(scope: 'user' | 'server' | 'channel' | 'global', name: string, id?: string | null): void;
+  use(plugin: Plugin, options?: unknown): this;
+  setDatabase(adapter: DatabaseAdapter): this;
+  getVar(scope: 'user' | 'server' | 'channel' | 'global', name: string, id?: string | null): Promise<string>;
+  setVar(scope: 'user' | 'server' | 'channel' | 'global', name: string, value: unknown, id?: string | null): Promise<void>;
+  resetVar(scope: 'user' | 'server' | 'channel' | 'global', name: string, id?: string | null): Promise<void>;
+  incVar(scope: 'user' | 'server' | 'channel' | 'global', name: string, amount: number | string, id?: string | null): Promise<string>;
   connect(token?: string): Promise<this>;
   destroy(): Promise<void>;
 }

package/mongodb.d.ts

@@ -0,0 +1,31 @@
+import type { Database } from './index';
+
+export interface MongoOptions {
+  /** Alamat MongoDB, mis. process.env.MONGO_URI. Wajib kecuali `client` diisi. */
+  uri?: string;
+  dbName?: string;
+  /** Bawaan: "easydc" */
+  collection?: string;
+  /** Bawaan true. Matikan bila lebih dari satu proses bot memakai database yang sama. */
+  cache?: boolean;
+  cacheLimit?: number;
+  /** MongoClient milik sendiri (tidak ditutup otomatis). */
+  client?: unknown;
+  driver?: unknown;
+  clientOptions?: Record<string, unknown>;
+}
+
+export class MongoDatabase {
+  constructor(options: MongoOptions);
+  connect(): Promise<void>;
+  get(key: string): Promise<string | undefined>;
+  has(key: string): Promise<boolean>;
+  set(key: string, value: unknown): Promise<void>;
+  delete(key: string): Promise<boolean>;
+  keys(prefix?: string): Promise<string[]>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+
+/** Plugin: bot.use(mongodb({ uri, dbName })) */
+export function mongodb(options: MongoOptions): { name: string; install(bot: unknown): void };

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@tryty/easydc-js",
-  "version": "1.1.0",
-  "description": "Bot Discord super mudah di atas discord.js: tulis perintah dengan sintaks $fungsi[arg] ala aoi.js.",
+  "version": "1.2.0",
+  "description": "Super easy Discord bot on top of discord.js: write commands with $function[arg] syntax.",
   "main": "src/index.js",
   "types": "index.d.ts",
   "files": [
     "src",
     "examples",
     "index.d.ts",
+    "mongodb.d.ts",
     "README.md",
     "LICENSE"
   ],
@@ -16,11 +17,12 @@
     "docs": "node scripts/gen-docs.js"
   },
   "keywords": [
+    "bot",
     "discord",
     "discord.js",
-    "bot",
-    "aoi.js",
     "easy",
+    "mongodb",
+    "plugin",
     "wrapper"
   ],
   "author": "",
@@ -30,5 +32,24 @@
   },
   "dependencies": {
     "discord.js": "^14.16.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./mongodb": {
+      "types": "./mongodb.d.ts",
+      "default": "./src/plugins/mongodb.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "mongodb": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "mongodb": {
+      "optional": true
+    }
   }
 }

package/src/bot.js

@@ -7,6 +7,7 @@ const { Interpreter } = require('./interpreter');
 const { Context } = require('./context');
 const { Database } = require('./database');
 const { createRegistry } = require('./functions');
+const { formatNumber } = require('./util');
 const { f } = require('./functions/helpers');
 
 const DEFAULT_INTENTS = [
@@ -38,6 +39,16 @@ const EVENT_TYPES = [
 ];
 const VAR_SCOPES = ['user', 'server', 'channel', 'global'];
 
+const ADAPTER_METHODS = ['get', 'set', 'delete'];
+const looksLikeAdapter = (d) => !!d && typeof d === 'object' && ADAPTER_METHODS.some((m) => typeof d[m] === 'function');
+
+/** Pastikan adapter database punya method wajib: get(key), set(key, value), delete(key). */
+function checkAdapter(adapter) {
+  const missing = ADAPTER_METHODS.filter((m) => typeof adapter?.[m] !== 'function');
+  if (missing.length) throw new BotError(`Adapter database tidak lengkap, method yang kurang: ${missing.join(', ')}`);
+  return adapter;
+}
+
 const wildcardToRegExp = (pattern) => new RegExp(
   `^${pattern.split('*').map((s) => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*')}$`,
 );
@@ -80,7 +91,9 @@ class Bot {
     this.client = null;
     this.registry = createRegistry();
     this.interpreter = new Interpreter();
-    this.db = opts.database instanceof Database ? opts.database : new Database(opts.database);
+    this.db = looksLikeAdapter(opts.database) ? checkAdapter(opts.database) : new Database(opts.database);
+    this.plugins = new Map();
+    this._locks = new Map();
     this.cooldowns = new Map();
 
     this.commands = new Map(); // nama/alias -> handler
@@ -280,6 +293,33 @@ class Bot {
   /** Jalan untuk setiap pesan yang BUKAN command. */
   onMessage(arg) { return this._eventShortcut('message', arg); }
 
+  /**
+   * Pasang plugin. Plugin = function(bot, opsi) atau object { name, install(bot, opsi) }.
+   * install harus sinkron (koneksi jaringan dilakukan adapter lewat connect()).
+   *   bot.use(mongodb({ uri: process.env.MONGO_URI, dbName: 'botku' }))
+   */
+  use(plugin, pluginOptions) {
+    const p = typeof plugin === 'function' ? { name: plugin.name || 'anonim', install: plugin } : plugin;
+    if (!p || typeof p.install !== 'function') {
+      throw new BotError('use: plugin harus berupa function atau object { name, install(bot) }');
+    }
+    const name = String(p.name ?? 'anonim');
+    if (name !== 'anonim' && this.plugins.has(name)) throw new BotError(`Plugin "${name}" sudah terpasang`);
+    const result = p.install(this, pluginOptions);
+    if (result && typeof result.then === 'function') {
+      throw new BotError(`Plugin "${name}": install() tidak boleh async. Lakukan koneksi di method connect() milik adapter`);
+    }
+    this.plugins.set(name, p);
+    return this;
+  }
+
+  /** Ganti database. Adapter wajib punya get/set/delete; opsional: has, keys, flush, connect, close. */
+  setDatabase(adapter) {
+    if (this._started) throw new BotError('setDatabase harus dipanggil sebelum connect()');
+    this.db = checkAdapter(adapter);
+    return this;
+  }
+
   /** Deklarasi variabel + nilai awal: bot.variables({ uang: 0, bio: '-' }) */
   variables(vars) {
     if (!vars || typeof vars !== 'object') throw new BotError('variables: berikan object { nama: nilaiAwal }');
@@ -395,18 +435,49 @@ class Bot {
     return scope === 'global' ? `global:${name}` : `${scope}:${id}:${name}`;
   }
 
-  getVar(scope, name, id) {
+  // Semua akses variabel bersifat asinkron karena adapter database (mis. MongoDB) berjalan lewat jaringan.
+  async getVar(scope, name, id) {
     const key = this._varKey(scope, name, id);
-    const stored = this.db.get(key);
-    return stored === undefined ? this.declaredVars.get(name) : stored;
+    const stored = await this.db.get(key);
+    return stored === undefined || stored === null ? this.declaredVars.get(name) : stored;
   }
 
-  setVar(scope, name, value, id) {
-    this.db.set(this._varKey(scope, name, id), String(value));
+  async setVar(scope, name, value, id) {
+    await this.db.set(this._varKey(scope, name, id), String(value));
   }
 
-  resetVar(scope, name, id) {
-    this.db.delete(this._varKey(scope, name, id));
+  async resetVar(scope, name, id) {
+    await this.db.delete(this._varKey(scope, name, id));
+  }
+
+  /**
+   * Tambah (atau kurangi, bila negatif) variabel angka. Dijalankan berurutan per variabel di dalam satu proses,
+   * sehingga dua command bersamaan tidak saling menimpa. Mengembalikan nilai baru.
+   */
+  async incVar(scope, name, amount, id) {
+    const key = this._varKey(scope, name, id);
+    const add = Number(String(amount).trim());
+    if (String(amount).trim() === '' || !Number.isFinite(add)) throw new BotError(`Jumlah "${amount}" bukan angka`);
+    const prev = this._locks.get(key) ?? Promise.resolve();
+    let release;
+    const gate = new Promise((resolve) => { release = resolve; });
+    const chain = prev.then(() => gate);
+    this._locks.set(key, chain);
+    await prev;
+    try {
+      const stored = await this.db.get(key);
+      const current = stored === undefined || stored === null ? this.declaredVars.get(name) : stored;
+      const base = Number(String(current).trim());
+      if (String(current).trim() === '' || !Number.isFinite(base)) {
+        throw new BotError(`Variabel "${name}" bernilai "${current}", bukan angka`);
+      }
+      const next = formatNumber(base + add);
+      await this.db.set(key, next);
+      return next;
+    } finally {
+      release();
+      if (this._locks.get(key) === chain) this._locks.delete(key);
+    }
   }
 
   // ===== Menjalankan =========================================================
@@ -748,6 +819,7 @@ class Bot {
       throw new BotError('Token bot belum diisi. Contoh: new Bot({ token: process.env.TOKEN })');
     }
     this.validate();
+    this._started = true;
     const discord = this._discord();
     const client = this.options.client ?? new discord.Client({
       intents: this._resolveIntents(discord),
@@ -757,19 +829,39 @@ class Bot {
     this._bind(client, discord);
     if (this.options.handleSignals && !this._signalsBound) {
       this._signalsBound = true;
-      const shutdown = () => { try { this.db.flush(); } catch { /* abaikan */ } process.exit(0); };
+      const shutdown = async () => {
+        const timeout = new Promise((resolve) => { setTimeout(resolve, 5000); });
+        try { await Promise.race([this.destroy(), timeout]); } catch { /* abaikan */ }
+        process.exit(0);
+      };
       process.once('SIGINT', shutdown);
       process.once('SIGTERM', shutdown);
-      process.once('exit', () => { try { this.db.flush(); } catch { /* abaikan */ } });
+      process.once('exit', () => {
+        try {
+          const r = this.db.flush?.();
+          if (r && typeof r.catch === 'function') r.catch(() => {});
+        } catch { /* abaikan */ }
+      });
+    }
+    try {
+      await this.db.connect?.();
+    } catch (e) {
+      throw new BotError(`Gagal terhubung ke database: ${e.message}`, { cause: e });
+    }
+    try {
+      await client.login(token);
+    } catch (e) {
+      try { await this.db.close?.(); } catch { /* abaikan */ }
+      throw e;
     }
-    await client.login(token);
     return this;
   }
 
-  /** Matikan bot dan simpan database. */
+  /** Matikan bot, simpan database, dan tutup koneksinya. */
   async destroy() {
-    this.db.flush();
+    await this.db.flush?.();
     if (this.client && typeof this.client.destroy === 'function') await this.client.destroy();
+    await this.db.close?.();
   }
 }
 

package/src/database.js

@@ -60,6 +60,9 @@ class Database {
     if (this._timer.unref) this._timer.unref();
   }
 
+  /** Dipanggil saat bot dimatikan: simpan data. */
+  close() { this.flush(); }
+
   /** Tulis ke disk sekarang juga (sinkron). */
   flush() {
     if (!this.file) return;
@@ -70,4 +73,24 @@ class Database {
   }
 }
 
-module.exports = { Database };
+/**
+ * Salin semua data dari satu database ke database lain (mis. file JSON -> MongoDB).
+ * Data yang sudah ada di tujuan tidak ditimpa, kecuali overwrite: true.
+ * Kedua adapter harus sudah connect() bila perlu, dan `from` wajib punya method keys().
+ * Mengembalikan { copied, skipped }.
+ */
+async function copyDatabase(from, to, { overwrite = false, prefix = '' } = {}) {
+  if (typeof from?.keys !== 'function') throw new Error('copyDatabase: database asal harus punya method keys()');
+  let copied = 0;
+  let skipped = 0;
+  for (const key of await from.keys(prefix)) {
+    if (!overwrite && (await to.get(key)) !== undefined) { skipped++; continue; }
+    const value = await from.get(key);
+    if (value === undefined) continue;
+    await to.set(key, value);
+    copied++;
+  }
+  return { copied, skipped };
+}
+
+module.exports = { Database, copyDatabase };

package/src/functions/vars.js

@@ -17,21 +17,25 @@ for (const [Scope, scope, defaultId, label] of SCOPES) {
   };
   out.push(
     f(`set${Scope}Var`, { b: 'required', min: 2, max: 3, s: `[nama;nilai;${label}ID?]`, d: `Simpan variabel ${label} (harus dideklarasikan dengan bot.variables)` },
-      (ctx, [name, value, id]) => { ctx.bot.setVar(scope, name, value, idFor(ctx, id)); return ''; }),
+      async (ctx, [name, value, id]) => { await ctx.bot.setVar(scope, name, value, idFor(ctx, id)); return ''; }),
     f(`get${Scope}Var`, { b: 'required', min: 1, max: 2, s: `[nama;${label}ID?]`, d: `Baca variabel ${label}` },
       (ctx, [name, id]) => ctx.bot.getVar(scope, name, idFor(ctx, id))),
     f(`reset${Scope}Var`, { b: 'required', min: 1, max: 2, s: `[nama;${label}ID?]`, d: `Kembalikan variabel ${label} ke nilai awal` },
-      (ctx, [name, id]) => { ctx.bot.resetVar(scope, name, idFor(ctx, id)); return ''; }),
+      async (ctx, [name, id]) => { await ctx.bot.resetVar(scope, name, idFor(ctx, id)); return ''; }),
+    f(`inc${Scope}Var`, { b: 'required', min: 2, max: 3, s: `[nama;jumlah;${label}ID?]`, d: `Tambah variabel ${label} berupa angka (jumlah negatif = kurangi). Aman dari tabrakan antar command. Tidak menampilkan apa pun` },
+      async (ctx, [name, amount, id]) => { await ctx.bot.incVar(scope, name, amount, idFor(ctx, id)); return ''; }),
   );
 }
 
 out.push(
   f('setGlobalVar', { b: 'required', min: 2, max: 2, s: '[nama;nilai]', d: 'Simpan variabel global' },
-    (ctx, [name, value]) => { ctx.bot.setVar('global', name, value, null); return ''; }),
+    async (ctx, [name, value]) => { await ctx.bot.setVar('global', name, value, null); return ''; }),
   f('getGlobalVar', { b: 'required', min: 1, max: 1, s: '[nama]', d: 'Baca variabel global' },
     (ctx, [name]) => ctx.bot.getVar('global', name, null)),
   f('resetGlobalVar', { b: 'required', min: 1, max: 1, s: '[nama]', d: 'Kembalikan variabel global ke nilai awal' },
-    (ctx, [name]) => { ctx.bot.resetVar('global', name, null); return ''; }),
+    async (ctx, [name]) => { await ctx.bot.resetVar('global', name, null); return ''; }),
+  f('incGlobalVar', { b: 'required', min: 2, max: 2, s: '[nama;jumlah]', d: 'Tambah variabel global berupa angka (jumlah negatif = kurangi)' },
+    async (ctx, [name, amount]) => { await ctx.bot.incVar('global', name, amount, null); return ''; }),
 );
 
 module.exports = out;

package/src/index.js

@@ -1,6 +1,6 @@
 'use strict';
 const { Bot } = require('./bot');
-const { Database } = require('./database');
+const { Database, copyDatabase } = require('./database');
 const { Context } = require('./context');
 const { BotError, ParseError, ValidationError } = require('./errors');
 const { parse } = require('./parser');
@@ -9,6 +9,7 @@ const { createRegistry, CATEGORIES } = require('./functions');
 module.exports = {
   Bot,
   Database,
+  copyDatabase,
   Context,
   BotError,
   ParseError,

package/src/plugins/mongodb.js

@@ -0,0 +1,140 @@
+'use strict';
+const { BotError } = require('../errors');
+
+const MISSING = Symbol('missing');
+const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * Adapter database MongoDB. Setiap variabel = satu dokumen { _id: kunci, v: nilai, t: waktuUbah }.
+ *
+ * Opsi:
+ *  - uri          alamat MongoDB (wajib kecuali memberi `client`), mis. process.env.MONGO_URI
+ *  - dbName       nama database (bila kosong dipakai nama dari URI, atau "test")
+ *  - collection   nama collection, bawaan "easydc"
+ *  - cache        true (bawaan): simpan data yang sudah dibaca di RAM. Matikan (false) bila
+ *                 LEBIH DARI SATU proses bot memakai database yang sama.
+ *  - cacheLimit   maksimal jumlah kunci di cache (bawaan 10000)
+ *  - client       MongoClient milik sendiri (tidak ditutup otomatis)
+ *  - driver       modul mongodb sendiri (untuk pengujian)
+ *  - clientOptions opsi tambahan untuk new MongoClient(uri, opsi)
+ */
+class MongoDatabase {
+  constructor(options = {}) {
+    if (!options.uri && !options.client) {
+      throw new BotError('mongodb: opsi "uri" wajib diisi. Contoh: mongodb({ uri: process.env.MONGO_URI, dbName: "botku" })');
+    }
+    this.options = options;
+    this.client = options.client ?? null;
+    this._ownsClient = !options.client;
+    this.collectionName = options.collection ?? 'easydc';
+    if (typeof this.collectionName !== 'string' || !/^[^$\0]{1,120}$/.test(this.collectionName) || this.collectionName.startsWith('system.')) {
+      throw new BotError(`mongodb: nama collection "${this.collectionName}" tidak valid`);
+    }
+    this.useCache = options.cache !== false;
+    this.cacheLimit = options.cacheLimit ?? 10000;
+    this.cache = new Map();
+    this._gen = new Map();
+    this.col = null;
+  }
+
+  _loadDriver() {
+    if (this.options.driver) return this.options.driver;
+    try {
+      // eslint-disable-next-line global-require
+      return require('mongodb');
+    } catch (e) {
+      throw new BotError('Package "mongodb" tidak ditemukan. Jalankan: npm install mongodb', { cause: e });
+    }
+  }
+
+  async connect() {
+    if (this.col) return;
+    if (!this.client) {
+      const { MongoClient } = this._loadDriver();
+      this.client = new MongoClient(this.options.uri, { serverSelectionTimeoutMS: 10000, ...this.options.clientOptions });
+    }
+    await this.client.connect();
+    this.col = this.client.db(this.options.dbName).collection(this.collectionName);
+  }
+
+  _ready() {
+    if (!this.col) throw new BotError('Database MongoDB belum terhubung. Pastikan bot.connect() sudah dipanggil');
+    return this.col;
+  }
+
+  _touch(key) { this._gen.set(key, (this._gen.get(key) ?? 0) + 1); }
+
+  _remember(key, value) {
+    if (!this.useCache) return;
+    this.cache.delete(key); // pindahkan ke posisi terbaru
+    this.cache.set(key, value);
+    if (this.cache.size > this.cacheLimit) this.cache.delete(this.cache.keys().next().value);
+  }
+
+  async get(key) {
+    if (this.useCache && this.cache.has(key)) {
+      const hit = this.cache.get(key);
+      return hit === MISSING ? undefined : hit;
+    }
+    const col = this._ready();
+    const gen = this._gen.get(key) ?? 0;
+    const doc = await col.findOne({ _id: key });
+    // Jangan isi cache bila kunci ini diubah selagi kita membaca (supaya tidak menyimpan data basi)
+    if ((this._gen.get(key) ?? 0) === gen) this._remember(key, doc ? doc.v : MISSING);
+    return doc ? doc.v : undefined;
+  }
+
+  async has(key) { return (await this.get(key)) !== undefined; }
+
+  async set(key, value) {
+    const col = this._ready();
+    this._touch(key);
+    await col.updateOne({ _id: key }, { $set: { v: value, t: new Date() } }, { upsert: true });
+    this._touch(key);
+    this._remember(key, value);
+  }
+
+  async delete(key) {
+    const col = this._ready();
+    this._touch(key);
+    const res = await col.deleteOne({ _id: key });
+    this._touch(key);
+    this._remember(key, MISSING);
+    return (res?.deletedCount ?? 0) > 0;
+  }
+
+  /** Daftar kunci berawalan `prefix` (langsung dari database, bukan dari cache). */
+  async keys(prefix = '') {
+    const col = this._ready();
+    const filter = prefix ? { _id: { $regex: `^${escapeRegex(prefix)}` } } : {};
+    const docs = await col.find(filter, { projection: { _id: 1 } }).toArray();
+    return docs.map((d) => d._id);
+  }
+
+  /** Penulisan ke MongoDB langsung (tanpa antrean), jadi tidak ada yang perlu di-flush. */
+  async flush() {}
+
+  async close() {
+    this.cache.clear();
+    this._gen.clear();
+    const had = this.col;
+    this.col = null;
+    if (had && this._ownsClient && this.client) await this.client.close();
+  }
+}
+
+/**
+ * Plugin MongoDB untuk Bot.
+ *   const { mongodb } = require('easydc-js/mongodb');
+ *   bot.use(mongodb({ uri: process.env.MONGO_URI, dbName: 'botku' }));
+ */
+function mongodb(options) {
+  return {
+    name: 'mongodb',
+    install(bot) {
+      bot.setDatabase(new MongoDatabase(options));
+    },
+  };
+}
+
+module.exports = { mongodb, MongoDatabase };