@julanzw/ttoolbox-discordjs-framework 1.2.0 → 1.4.0

package/dist/classes/Command.class.d.ts

@@ -173,4 +173,97 @@ export declare abstract class Command {
      * Set the error reporter for this command
      */
     setErrorReporter(reporter: ErrorReporter): void;
+    /**
+     * Lifecycle hook called before command execution.
+     *
+     * Can be used for:
+     * - Custom validation
+     * - Logging/analytics
+     * - Loading user preferences
+     * - Rate limiting checks
+     * - And more...
+     *
+     * If this hook throws an error or returns false, execution is stopped.
+     *
+     * @param interaction - The command interaction
+     * @returns true to continue execution, false to stop (or throw an error)
+     *
+     * @example
+     * ```typescript
+     * protected async beforeExecute(interaction: ChatInputCommandInteraction): Promise<boolean> {
+     *   // Log command usage
+     *   console.log(`${interaction.user.tag} used ${this.name}`);
+     *
+     *   // Check custom rate limit
+     *   if (await this.isRateLimited(interaction.user.id)) {
+     *     await interaction.reply('You are rate limited!');
+     *     return false; // Stop execution
+     *   }
+     *
+     *   return true; // Continue
+     * }
+     * ```
+     */
+    protected beforeExecute?(interaction: ChatInputCommandInteraction, client: Client): Promise<boolean | void>;
+    /**
+     * Lifecycle hook called after successful command execution.
+     *
+     * Can be used for:
+     * - Analytics tracking
+     * - Cleanup tasks
+     * - Success logging
+     * - Updating usage statistics
+     * - And more...
+     *
+     * Note: This is **NOT** called if the command throws an error (use onError for that).
+     *
+     * @param interaction - The command interaction
+     *
+     * @example
+     * ```typescript
+     * protected async afterExecute(interaction: ChatInputCommandInteraction): Promise<void> {
+     *   // Track command usage
+     *   await analytics.track('command_used', {
+     *     command: this.name,
+     *     user: interaction.user.id,
+     *   });
+     *
+     *   // Update user stats
+     *   await incrementCommandCount(interaction.user.id);
+     * }
+     * ```
+     */
+    protected afterExecute?(interaction: ChatInputCommandInteraction, client: Client): Promise<void>;
+    /**
+     * Lifecycle hook called when command execution fails.
+     *
+     * Can be used for:
+     * - Custom error handling
+     * - Error reporting to external services
+     * - User-friendly error messages
+     * - Cleanup after errors
+     * - And more...
+     *
+     * The error is rethrown after this hook.
+     *
+     * @param interaction - The command interaction
+     * @param error - The error that occurred
+     *
+     * @example
+     * ```typescript
+     * protected async onError(interaction: ChatInputCommandInteraction, error: Error): Promise<void> {
+     *   // Send to Sentry
+     *   Sentry.captureException(error, {
+     *     tags: { command: this.name },
+     *     user: { id: interaction.user.id },
+     *   });
+     *
+     *   // Custom error message
+     *   if (error.message.includes('DATABASE')) {
+     *     await interaction.reply('Database is temporarily unavailable. Try again later.');
+     *   }
+     * }
+     * ```
+     */
+    protected onError?(interaction: ChatInputCommandInteraction, error: Error, client: Client): Promise<void>;
 }

package/dist/classes/Command.class.js

@@ -116,7 +116,24 @@ export class Command {
             const error = this.validate(interaction);
             if (error)
                 return await safeReply(interaction, error, true);
-            await this.run(interaction, client);
+            if (this.beforeExecute) {
+                const shouldContinue = await this.beforeExecute(interaction, client);
+                if (shouldContinue === false) {
+                    return;
+                }
+            }
+            try {
+                await this.run(interaction, client);
+                if (this.afterExecute) {
+                    await this.afterExecute(interaction, client);
+                }
+            }
+            catch (err) {
+                if (this.onError) {
+                    await this.onError(interaction, err, client);
+                }
+                throw err;
+            }
         });
     }
     /**

package/dist/classes/SubcommandGroup.class.d.ts

@@ -35,20 +35,6 @@ export declare abstract class SubcommandGroup {
     protected logger?: ILogger;
     /** ErrorReporter instance to use inside the subcommand group */
     private errorReporter?;
