vimcord 1.0.1 → 1.0.2

package/README.md

@@ -0,0 +1,94 @@
+# vimcord
+
+**Vimcord** (pronounced as in _vhem-cord_) is a lightweight, opinionated framework for **Discord.js**. Built for developers who want to reduce the distance between an idea and a working command without fighting with the library.
+
+## 🚀 Installation
+
+```bash
+npm install vimcord discord.js
+# or
+pnpm add vimcord discord.js
+# or
+yarn add vimcord discord.js
+```
+
+## 🛠 Quick Start
+
+Vimcord uses a `createClient` factory to initialize a pre-configured environment with optional feature flags.
+
+```ts
+import { ActivityType, ClientOptions, GatewayIntentBits } from "discord.js";
+import { createClient, GatewayIntentBits, MongoDatabase, StatusType } from "vimcord";
+
+const client = createClient(
+    {
+        intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages]
+    },
+    {
+        useGlobalErrorHandlers: true,
+        useDefaultSlashCommandHandler: true,
+        useDefaultPrefixCommandHandler: true,
+        useDefaultContextCommandHandler: true,
+
+        // Automatically import the .env using dotEnv
+        useEnv: true,
+
+        // Automatically import event and command modules
+        importModules: {
+            events: "./events",
+            slashCommands: "./commands/slash",
+            prefixCommands: "./commands/prefix"
+            contextCommands: "./commands/context"
+        }
+    }
+);
+
+client.start(async client => {
+    // NOTE: This runs *BEFORE* the client logs in
+
+    // Use Mongo as our database
+    await client.useDatabase(new MongoDatabase(client));
+})
+```
+
+## 🛠 Features
+
+- **CommandManager**: Advanced managers for **Slash**, **Prefix**, and **Context** commands. Includes deep inference for permissions and automated error boundaries.
+- **DatabaseManager**: Seamless **MongoDB/Mongoose** integration via `createMongoSchema` and `useMongoDatabase`.
+- **DiscordTools**: High-level interaction helpers including the **Paginator**, **Prompt**, and **BetterModal** for stateful UI.
+- **DiscordUtils**: Essential Discord-first utilities like `dynaSend`, `fetchMember`, and `isMentionOrSnowflake`.
+- **Logger**: A fun, retro style console logger for clear, actionable terminal output.
+
+## 💎 Useful Utilities
+
+### **The BetterEmbed & ACF**
+
+Stop writing boilerplate for user mentions and avatars. `BetterEmbed` supports **Shorthand Context Formatting (ACF)**, allowing you to use tokens like `$USER` and `$BOT_AVATAR` directly in strings. Vimcord resolves them at runtime.
+
+### **The Paginator (Chapters & Nested Pages)**
+
+Multi-page embeds shouldn't be a chore. The `Paginator` supports **Chapters**, enabling complex, nested page structures with built-in navigation logic and select menu support.
+
+### **The DynaSend: Smart Dispatch**
+
+`DynaSend` is an intelligent message delivery system. It automatically detects the interaction state to decide whether to `.reply()`, `.editReply()`, or `.followUp()`. You write one line; Vimcord handles the logic.
+
+### **MongoSchemaBuilder: Resilient DB Ops**
+
+The `execute` method on your schemas includes built-in **exponential backoff**. If the database is under load or reconnecting, Vimcord retries the operation instead of crashing your command.
+
+## 👀 Mentionables
+
+- **Strictly Typed**: Full TypeScript support with deep inference for command permissions, events, and database documents.
+- **Feature-Rich**: Includes a built-in CLI, automated status rotation, and sophisticated error boundaries.
+- **Developer-Centric**: Focused on performance and ergonomics.
+
+## 👋 About
+
+_Vimcord was created by **xsqu1znt**,_ and designed for developers who value performance and aesthetic code.
+
+It also takes advantage of my lightweight library [qznt](https://github.com/xsqu1znt/qznt) for a smooth experience.
+
+## **_Vimcord is still a work in progress. If you find any bugs, please let me know._**
+
+License: MIT

package/dist/index.cjs

@@ -525,8 +525,8 @@ var ContextCommandBuilder = class extends BaseCommandBuilder {
 };
 
 // src/utils/dir.ts
-var import_jstools = __toESM(require("jstools"));
 var import_node_path = __toESM(require("path"));
+var import_qznt = require("qznt");
 function getProcessDir() {
   const mainPath = process.argv[1];
   if (!mainPath) return "";
@@ -536,7 +536,7 @@ async function importModulesFromDir(dir, fnPrefix) {
   const cwd = getProcessDir();
   const MODULE_RELATIVE_PATH = import_node_path.default.join(cwd, dir);
   const MODULE_LOG_PATH = dir;
-  const files = import_jstools.default.readDir(MODULE_RELATIVE_PATH, { recursive: true }).filter(
+  const files = import_qznt.$.fs.readDir(MODULE_RELATIVE_PATH).filter(
     (fn) => fn.endsWith(`${fnPrefix ? `.${fnPrefix}` : ""}.js`) || fn.endsWith(`${fnPrefix ? `.${fnPrefix}` : ""}.ts`)
   );
   if (!files.length) {
@@ -1341,28 +1341,9 @@ function formatThousands(num, sep = ",") {
   return `${num}`.replace(/\B(?<!\.\d*)(?=(\d{3})+(?!\d))/g, sep);
 }
 
-// src/utils/random.ts
-function pickRandom(arr, options) {
-  const _rnd = () => {
-    return arr[Math.floor(Math.random() * arr.length)];
-  };
-  let att = 0;
-  let candidate = _rnd();
-  if (options?.notEqualTo !== void 0 && arr.length > 1) {
-    while (candidate === options.notEqualTo) {
-      if (att < (options?.maxRerollAttempts ?? 100)) {
-        throw new Error(`pickRandom reached max reroll attempts (${options?.maxRerollAttempts ?? 100})`);
-      }
-      candidate = _rnd();
-      att++;
-    }
-  }
-  return options?.clone ? structuredClone(candidate) : candidate;
-}
-
 // src/modules/status.manager.ts
-var import_node_cron = __toESM(require("node-cron"));
 var import_node_events = __toESM(require("events"));
+var import_qznt2 = require("qznt");
 var VimcordStatusManager = class {
   client;
   logger;
@@ -1383,24 +1364,9 @@ var VimcordStatusManager = class {
         this.logger.debug("Status cleared");
       }
     });
-    this.emitter.on("rotation", () => {
-      if (this.client.config.app.verbose) {
-        this.logger.debug("Status rotated");
-      }
-    });
-    this.emitter.on("rotationStarted", () => {
-      if (this.client.config.app.verbose) {
-        this.logger.debug("Status rotation resumed \u25B6\uFE0F");
-      }
-    });
-    this.emitter.on("rotationPaused", () => {
-      if (this.client.config.app.verbose) {
-        this.logger.debug("Status rotation paused \u23F8\uFE0F");
-      }
-    });
   }
   clearData() {
-    this.task?.destroy();
+    this.task?.stop();
     this.task = null;
     this.lastActivity = null;
     this.lastActivityIndex = 0;
@@ -1433,11 +1399,8 @@ var VimcordStatusManager = class {
   }
   async statusRotationTask(clientStatus) {
     let activity;
-    if (clientStatus.randomize) {
-      activity = pickRandom(clientStatus.activity, {
-        notEqualTo: this.lastActivity,
-        clone: true
-      });
+    if (clientStatus.randomize && Array.isArray(clientStatus.activity)) {
+      activity = import_qznt2.$.rnd.choice(clientStatus.activity, { not: this.lastActivity });
       this.lastActivity = activity;
     } else {
       const activityIndex = (this.lastActivityIndex + 1) % clientStatus.activity.length;
@@ -1449,34 +1412,22 @@ var VimcordStatusManager = class {
   }
   async scheduleStatusRotation(clientStatus) {
     if (!clientStatus.interval) throw new Error("Cannot create client activity interval without interval time");
-    this.task?.destroy();
+    this.task?.stop();
     this.task = null;
-    await this.statusRotationTask(clientStatus);
-    this.task = import_node_cron.default.createTask(
-      `*/${clientStatus.interval} * * * * *`,
-      async () => await this.statusRotationTask(clientStatus),
-      { noOverlap: true }
-    );
+    this.task = new import_qznt2.$.Loop(() => this.statusRotationTask(clientStatus), import_qznt2.$.math.ms(clientStatus.interval), true);
     this.start();
-    this.emitter.emit("rotationStarted", this.task);
   }
   start() {
     if (this.task) {
       this.task.start();
-      this.emitter.emit("rotationStarted", this.task);
-      if (this.client.config.app.verbose) {
-        this.logger.debug("Status rotation started");
-      }
+      this.emitter.emit("started", this.task);
     }
     return this;
   }
   pause() {
     if (this.task) {
       this.task.stop();
-      this.emitter.emit("rotationPaused", this.task);
-      if (this.client.config.app.verbose) {
-        this.logger.debug("Status rotation paused");
-      }
+      this.emitter.emit("paused", this.task);
     }
     return this;
   }
@@ -1490,21 +1441,16 @@ var VimcordStatusManager = class {
     }
     if (!clientStatus.interval) {
       await this.setActivity(Array.isArray(clientStatus.activity) ? clientStatus.activity[0] : clientStatus.activity);
-      return this;
-    }
-    if (clientStatus.interval) {
+    } else {
       await this.scheduleStatusRotation(clientStatus);
     }
     return this;
   }
   async destroy() {
     if (this.task) {
-      this.task.destroy();
+      this.task.stop();
       this.task = null;
-      this.emitter.emit("rotationDestroyed");
-      if (this.client.config.app.verbose) {
-        this.logger.debug("Status rotation destroyed");
-      }
+      this.emitter.emit("destroyed");
       await this.clear();
     }
     return this;
@@ -1514,9 +1460,6 @@ var VimcordStatusManager = class {
     this.clearData();
     client.user.setActivity({ name: "" });
     this.emitter.emit("cleared");
-    if (this.client.config.app.verbose) {
-      this.logger.debug("Status cleared");
-    }
     return this;
   }
 };
@@ -3046,7 +2989,7 @@ var BetterCollector = class _BetterCollector {
             if (shouldBeDeferred.update) {
               await interaction.deferUpdate().catch(Boolean);
             } else {
-              await interaction.deferReply({ ephemeral: shouldBeDeferred.ephemeral }).catch(Boolean);
+              await interaction.deferReply({ flags: shouldBeDeferred.ephemeral ? "Ephemeral" : void 0 }).catch(Boolean);
             }
           } else {
             await interaction.deferReply().catch(Boolean);
@@ -3057,7 +3000,7 @@ var BetterCollector = class _BetterCollector {
             try {
               const isAllowed = await this.validateParticipant(interaction, listener.options?.participants);
               if (!isAllowed) return;
-              await listener.fn(interaction);
+              await listener.fn(interaction).finally(() => listener.options?.finally?.(interaction));
             } catch (err) {
               this.handleListenerError(err);
             }
@@ -3067,7 +3010,7 @@ var BetterCollector = class _BetterCollector {
             allListeners.map((l) => {
               const isAllowed = this.validateParticipant(interaction, l.options?.participants);
               if (!isAllowed) return;
-              return l.fn(interaction).catch(this.handleListenerError);
+              return l.fn(interaction).catch(this.handleListenerError).finally(() => l.options?.finally?.(interaction));
             })
           );
         }
@@ -3917,6 +3860,7 @@ var Prompt = class {
   content;
   embed;
   container;
+  textOnly;
   buttons;
   customButtons;
   onResolve;
@@ -3930,6 +3874,7 @@ var Prompt = class {
     this.content = options.content;
     this.embed = options.embed ?? this.createDefaultForm();
     this.container = options?.container;
+    this.textOnly = options.textOnly;
     this.buttons = this.createButtons(options.buttons);
     this.customButtons = this.createCustomButtons(options.customButtons);
     this.onResolve = options.onResolve ?? [3 /* DeleteOnConfirm */, 4 /* DeleteOnReject */];
@@ -4009,7 +3954,7 @@ var Prompt = class {
   }
   buildSendOptions(options) {
     const sendData = { ...options };
-    if (this.container) {
+    if (!this.textOnly && this.container) {
       sendData.components = Array.isArray(sendData.components) ? [...sendData.components, this.container] : [this.container];
       const existingFlags = sendData.flags ? Array.isArray(sendData.flags) ? sendData.flags : [sendData.flags] : [];
       if (!existingFlags.includes("IsComponentsV2")) {
@@ -4018,7 +3963,9 @@ var Prompt = class {
         sendData.flags = existingFlags;
       }
     } else {
-      sendData.embeds = Array.isArray(sendData.embeds) ? [this.embed, ...sendData.embeds] : [this.embed];
+      if (!this.textOnly) {
+        sendData.embeds = Array.isArray(sendData.embeds) ? [this.embed, ...sendData.embeds] : [this.embed];
+      }
     }
     if (this.content) {
       sendData.content = this.content;
@@ -4104,7 +4051,7 @@ async function prompt(handler, options, sendOptions) {
 
 // src/utils/VimcordCLI.ts
 var import_node_readline = require("readline");
-var import_jstools2 = __toESM(require("jstools"));
+var import_qznt3 = require("qznt");
 var VimcordCLI = class {
   rl;
   options;
@@ -4143,7 +4090,7 @@ var VimcordCLI = class {
     return { isCommand: true, commandName, content: args.join(" "), args };
   }
   getClientInstance(line) {
-    const clientIndex = import_jstools2.default.getFlagSubstring(line, "--client", 1) || import_jstools2.default.getFlagSubstring(line, "-c", 1);
+    const clientIndex = import_qznt3.$.str.getFlag(line, "--client", 1) || import_qznt3.$.str.getFlag(line, "-c", 1);
     if (clientIndex) {
       const idx = Number(clientIndex);
       if (isNaN(idx)) {
@@ -4193,7 +4140,7 @@ CLI.addCommand("register", "Register app commands (slash & context) globally, or
   if (!["guild", "global"].includes(mode)) {
     return CLI.logger.error(`'${mode}' is not a valid option. Your options are [guild|global]`);
   }
-  let guildIds = (import_jstools2.default.getFlagSubstring(content, "--guilds", 1) || import_jstools2.default.getFlagSubstring(content, "-g", 1) || "").replaceAll(/["']/g, "").split(" ").filter(Boolean).map((s) => s.replaceAll(",", "").trim());
+  let guildIds = (import_qznt3.$.str.getFlag(content, "--guilds", 1) || import_qznt3.$.str.getFlag(content, "-g", 1) || "").replaceAll(/["']/g, "").split(" ").filter(Boolean).map((s) => s.replaceAll(",", "").trim());
   if (!guildIds.length) guildIds = client.guilds.cache.map((g) => g.id);
   switch (mode) {
     case "guild":
@@ -4215,7 +4162,7 @@ CLI.addCommand("unregister", "Unregister app commands globally, or per guild", a
   if (!["guild", "global"].includes(mode)) {
     return CLI.logger.error(`'${mode}' is not a valid option. Your options are [guild|global]`);
   }
-  let guildIds = (import_jstools2.default.getFlagSubstring(content, "--guilds", 1) || import_jstools2.default.getFlagSubstring(content, "-g", 1) || "").replaceAll(/["']/g, "").split(" ").filter(Boolean).map((s) => s.replaceAll(",", "").trim());
+  let guildIds = (import_qznt3.$.str.getFlag(content, "--guilds", 1) || import_qznt3.$.str.getFlag(content, "-g", 1) || "").replaceAll(/["']/g, "").split(" ").filter(Boolean).map((s) => s.replaceAll(",", "").trim());
   if (!guildIds.length) guildIds = client.guilds.cache.map((g) => g.id);
   switch (mode) {
     case "guild":
@@ -4234,9 +4181,9 @@ CLI.addCommand("stats", "View statistics about a client instance", (args, conten
   const client = CLI.getClientInstance(content);
   if (!client) return;
   CLI.logger.table(`(stats) ~ ${client.config.app.name}`, {
-    "Guilds:": import_jstools2.default.formatThousands(client.guilds.cache.size),
+    "Guilds:": import_qznt3.$.format.number(client.guilds.cache.size),
     "Ping:": `${client.ws.ping || 0}ms`,
-    "Uptime:": `${import_jstools2.default.msToSec(client.uptime || 0)}s`,
+    "Uptime:": `${import_qznt3.$.math.secs(client.uptime || 0)}s`,
     "Process Uptime:": `${Math.floor(process.uptime())}s`,
     "Memory Usage:": `${(process.memoryUsage().rss / 1024 / 1024).toFixed(2)} MB`
   });
@@ -4253,7 +4200,7 @@ CLI.addCommand("cmds", "List the loaded commands", async (args, content) => {
       for (const cmd of commands) {
         tableData[`/${cmd.builder.name}`] = `~ ${cmd.builder.description || "No description"}`;
       }
-      return CLI.logger.table(`(cmds) ~ slash (${import_jstools2.default.formatThousands(commands.length)})`, tableData);
+      return CLI.logger.table(`(cmds) ~ slash (${import_qznt3.$.format.number(commands.length)})`, tableData);
     }
     case "prefix": {
       const commands = Array.from(client.commands.prefix.commands.values());
@@ -4269,7 +4216,7 @@ CLI.addCommand("cmds", "List the loaded commands", async (args, content) => {
         const aliasIndicator = config.aliases?.length ? ` [${config.aliases.join(", ")}]` : "";
         tableData[`${defaultPrefix}${config.name}${aliasIndicator}`] = `~ ${config.description || "No description"}`;
       }
-      return CLI.logger.table(`(cmds) ~ prefix (${import_jstools2.default.formatThousands(commands.length)})`, tableData);
+      return CLI.logger.table(`(cmds) ~ prefix (${import_qznt3.$.format.number(commands.length)})`, tableData);
     }
     case "ctx": {
       const commands = Array.from(client.commands.context.commands.values());
@@ -4279,7 +4226,7 @@ CLI.addCommand("cmds", "List the loaded commands", async (args, content) => {
         const type = cmd.builder.type === 2 ? "User" : "Msg";
         tableData[`[${type}] ${cmd.builder.name}`] = "";
       }
-      return CLI.logger.table(`(cmds) ~ ctx (${import_jstools2.default.formatThousands(commands.length)})`, tableData);
+      return CLI.logger.table(`(cmds) ~ ctx (${import_qznt3.$.format.number(commands.length)})`, tableData);
     }
     default:
       return CLI.logger.error(`'${mode}' is not a valid option. Valid options: [slash|prefix|ctx]`);
@@ -4306,6 +4253,25 @@ function createClient(options, features = {}, config = {}) {
 function getClientInstances() {
   return clientInstances;
 }
+
+// src/utils/random.ts
+function pickRandom(arr, options) {
+  const _rnd = () => {
+    return arr[Math.floor(Math.random() * arr.length)];
+  };
+  let att = 0;
+  let candidate = _rnd();
+  if (options?.notEqualTo !== void 0 && arr.length > 1) {
+    while (candidate === options.notEqualTo) {
+      if (att < (options?.maxRerollAttempts ?? 100)) {
+        throw new Error(`pickRandom reached max reroll attempts (${options?.maxRerollAttempts ?? 100})`);
+      }
+      candidate = _rnd();
+      att++;
+    }
+  }
+  return options?.clone ? structuredClone(candidate) : candidate;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BaseCommandBuilder,