js-discord-modularcommand 1.1.0 → 2.0.1

package/dist/registercommand.js

@@ -0,0 +1,249 @@
+"use strict";
+/**
+ * @file Contains the logic for registering modular commands and building their Discord.js data structures.
+ * @author vicentefelipechile
+ * @license MIT
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = RegisterCommand;
+const discord_js_1 = require("discord.js");
+const cooldown_1 = __importStar(require("./cooldown"));
+const locales_1 = require("./locales");
+/**
+ * @description Gets the appropriate localization object for a command based on the interaction's locale.
+ * Falls back to EnglishUS if the target locale is not available.
+ * @param {ModularCommand} command The command instance.
+ * @param {Interaction} interaction The interaction object to get the locale from.
+ * @returns {CommandLocale} The resolved locale object.
+ * @throws {Error} If the EnglishUS localization is missing.
+ */
+function getCommandLocale(command, interaction) {
+    const localeTable = command.localizationPhrases;
+    if (!localeTable || !localeTable[discord_js_1.Locale.EnglishUS]) {
+        throw new Error(`Missing localization for EnglishUS in command ${command.name}`);
+    }
+    const targetLocale = localeTable[interaction.locale] ? interaction.locale : discord_js_1.Locale.EnglishUS;
+    return { [targetLocale]: localeTable[targetLocale] };
+}
+// =================================================================================================
+// Execution Context Constructors
+// =================================================================================================
+/**
+ * @description Creates the execution function for chat input (slash) commands.
+ * @param {ModularCommand} command The command to create the executor for.
+ * @param {Record<string, OptionType>} options The parsed options for argument retrieval.
+ * @returns {Function} The async function that will handle the interaction.
+ */
+function createChatInputExecutor(command, options) {
+    return async (interaction) => {
+        // Permission & NSFW Checks
+        if (command.permissionCheck && !command.permissionCheck({ interaction })) {
+            await interaction.reply({ content: locales_1.LOCALE_FORBIDDEN[interaction.locale], flags: discord_js_1.MessageFlags.Ephemeral });
+            return;
+        }
+        if (command.isNSFW && (!interaction.channel || !('nsfw' in interaction.channel) || !interaction.channel.nsfw)) {
+            await interaction.reply({ content: locales_1.LOCALE_NSFW[interaction.locale], flags: discord_js_1.MessageFlags.Ephemeral });
+            return;
+        }
+        // Cooldown Check
+        const { inCooldown, waitTime } = (0, cooldown_1.default)(command.name, interaction.user.id);
+        if (inCooldown) {
+            await interaction.reply({ content: locales_1.LOCALE_DELAY[interaction.locale].formatTime(waitTime), flags: discord_js_1.MessageFlags.Ephemeral });
+            return;
+        }
+        (0, cooldown_1.cooldownSetUser)(command.name, interaction.user.id);
+        // Argument Parsing
+        const args = {};
+        for (const optionName of Object.keys(options)) {
+            switch (options[optionName]) {
+                case discord_js_1.ApplicationCommandOptionType.String:
+                    args[optionName] = interaction.options.getString(optionName, false);
+                    break;
+                case discord_js_1.ApplicationCommandOptionType.Boolean:
+                    args[optionName] = interaction.options.getBoolean(optionName, false);
+                    break;
+                case discord_js_1.ApplicationCommandOptionType.Integer:
+                    args[optionName] = interaction.options.getInteger(optionName, false);
+                    break;
+                case discord_js_1.ApplicationCommandOptionType.Number:
+                    args[optionName] = interaction.options.getNumber(optionName, false);
+                    break;
+                case discord_js_1.ApplicationCommandOptionType.User:
+                    args[optionName] = interaction.options.getUser(optionName, false);
+                    break;
+                default: throw new Error(`Unsupported option type: ${options[optionName]}`);
+            }
+        }
+        const locale = getCommandLocale(command, interaction);
+        // Execute Handler
+        await command.execute({ interaction, args, command, locale });
+    };
+}
+/**
+ * @description Creates the execution function for message components.
+ * @param {ModularCommand} command The command to create the executor for.
+ * @returns {Function|undefined} The async function or undefined if not needed.
+ */
+function createComponentExecutor(command) {
+    const executor = command.componentExecute;
+    if (executor === undefined)
+        return undefined;
+    return async (interaction) => {
+        if (!interaction.customId.startsWith(command.componentId || ''))
+            return;
+        await executor({
+            interaction,
+            command,
+            locale: getCommandLocale(command, interaction),
+        });
+    };
+}
+/**
+ * @description Creates the execution function for modal submissions.
+ * @param {ModularCommand} command The command to create the executor for.
+ * @returns {Function|undefined} The async function or undefined if not needed.
+ */
+function createModalExecutor(command) {
+    if (command.modals.size === 0)
+        return undefined;
+    return async (interaction) => {
+        const modalObject = command.modals.get(interaction.customId);
+        if (!modalObject)
+            return;
+        const args = {};
+        for (const [id] of modalObject.modalInputs.entries()) {
+            args[id] = interaction.fields.getTextInputValue(id);
+        }
+        await modalObject.execute({
+            interaction,
+            args,
+            command,
+            locale: getCommandLocale(command, interaction),
+        });
+    };
+}
+/**
+ * @description Creates the execution function for button interactions.
+ * @param {ModularCommand} command The command to create the executor for.
+ * @returns {Function|undefined} The async function or undefined if not needed.
+ */
+function createButtonExecutor(command) {
+    if (command.buttons.size === 0)
+        return undefined;
+    return async (interaction) => {
+        const buttonObject = command.buttons.get(interaction.customId);
+        if (!buttonObject)
+            return;
+        await buttonObject.execute({
+            interaction,
+            command,
+            locale: getCommandLocale(command, interaction),
+            message: interaction.message,
+        });
+    };
+}
+// =================================================================================================
+// Main Registration Function
+// =================================================================================================
+/**
+ * @description Registers an array of modular commands, building their final `CommandData` objects.
+ * This function processes the command definitions, sets up command builders, and assigns the execution logic.
+ * @param {ModularCommand[]} commands An array of ModularCommand instances.
+ * @returns {CommandData[]} An array of command data objects ready for the Discord.js client.
+ */
+function RegisterCommand(commands) {
+    commands = Array.isArray(commands) ? commands : [commands];
+    return commands.map(command => {
+        if (command.name === undefined)
+            throw new Error("A command is missing a name.");
+        if (command.description === undefined)
+            throw new Error(`Command "${command.name}" is missing a description.`);
+        // Build SlashCommand Data
+        const commandBuilder = new discord_js_1.SlashCommandBuilder()
+            .setName(command.name)
+            .setDescription(command.description)
+            .setDescriptionLocalizations(command.descriptionLocalizations || null);
+        (0, cooldown_1.cooldownRegister)(command.name, command.cooldown);
+        const options = {};
+        command.options.forEach(opt => {
+            const description = typeof opt.description === 'string'
+                ? opt.description
+                : (opt.description[discord_js_1.Locale.EnglishUS] || `The description for ${opt.name} in English.`);
+            if (!description) {
+                throw new Error(`Option '${opt.name}' is missing a description.`);
+            }
+            options[opt.name] = opt.type;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const optionBuilder = (option) => {
+                option.setName(opt.name)
+                    .setDescription(description)
+                    .setRequired(opt.required || false)
+                    .setDescriptionLocalizations(typeof opt.description === 'object' ? opt.description : {});
+                if (opt.choices && opt.choices.length > 0) {
+                    option.addChoices(...opt.choices);
+                }
+                return option;
+            };
+            switch (opt.type) {
+                case discord_js_1.ApplicationCommandOptionType.String:
+                    commandBuilder.addStringOption(optionBuilder);
+                    break;
+                case discord_js_1.ApplicationCommandOptionType.Boolean:
+                    commandBuilder.addBooleanOption(optionBuilder);
+                    break;
+                case discord_js_1.ApplicationCommandOptionType.Integer:
+                    commandBuilder.addIntegerOption(optionBuilder);
+                    break;
+                case discord_js_1.ApplicationCommandOptionType.Number:
+                    commandBuilder.addNumberOption(optionBuilder);
+                    break;
+                case discord_js_1.ApplicationCommandOptionType.User:
+                    commandBuilder.addUserOption(optionBuilder);
+                    break;
+                default: throw new Error(`Unsupported option type: ${opt.type}`);
+            }
+        });
+        // Assign Handlers using Constructors
+        return {
+            data: commandBuilder,
+            execute: createChatInputExecutor(command, options),
+            componentExecute: createComponentExecutor(command),
+            modalExecute: createModalExecutor(command),
+            buttonExecute: createButtonExecutor(command),
+            cooldown: command.cooldown,
+        };
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * @file Contains the type and interface definitions for the Discord bot's modular commands.
+ * @author vicentefelipechile
+ * @license MIT
+ */
+import { ApplicationCommandOptionType as OptionType, APIApplicationCommandOptionChoice, ChatInputCommandInteraction, MessageComponentInteraction, ModalSubmitInteraction, CommandInteraction, ButtonInteraction, SlashCommandBuilder, PartialDMChannel, ThreadChannel, GuildChannel, Collection, Message, Locale, Client, User } from "discord.js";
+import ModularCommand from "./modularcommand";
+/**
+ * @interface CommandOption
+ * @description Defines the structure of an option for a slash command.
+ */
+export interface CommandOption {
+    /** The name of the option, must be unique within the command. */
+    name: string;
+    /** The data type the option expects (e.g., STRING, USER, CHANNEL). */
+    type: AllowedOptionType;
+    /** The description of the option. It can be a string or an object for localization. */
+    description: Record<Locale, string> | string;
+    /** Defines if the option is required. */
+    required?: boolean;
+    /** An array of predefined choices the user can select from. */
+    choices?: APIApplicationCommandOptionChoice[];
+}
+/**
+ * @interface CommandData
+ * @description Represents the final structure of a registered command, ready to be used by the Discord client.
+ */
+export interface CommandData {
+    /** The slash command configuration built with SlashCommandBuilder. */
+    data: SlashCommandBuilder;
+    /** The main function that executes when the command is invoked. */
+    execute: (interaction: ChatInputCommandInteraction) => Promise<void>;
+    /** (Optional) Function to handle component interactions (e.g., select menus). */
+    componentExecute?: (interaction: MessageComponentInteraction) => Promise<void>;
+    /** (Optional) Function to handle modal submissions. */
+    modalExecute?: (interaction: ModalSubmitInteraction) => Promise<void>;
+    /** (Optional) Function to handle button interactions. */
+    buttonExecute?: (interaction: ButtonInteraction) => Promise<void>;
+    /** The command's cooldown time in seconds. */
+    cooldown: number;
+}
+/**
+ * @const ALLOWED_OPTION_TYPE
+ * @description A list of allowed option types for slash commands.
+ */
+export declare const ALLOWED_OPTION_TYPE: readonly [OptionType.String, OptionType.Boolean, OptionType.Integer, OptionType.Number, OptionType.User];
+/**
+ * @type AllowedOptionType
+ * @description The union type of allowed option types for slash commands.
+ */
+export type AllowedOptionType = typeof ALLOWED_OPTION_TYPE[number];
+/**
+ * @type LocaleKey
+ * @description An object that maps text identifiers to their translations.
+ * @example { "GREETING": "Hello!", "FAREWELL": "Goodbye!" }
+ */
+export type LocaleKey = Record<string, string>;
+/**
+ * @type ClientWithCommands
+ * @description Extends the discord.js `Client` type to include a collection of commands.
+ */
+export type ClientWithCommands = Client & {
+    commands: Collection<string, CommandData>;
+};
+/**
+ * @type CommandArgumentValue
+ * @description Represents the possible value types that a command argument can have.
+ */
+export type CommandArgumentValue = string | boolean | number | User | GuildChannel | ThreadChannel | PartialDMChannel | null;
+/**
+ * @type BaseExecuteParams
+ * @description Defines the base parameters shared by all execution functions.
+ */
+export type BaseExecuteParams<T extends CommandInteraction | MessageComponentInteraction | ModalSubmitInteraction> = {
+    /** The interaction received from Discord. */
+    interaction: T;
+    /** The instance of the modular command being executed. */
+    command: ModularCommand;
+    /** The localization object to get translated texts. */
+    locale: LocaleKey;
+};
+/**
+ * @type CommandExecuteParams
+ * @description Parameters for the execution function of a chat command.
+ */
+export type CommandExecuteParams = BaseExecuteParams<ChatInputCommandInteraction> & {
+    /** An object containing the arguments provided by the user. */
+    args?: Record<string, CommandArgumentValue>;
+};
+/**
+ * @type ButtonExecuteParams
+ * @description Parameters for the execution function of a button.
+ */
+export type ButtonExecuteParams = BaseExecuteParams<ButtonInteraction> & {
+    /** The message to which the button is attached. */
+    message: Message;
+};
+/**
+ * @type ModalExecuteParams
+ * @description Parameters for the execution function of a modal.
+ */
+export type ModalExecuteParams = BaseExecuteParams<ModalSubmitInteraction> & {
+    /** An object with the values of the fields submitted in the modal. */
+    args: Record<string, string>;
+};
+/**
+ * @type CommandExecuteFunction
+ * @description Defines the signature for the main execution function of a command.
+ */
+export type CommandExecuteFunction = (params: CommandExecuteParams) => Promise<void>;
+/**
+ * @type ComponentExecuteFunction
+ * @description Defines the signature for the function that handles generic component interactions.
+ */
+export type ComponentExecuteFunction = (params: BaseExecuteParams<MessageComponentInteraction>) => Promise<void>;
+/**
+ * @type ButtonExecuteFunction
+ * @description Defines the signature for the function that handles button interactions.
+ */
+export type ButtonExecuteFunction = (params: ButtonExecuteParams) => Promise<void>;
+/**
+ * @type ModalExecuteFunction
+ * @description Defines the signature for the function that handles a modal submission.
+ */
+export type ModalExecuteFunction = (params: ModalExecuteParams) => Promise<void>;
+/**
+ * @type PermissionCheckFunction
+ * @description Defines the signature for a function that checks a user's permissions to execute a command.
+ * @returns {boolean | Promise<boolean>} `true` if the user has permission, `false` otherwise.
+ */
+export type PermissionCheckFunction = (params: {
+    interaction: CommandInteraction;
+}) => boolean | Promise<boolean>;

package/dist/types.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * @file Contains the type and interface definitions for the Discord bot's modular commands.
+ * @author vicentefelipechile
+ * @license MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALLOWED_OPTION_TYPE = void 0;
+const discord_js_1 = require("discord.js");
+// =================================================================================================
+// Generic and Utility Types
+// =================================================================================================
+/**
+ * @const ALLOWED_OPTION_TYPE
+ * @description A list of allowed option types for slash commands.
+ */
+exports.ALLOWED_OPTION_TYPE = [
+    discord_js_1.ApplicationCommandOptionType.String,
+    discord_js_1.ApplicationCommandOptionType.Boolean,
+    discord_js_1.ApplicationCommandOptionType.Integer,
+    discord_js_1.ApplicationCommandOptionType.Number,
+    discord_js_1.ApplicationCommandOptionType.User,
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-discord-modularcommand",
-  "version": "1.1.0",
+  "version": "2.0.1",
   "description": "",
   "keywords": [
     "discord",
@@ -17,13 +17,22 @@
   "main": "./dist/index.js",
   "scripts": {
     "build": "tsc",
-    "prepublish": "npm run build"
+    "prepublish": "npm run build",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix"
   },
   "dependencies": {
     "discord.js": "^14.21.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.34.0",
     "@types/node": "^24.2.1",
-    "typescript": "^5.9.2"
+    "@typescript-eslint/eslint-plugin": "^8.41.0",
+    "@typescript-eslint/parser": "^8.41.0",
+    "eslint": "^9.34.0",
+    "globals": "^16.3.0",
+    "jiti": "^2.5.1",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.41.0"
   }
 }