-    /**
-     * Safely executes a function with error handling and logging.
-     *
-     * Wraps the execution in a try-catch block, logs successful executions,
-     * and automatically handles errors by logging them and sending a user-friendly
-     * error message.
-     *
-     * @param subcommandName - The name of the subcommand
-     * @param scope - The logging scope for this execution
-     * @param interaction - The command interaction
-     * @param fn - The function to execute
-     * @private
-     */
-    private safeExecute;
     /**
      * Executes the appropriate subcommand based on the user's interaction.
      *
@@ -131,4 +117,19 @@ export declare abstract class SubcommandGroup {
      * Set the error reporter for this subcommand group.
      */
     setErrorReporter(reporter: ErrorReporter): this;
+    /**
+     * Lifecycle hook called before any subcommand in this group executes.
+     *
+     * @param interaction - The command interaction
+     * @returns true to continue, false to stop execution
+     */
+    protected beforeExecute?(interaction: ChatInputCommandInteraction, client: Client): Promise<boolean | void>;
+    /**
+     * Lifecycle hook called after any subcommand in this group executes successfully.
+     */
+    protected afterExecute?(interaction: ChatInputCommandInteraction, client: Client): Promise<void>;
+    /**
+     * Lifecycle hook called when any subcommand in this group fails.
+     */
+    protected onError?(interaction: ChatInputCommandInteraction, error: Error, client: Client): Promise<void>;
 }

package/dist/classes/SubcommandGroup.class.js

@@ -1,5 +1,4 @@
 import { SlashCommandBuilder, } from 'discord.js';
-import { safeReply } from '../utils/editAndReply.js';
 /**
  * Abstract base class for Discord slash command groups with subcommands.
  *
@@ -23,36 +22,6 @@ import { safeReply } from '../utils/editAndReply.js';
  * ```
  */
 export class SubcommandGroup {
-    /**
-     * Safely executes a function with error handling and logging.
-     *
-     * Wraps the execution in a try-catch block, logs successful executions,
-     * and automatically handles errors by logging them and sending a user-friendly
-     * error message.
-     *
-     * @param subcommandName - The name of the subcommand
-     * @param scope - The logging scope for this execution
-     * @param interaction - The command interaction
-     * @param fn - The function to execute
-     * @private
-     */
-    async safeExecute(subcommandName, scope, interaction, fn) {
-        try {
-            await fn();
-            this.logger?.log(`${this.name} (${subcommandName}) command executed`, 'info', scope);
-        }
-        catch (err) {
-            this.logger?.log('An Error occured' + err, 'error', scope, true);
-            await this.errorReporter?.reportError(err, `Command: ${subcommandName} in SubcommandGroup: ${this.name}`, {
-                user: interaction.user.tag,
-                userId: interaction.user.id,
-                guild: interaction.guild?.name,
-                guildId: interaction.guildId,
-                channel: interaction.channel?.id,
-            });
-            return await safeReply(interaction, 'An unexpected error occurred.');
-        }
-    }
     /**
      * Executes the appropriate subcommand based on the user's interaction.
      *
@@ -79,8 +48,24 @@ export class SubcommandGroup {
         if (!subcommand) {
             throw new Error(`Unknown subcommand: ${subcommandName}`);
         }
-        const scope = `${subcommand.name}_EXECUTION`;
-        await this.safeExecute(subcommandName, scope, interaction, () => subcommand.execute(interaction, client));
+        if (this.beforeExecute) {
+            const shouldContinue = await this.beforeExecute(interaction, client);
+            if (shouldContinue === false) {
+                return;
+            }
+        }
+        try {
+            await subcommand.execute(interaction, client);
+            if (this.afterExecute) {
+                await this.afterExecute(interaction, client);
+            }
+        }
+        catch (err) {
+            if (this.onError) {
+                await this.onError(interaction, err, client);
+            }
+            throw err;
+        }
     }
     /**
      * Converts the command group to Discord API JSON format for registration.

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export type { Modal, ModalField } from './types/modal.js';
 export type { ButtonType } from './types/button.js';
 export type { ILogger } from './types/logger.js';
 export type { AnySelectMenuInteraction, ButtonHandler, SelectMenuHandler, ComponentConfig } from './types/component.js';
+export type { AutocompleteHandler } from './types/autocomplete.js';
 export { getPermissionsForLevel } from './utils/permissions.js';
 export { embedBuilder, createButton, createButtonsRow, createPaginationButtons, } from './utils/embeds.js';
 export { stringOption, integerOption, booleanOption, userOption, channelOption, roleOption, } from './utils/slashCommandOptions.js';
@@ -18,4 +19,5 @@ export { TIMES_MILISECONDS } from './utils/miliseconds.js';
 export { TToolboxLogger } from './utils/TToolboxLogger.class.js';
 export { ErrorReporter } from './utils/ErrorReporter.js';
 export { ComponentManager } from './utils/ComponentManager.class.js';
+export { AutocompleteManager } from './utils/AutocompleteManager.class.js';
 export { InteractionError } from './classes/InteractionError.class.js';

package/dist/index.js

@@ -15,5 +15,6 @@ export { TIMES_MILISECONDS } from './utils/miliseconds.js';
 export { TToolboxLogger } from './utils/TToolboxLogger.class.js';
 export { ErrorReporter } from './utils/ErrorReporter.js';
 export { ComponentManager } from './utils/ComponentManager.class.js';
+export { AutocompleteManager } from './utils/AutocompleteManager.class.js';
 // Errors
 export { InteractionError } from './classes/InteractionError.class.js';

package/dist/types/autocomplete.d.ts

@@ -0,0 +1,25 @@
+import { AutocompleteInteraction } from "discord.js";
+/**
+ * Handler function for autocomplete interactions.
+ *
+ * @param interaction - The autocomplete interaction
+ * @param focusedValue - The current value the user is typing
+ * @returns Array of choices to display (max 25)
+ *
+ * @example
+ * ```typescript
+ * async (interaction, focusedValue) => {
+ *   const feeds = await getFeeds(interaction.user.id);
+ *   return feeds
+ *     .filter(f => f.name.toLowerCase().includes(focusedValue.toLowerCase()))
+ *     .map(f => ({ name: f.name, value: f.name }));
+ * }
+ * ```
+ */
+export type AutocompleteHandler = (interaction: AutocompleteInteraction, focusedValue: string) => Promise<Array<{
+    name: string;
+    value: string;
+}>> | Array<{
+    name: string;
+    value: string;
+}>;

package/dist/types/autocomplete.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/AutocompleteManager.class.d.ts

@@ -0,0 +1,140 @@
+import { AutocompleteInteraction } from 'discord.js';
+import type { ILogger } from '../types/logger.js';
+import { AutocompleteHandler } from '../types/autocomplete.js';
+/**
+ * Manages autocomplete interactions for slash commands.
+ *
+ * Provides centralized registration and handling of autocomplete options.
+ * Supports per-command, per-option handlers with automatic filtering and
+ * Discord's 25-choice limit.
+ *
+ * @example
+ * ```typescript
+ * const autocompleteManager = new AutocompleteManager(logger);
+ *
+ * // Register autocomplete for a specific command option
+ * autocompleteManager.register('item', 'name', async (interaction, value) => {
+ *   const items = await prisma.item.findMany({
+ *     where: {
+ *       userId: interaction.user.id,
+ *       name: { contains: value },
+ *     },
+ *   });
+ *
+ *   return items.map(item => ({ name: item.name, value: item.name }));
+ * });
+ *
+ * // Handle autocomplete interactions
+ * client.on('interactionCreate', async (interaction) => {
+ *   if (interaction.isAutocomplete()) {
+ *     await autocompleteManager.handle(interaction);
+ *   }
+ * });
+ * ```
+ */
+export declare class AutocompleteManager {
+    private logger?;
+    private handlers;
+    constructor(logger?: ILogger | undefined);
+    /**
+     * Register an autocomplete handler for a command option.
+     *
+     * @param commandName - The name of the slash command
+     * @param optionName - The name of the option with autocomplete enabled
+     * @param handler - The handler function that returns choices
+     *
+     * @example
+     * ```typescript
+     * // Simple static choices
+     * autocompleteManager.register('config', 'setting', async () => {
+     *   return [
+     *     { name: 'Notifications', value: 'notifications' },
+     *     { name: 'Language', value: 'language' },
+     *     { name: 'Theme', value: 'theme' },
+     *   ];
+     * });
+     *
+     * // Dynamic choices from database
+     * autocompleteManager.register('item', 'name', async (interaction, value) => {
+     *   const items = await prisma.item.findMany({
+     *     where: {
+     *       userId: interaction.user.id,
+     *       name: { contains: value },
+     *     },
+     *     take: 25,
+     *   });
+     *
+     *   return items.map(item => ({ name: item.name, value: item.id }));
+     * });
+     *
+     * // With fuzzy search
+     * autocompleteManager.register('user', 'username', async (interaction, value) => {
+     *   const users = await searchUsers(value);
+     *   return users.map(u => ({ name: u.tag, value: u.id }));
+     * });
+     * ```
+     */
+    register(commandName: string, optionName: string, handler: AutocompleteHandler): void;
+    /**
+     * Handle an autocomplete interaction.
+     *
+     * Automatically calls the appropriate handler and responds with choices.
+     * Handles errors gracefully and enforces Discord's 25-choice limit.
+     *
+     * @param interaction - The autocomplete interaction to handle
+     *
+     * @example
+     * ```typescript
+     * client.on('interactionCreate', async (interaction) => {
+     *   if (interaction.isAutocomplete()) {
+     *     await autocompleteManager.handle(interaction);
+     *   }
+     * });
+     * ```
+     */
+    handle(interaction: AutocompleteInteraction): Promise<void>;
+    /**
+     * Unregister an autocomplete handler.
+     *
+     * @param commandName - The command name
+     * @param optionName - The option name
+     * @returns true if the handler was removed, false if it didn't exist
+     */
+    unregister(commandName: string, optionName: string): boolean;
+    /**
+     * Unregister all handlers for a command.
+     *
+     * @param commandName - The command name
+     * @returns true if any handlers were removed
+     */
+    unregisterCommand(commandName: string): boolean;
+    /**
+     * Check if a handler is registered for a command option.
+     *
+     * @param commandName - The command name
+     * @param optionName - The option name
+     * @returns true if a handler exists
+     */
+    has(commandName: string, optionName: string): boolean;
+    /**
+     * Get all registered command names.
+     */
+    getCommands(): string[];
+    /**
+     * Get all registered option names for a command.
+     *
+     * @param commandName - The command name
+     * @returns Array of option names, or empty array if command not found
+     */
+    getOptions(commandName: string): string[];
+    /**
+     * Clear all registered handlers.
+     *
+     * Useful for cleanup or testing.
+     */
+    clear(): void;
+    /**
+     * Get the total number of registered handlers across all commands.
+     */
+    get handlerCount(): number;
+}

package/dist/utils/AutocompleteManager.class.js

@@ -0,0 +1,200 @@
+/**
+ * Manages autocomplete interactions for slash commands.
+ *
+ * Provides centralized registration and handling of autocomplete options.
+ * Supports per-command, per-option handlers with automatic filtering and
+ * Discord's 25-choice limit.
+ *
+ * @example
+ * ```typescript
+ * const autocompleteManager = new AutocompleteManager(logger);
+ *
+ * // Register autocomplete for a specific command option
+ * autocompleteManager.register('item', 'name', async (interaction, value) => {
+ *   const items = await prisma.item.findMany({
+ *     where: {
+ *       userId: interaction.user.id,
+ *       name: { contains: value },
+ *     },
+ *   });
+ *
+ *   return items.map(item => ({ name: item.name, value: item.name }));
+ * });
+ *
+ * // Handle autocomplete interactions
+ * client.on('interactionCreate', async (interaction) => {
+ *   if (interaction.isAutocomplete()) {
+ *     await autocompleteManager.handle(interaction);
+ *   }
+ * });
+ * ```
+ */
+export class AutocompleteManager {
+    constructor(logger) {
+        this.logger = logger;
+        // Map structure: Map<commandName, Map<optionName, handler>>
+        this.handlers = new Map();
+    }
+    /**
+     * Register an autocomplete handler for a command option.
+     *
+     * @param commandName - The name of the slash command
+     * @param optionName - The name of the option with autocomplete enabled
+     * @param handler - The handler function that returns choices
+     *
+     * @example
+     * ```typescript
+     * // Simple static choices
+     * autocompleteManager.register('config', 'setting', async () => {
+     *   return [
+     *     { name: 'Notifications', value: 'notifications' },
+     *     { name: 'Language', value: 'language' },
+     *     { name: 'Theme', value: 'theme' },
+     *   ];
+     * });
+     *
+     * // Dynamic choices from database
+     * autocompleteManager.register('item', 'name', async (interaction, value) => {
+     *   const items = await prisma.item.findMany({
+     *     where: {
+     *       userId: interaction.user.id,
+     *       name: { contains: value },
+     *     },
+     *     take: 25,
+     *   });
+     *
+     *   return items.map(item => ({ name: item.name, value: item.id }));
+     * });
+     *
+     * // With fuzzy search
+     * autocompleteManager.register('user', 'username', async (interaction, value) => {
+     *   const users = await searchUsers(value);
+     *   return users.map(u => ({ name: u.tag, value: u.id }));
+     * });
+     * ```
+     */
+    register(commandName, optionName, handler) {
+        if (!this.handlers.has(commandName)) {
+            this.handlers.set(commandName, new Map());
+        }
+        this.handlers.get(commandName).set(optionName, handler);
+        this.logger?.info(`Registered autocomplete handler: ${commandName}.${optionName}`, 'autocomplete-manager');
+    }
+    /**
+     * Handle an autocomplete interaction.
+     *
+     * Automatically calls the appropriate handler and responds with choices.
+     * Handles errors gracefully and enforces Discord's 25-choice limit.
+     *
+     * @param interaction - The autocomplete interaction to handle
+     *
+     * @example
+     * ```typescript
+     * client.on('interactionCreate', async (interaction) => {
+     *   if (interaction.isAutocomplete()) {
+     *     await autocompleteManager.handle(interaction);
+     *   }
+     * });
+     * ```
+     */
+    async handle(interaction) {
+        const commandHandlers = this.handlers.get(interaction.commandName);
+        if (!commandHandlers) {
+            this.logger?.warn(`No autocomplete handlers for command: ${interaction.commandName}`, 'autocomplete-manager');
+            await interaction.respond([]);
+            return;
+        }
+        const focusedOption = interaction.options.getFocused(true);
+        const handler = commandHandlers.get(focusedOption.name);
+        if (!handler) {
+            this.logger?.warn(`No autocomplete handler for ${interaction.commandName}.${focusedOption.name}`, 'autocomplete-manager');
+            await interaction.respond([]);
+            return;
+        }
+        try {
+            const choices = await handler(interaction, focusedOption.value);
+            // Discord's 25-choice limit
+            const limitedChoices = choices.slice(0, 25);
+            if (choices.length > 25) {
+                this.logger?.warn(`Autocomplete handler for ${interaction.commandName}.${focusedOption.name} returned ${choices.length} choices, truncating to 25`, 'autocomplete-manager');
+            }
+            await interaction.respond(limitedChoices);
+        }
+        catch (err) {
+            this.logger?.error(`Error in autocomplete handler for ${interaction.commandName}.${focusedOption.name}: ${err.message}`, 'autocomplete-manager');
+            // Empty array on error to prevent interaction failure
+            await interaction.respond([]);
+        }
+    }
+    /**
+     * Unregister an autocomplete handler.
+     *
+     * @param commandName - The command name
+     * @param optionName - The option name
+     * @returns true if the handler was removed, false if it didn't exist
+     */
+    unregister(commandName, optionName) {
+        const commandHandlers = this.handlers.get(commandName);
+        if (!commandHandlers)
+            return false;
+        const removed = commandHandlers.delete(optionName);
+        if (commandHandlers.size === 0) {
+            this.handlers.delete(commandName);
+        }
+        return removed;
+    }
+    /**
+     * Unregister all handlers for a command.
+     *
+     * @param commandName - The command name
+     * @returns true if any handlers were removed
+     */
+    unregisterCommand(commandName) {
+        return this.handlers.delete(commandName);
+    }
+    /**
+     * Check if a handler is registered for a command option.
+     *
+     * @param commandName - The command name
+     * @param optionName - The option name
+     * @returns true if a handler exists
+     */
+    has(commandName, optionName) {
+        return this.handlers.get(commandName)?.has(optionName) || false;
+    }
+    /**
+     * Get all registered command names.
+     */
+    getCommands() {
+        return Array.from(this.handlers.keys());
+    }
+    /**
+     * Get all registered option names for a command.
+     *
+     * @param commandName - The command name
+     * @returns Array of option names, or empty array if command not found
+     */
+    getOptions(commandName) {
+        const commandHandlers = this.handlers.get(commandName);
+        return commandHandlers ? Array.from(commandHandlers.keys()) : [];
+    }
+    /**
+     * Clear all registered handlers.
+     *
+     * Useful for cleanup or testing.
+     */
+    clear() {
+        this.handlers.clear();
+        this.logger?.info('Cleared all autocomplete handlers', 'autocomplete-manager');
+    }
+    /**
+     * Get the total number of registered handlers across all commands.
+     */
+    get handlerCount() {
+        let count = 0;
+        for (const commandHandlers of this.handlers.values()) {
+            count += commandHandlers.size;
+        }
+        return count;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@julanzw/ttoolbox-discordjs-framework",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "A Discord.js command framework with built-in handlers and utilities",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",