@julanzw/ttoolbox-discordjs-framework 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export type { PermissionLevel } from './types/permission.js';
 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 { 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';
@@ -16,4 +17,5 @@ export { formatDuration, formatDateToString, formatDateToYYYYMMDDHHMMSS, formatD
 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 { InteractionError } from './classes/InteractionError.class.js';

package/dist/index.js

@@ -14,5 +14,6 @@ export { formatDuration, formatDateToString, formatDateToYYYYMMDDHHMMSS, formatD
 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';
 // Errors
 export { InteractionError } from './classes/InteractionError.class.js';

package/dist/types/component.d.ts

@@ -0,0 +1,22 @@
+import { StringSelectMenuInteraction, ChannelSelectMenuInteraction, RoleSelectMenuInteraction, UserSelectMenuInteraction, MentionableSelectMenuInteraction, ButtonInteraction } from "discord.js";
+/**
+ * Type for all select menu interactions
+ */
+export type AnySelectMenuInteraction = StringSelectMenuInteraction | ChannelSelectMenuInteraction | RoleSelectMenuInteraction | UserSelectMenuInteraction | MentionableSelectMenuInteraction;
+/**
+ * Handler function for button interactions
+ */
+export type ButtonHandler = (interaction: ButtonInteraction) => Promise<void>;
+/**
+ * Handler function for select menu interactions
+ */
+export type SelectMenuHandler = (interaction: AnySelectMenuInteraction) => Promise<void>;
+/**
+ * Configuration for a component handler
+ */
+export interface ComponentConfig {
+    /** Whether this component should be removed after being handled once */
+    ephemeral?: boolean;
+    /** Optional timeout in milliseconds after which the handler is removed */
+    timeout?: number;
+}

package/dist/types/component.js

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

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

@@ -0,0 +1,194 @@
+import { ButtonInteraction, AnySelectMenuInteraction } from 'discord.js';
+import type { ILogger } from '../types/logger.js';
+import { ButtonHandler, ComponentConfig, SelectMenuHandler } from '../types/component.js';
+/**
+ * Manages Discord component interactions (buttons and select menus).
+ *
+ * Provides centralized registration and handling of long living
+ * button clicks and select menu interactions.
+ *
+ * Supports dynamic custom IDs (e.g., "delete-feed:123"),
+ * ephemeral handlers (one-time use), and automatic cleanup.
+ *
+ * @example
+ * ```typescript
+ * const componentManager = new ComponentManager(logger);
+ *
+ * // Register a button handler
+ * componentManager.registerButton('delete-feed', async (interaction) => {
+ *   const feedId = interaction.customId.split(':')[1];
+ *   await deleteFeed(feedId);
+ *   await interaction.reply('Feed deleted!');
+ * });
+ *
+ * // Register a select menu handler
+ * componentManager.registerSelect('choose-feed-type', async (interaction) => {
+ *   const type = interaction.values[0];
+ *   await interaction.reply(`You selected: ${type}`);
+ * });
+ *
+ * // Handle interactions
+ * client.on('interactionCreate', async (interaction) => {
+ *   if (interaction.isButton()) {
+ *     await componentManager.handleButton(interaction);
+ *   }
+ *   if (interaction.isAnySelectMenu()) {
+ *     await componentManager.handleSelect(interaction);
+ *   }
+ * });
+ * ```
+ */
+export declare class ComponentManager {
+    private logger?;
+    private buttonHandlers;
+    private selectHandlers;
+    private timeouts;
+    constructor(logger?: ILogger | undefined);
+    /**
+     * Register a button click handler.
+     *
+     * Supports dynamic custom IDs - if the exact ID isn't found, attempts to match
+     * using the base ID (before the first colon).\
+     * This allows for buttons with dynamic suffixes like "global-delete:123".
+     *
+     * Its recommended to add a prefix like ```global-``` to the id to fully
+     * distingush it from other local component handlers.
+     *
+     * @param customId - The button's custom ID (or base ID for dynamic buttons)
+     * @param handler - Function to call when the button is clicked
+     * @param config - Optional configuration (ephemeral, timeout)
+     *
+     * @example
+     * ```typescript
+     * // Simple button
+     * componentManager.registerButton('global-refresh', async (interaction) => {
+     *   await interaction.reply('Refreshed!');
+     * });
+     *
+     * // Dynamic button (matches "global-delete:123", "global-delete:456", etc.)
+     * componentManager.registerButton('global-delete', async (interaction) => {
+     *   const id = interaction.customId.split(':')[1];
+     *   await deleteItem(id);
+     * });
+     *
+     * // Ephemeral button (one-time use)
+     * componentManager.registerButton('global-confirm', async (interaction) => {
+     *   await processConfirmation();
+     * }, { ephemeral: true });
+     *
+     * // Button with timeout (auto-remove after 5 minutes)
+     * componentManager.registerButton('global-temp-action', async (interaction) => {
+     *   await doTempAction();
+     * }, { timeout: 5 * 60 * 1000 });
+     * ```
+     */
+    registerButton(customId: string, handler: ButtonHandler, config?: ComponentConfig): void;
+    /**
+     * Register a select menu handler.
+     *
+     * Supports dynamic custom IDs - if the exact ID isn't found, attempts to match
+     * using the base ID (before the first colon).
+     *
+     * Its recommended to add a prefix like ```global-``` to the id to fully
+     * distingush it from other local component handlers.
+     *
+     * @param customId - The select menu's custom ID (or base ID for dynamic menus)
+     * @param handler - Function to call when a selection is made
+     * @param config - Optional configuration (ephemeral, timeout)
+     *
+     * @example
+     * ```typescript
+     * // String select menu
+     * componentManager.registerSelect('global-choose-type', async (interaction) => {
+     *   const selected = interaction.values[0];
+     *   await interaction.reply(`You chose: ${selected}`);
+     * });
+     *
+     * // Dynamic select menu
+     * componentManager.registerSelect('global-choose-item', async (interaction) => {
+     *   const itemId = interaction.customId.split(':')[1];
+     *   const selected = interaction.values;
+     *   await processSelection(itemId, selected);
+     * });
+     * ```
+     */
+    registerSelect(customId: string, handler: SelectMenuHandler, config?: ComponentConfig): void;
+    /**
+     * Handle a button interaction.
+     *
+     * Automatically matches dynamic IDs and removes ephemeral handlers after use.
+     *
+     * @param interaction - The button interaction to handle
+     * @throws {Error} If no handler is found for the button
+     */
+    handleButton(interaction: ButtonInteraction): Promise<void>;
+    /**
+     * Handle a select menu interaction.
+     *
+     * Automatically matches dynamic IDs and removes ephemeral handlers after use.
+     *
+     * @param interaction - The select menu interaction to handle
+     * @throws {Error} If no handler is found for the select menu
+     */
+    handleSelect(interaction: AnySelectMenuInteraction): Promise<void>;
+    /**
+     * Find a handler by custom ID, supporting dynamic IDs.
+     *
+     * First tries exact match, then tries base ID (before colon).
+     */
+    private findHandler;
+    /**
+     * Set up automatic removal timeout for a handler.
+     */
+    private setupTimeout;
+    /**
+     * Unregister a button handler.
+     *
+     * @param customId - The button's custom ID
+     * @returns true if the handler was removed, false if it didn't exist
+     */
+    unregisterButton(customId: string): boolean;
+    /**
+     * Unregister a select menu handler.
+     *
+     * @param customId - The select menu's custom ID
+     * @returns true if the handler was removed, false if it didn't exist
+     */
+    unregisterSelect(customId: string): boolean;
+    /**
+     * Check if a button handler is registered.
+     *
+     * @param customId - The button's custom ID
+     * @returns true if a handler exists (exact or base ID match)
+     */
+    hasButton(customId: string): boolean;
+    /**
+     * Check if a select menu handler is registered.
+     *
+     * @param customId - The select menu's custom ID
+     * @returns true if a handler exists (exact or base ID match)
+     */
+    hasSelect(customId: string): boolean;
+    /**
+     * Clear all registered handlers.
+     *
+     * Useful for cleanup during bot shutdown or testing.
+     */
+    clear(): void;
+    /**
+     * Get the total number of registered button handlers.
+     */
+    get buttonCount(): number;
+    /**
+     * Get the total number of registered select menu handlers.
+     */
+    get selectCount(): number;
+    /**
+     * Get all registered button IDs.
+     */
+    getButtonIds(): string[];
+    /**
+     * Get all registered select menu IDs.
+     */
+    getSelectIds(): string[];
+}

package/dist/utils/ComponentManager.class.js

@@ -0,0 +1,318 @@
+/**
+ * Manages Discord component interactions (buttons and select menus).
+ *
+ * Provides centralized registration and handling of long living
+ * button clicks and select menu interactions.
+ *
+ * Supports dynamic custom IDs (e.g., "delete-feed:123"),
+ * ephemeral handlers (one-time use), and automatic cleanup.
+ *
+ * @example
+ * ```typescript
+ * const componentManager = new ComponentManager(logger);
+ *
+ * // Register a button handler
+ * componentManager.registerButton('delete-feed', async (interaction) => {
+ *   const feedId = interaction.customId.split(':')[1];
+ *   await deleteFeed(feedId);
+ *   await interaction.reply('Feed deleted!');
+ * });
+ *
+ * // Register a select menu handler
+ * componentManager.registerSelect('choose-feed-type', async (interaction) => {
+ *   const type = interaction.values[0];
+ *   await interaction.reply(`You selected: ${type}`);
+ * });
+ *
+ * // Handle interactions
+ * client.on('interactionCreate', async (interaction) => {
+ *   if (interaction.isButton()) {
+ *     await componentManager.handleButton(interaction);
+ *   }
+ *   if (interaction.isAnySelectMenu()) {
+ *     await componentManager.handleSelect(interaction);
+ *   }
+ * });
+ * ```
+ */
+export class ComponentManager {
+    constructor(logger) {
+        this.logger = logger;
+        this.buttonHandlers = new Map();
+        this.selectHandlers = new Map();
+        this.timeouts = new Map();
+    }
+    /**
+     * Register a button click handler.
+     *
+     * Supports dynamic custom IDs - if the exact ID isn't found, attempts to match
+     * using the base ID (before the first colon).\
+     * This allows for buttons with dynamic suffixes like "global-delete:123".
+     *
+     * Its recommended to add a prefix like ```global-``` to the id to fully
+     * distingush it from other local component handlers.
+     *
+     * @param customId - The button's custom ID (or base ID for dynamic buttons)
+     * @param handler - Function to call when the button is clicked
+     * @param config - Optional configuration (ephemeral, timeout)
+     *
+     * @example
+     * ```typescript
+     * // Simple button
+     * componentManager.registerButton('global-refresh', async (interaction) => {
+     *   await interaction.reply('Refreshed!');
+     * });
+     *
+     * // Dynamic button (matches "global-delete:123", "global-delete:456", etc.)
+     * componentManager.registerButton('global-delete', async (interaction) => {
+     *   const id = interaction.customId.split(':')[1];
+     *   await deleteItem(id);
+     * });
+     *
+     * // Ephemeral button (one-time use)
+     * componentManager.registerButton('global-confirm', async (interaction) => {
+     *   await processConfirmation();
+     * }, { ephemeral: true });
+     *
+     * // Button with timeout (auto-remove after 5 minutes)
+     * componentManager.registerButton('global-temp-action', async (interaction) => {
+     *   await doTempAction();
+     * }, { timeout: 5 * 60 * 1000 });
+     * ```
+     */
+    registerButton(customId, handler, config = {}) {
+        this.buttonHandlers.set(customId, { handler, config });
+        // Set up auto-removal timeout if specified
+        if (config.timeout) {
+            this.setupTimeout('button', customId, config.timeout);
+        }
+        this.logger?.info(`Registered button handler: ${customId}${config.ephemeral ? ' (ephemeral)' : ''}${config.timeout ? ` (timeout: ${config.timeout}ms)` : ''}`, 'component-manager');
+    }
+    /**
+     * Register a select menu handler.
+     *
+     * Supports dynamic custom IDs - if the exact ID isn't found, attempts to match
+     * using the base ID (before the first colon).
+     *
+     * Its recommended to add a prefix like ```global-``` to the id to fully
+     * distingush it from other local component handlers.
+     *
+     * @param customId - The select menu's custom ID (or base ID for dynamic menus)
+     * @param handler - Function to call when a selection is made
+     * @param config - Optional configuration (ephemeral, timeout)
+     *
+     * @example
+     * ```typescript
+     * // String select menu
+     * componentManager.registerSelect('global-choose-type', async (interaction) => {
+     *   const selected = interaction.values[0];
+     *   await interaction.reply(`You chose: ${selected}`);
+     * });
+     *
+     * // Dynamic select menu
+     * componentManager.registerSelect('global-choose-item', async (interaction) => {
+     *   const itemId = interaction.customId.split(':')[1];
+     *   const selected = interaction.values;
+     *   await processSelection(itemId, selected);
+     * });
+     * ```
+     */
+    registerSelect(customId, handler, config = {}) {
+        this.selectHandlers.set(customId, { handler, config });
+        if (config.timeout) {
+            this.setupTimeout('select', customId, config.timeout);
+        }
+        this.logger?.info(`Registered select menu handler: ${customId}${config.ephemeral ? ' (ephemeral)' : ''}${config.timeout ? ` (timeout: ${config.timeout}ms)` : ''}`, 'component-manager');
+    }
+    /**
+     * Handle a button interaction.
+     *
+     * Automatically matches dynamic IDs and removes ephemeral handlers after use.
+     *
+     * @param interaction - The button interaction to handle
+     * @throws {Error} If no handler is found for the button
+     */
+    async handleButton(interaction) {
+        if (interaction.replied || interaction.deferred) {
+            this.logger?.warn(`Button ${interaction.customId} already handled, skipping`, 'component-manager');
+            return;
+        }
+        const entry = this.findHandler(this.buttonHandlers, interaction.customId);
+        if (!entry) {
+            throw new Error(`No handler registered for button: ${interaction.customId}`);
+        }
+        const { handler, config, matchedId } = entry;
+        try {
+            await handler(interaction);
+            // Remove ephemeral handlers after use
+            if (config.ephemeral) {
+                this.unregisterButton(matchedId);
+                this.logger?.info(`Removed ephemeral button handler: ${matchedId}`, 'component-manager');
+            }
+        }
+        catch (err) {
+            this.logger?.error(`Error handling button ${interaction.customId}: ${err.message}`, 'component-manager');
+            throw err;
+        }
+    }
+    /**
+     * Handle a select menu interaction.
+     *
+     * Automatically matches dynamic IDs and removes ephemeral handlers after use.
+     *
+     * @param interaction - The select menu interaction to handle
+     * @throws {Error} If no handler is found for the select menu
+     */
+    async handleSelect(interaction) {
+        if (interaction.replied || interaction.deferred) {
+            this.logger?.warn(`Select menu ${interaction.customId} already handled, skipping`, 'component-manager');
+            return;
+        }
+        const entry = this.findHandler(this.selectHandlers, interaction.customId);
+        if (!entry) {
+            throw new Error(`No handler registered for select menu: ${interaction.customId}`);
+        }
+        const { handler, config, matchedId } = entry;
+        try {
+            await handler(interaction);
+            if (config.ephemeral) {
+                this.unregisterSelect(matchedId);
+                this.logger?.info(`Removed ephemeral select menu handler: ${matchedId}`, 'component-manager');
+            }
+        }
+        catch (err) {
+            this.logger?.error(`Error handling select menu ${interaction.customId}: ${err.message}`, 'component-manager');
+            throw err;
+        }
+    }
+    /**
+     * Find a handler by custom ID, supporting dynamic IDs.
+     *
+     * First tries exact match, then tries base ID (before colon).
+     */
+    findHandler(map, customId) {
+        // Try exact match first
+        const exact = map.get(customId);
+        if (exact) {
+            return { ...exact, matchedId: customId };
+        }
+        // Try base ID (before colon) for dynamic IDs
+        const baseId = customId.split(':')[0];
+        const base = map.get(baseId);
+        if (base) {
+            return { ...base, matchedId: baseId };
+        }
+        return null;
+    }
+    /**
+     * Set up automatic removal timeout for a handler.
+     */
+    setupTimeout(type, customId, timeout) {
+        // Clear existing timeout if any
+        const existingTimeout = this.timeouts.get(`${type}:${customId}`);
+        if (existingTimeout) {
+            clearTimeout(existingTimeout);
+        }
+        // Set new timeout
+        const timeoutId = setTimeout(() => {
+            if (type === 'button') {
+                this.unregisterButton(customId);
+            }
+            else {
+                this.unregisterSelect(customId);
+            }
+            this.logger?.info(`Auto-removed ${type} handler after timeout: ${customId}`, 'component-manager');
+        }, timeout);
+        this.timeouts.set(`${type}:${customId}`, timeoutId);
+    }
+    /**
+     * Unregister a button handler.
+     *
+     * @param customId - The button's custom ID
+     * @returns true if the handler was removed, false if it didn't exist
+     */
+    unregisterButton(customId) {
+        const removed = this.buttonHandlers.delete(customId);
+        // Clear timeout if exists
+        const timeoutId = this.timeouts.get(`button:${customId}`);
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+            this.timeouts.delete(`button:${customId}`);
+        }
+        return removed;
+    }
+    /**
+     * Unregister a select menu handler.
+     *
+     * @param customId - The select menu's custom ID
+     * @returns true if the handler was removed, false if it didn't exist
+     */
+    unregisterSelect(customId) {
+        const removed = this.selectHandlers.delete(customId);
+        const timeoutId = this.timeouts.get(`select:${customId}`);
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+            this.timeouts.delete(`select:${customId}`);
+        }
+        return removed;
+    }
+    /**
+     * Check if a button handler is registered.
+     *
+     * @param customId - The button's custom ID
+     * @returns true if a handler exists (exact or base ID match)
+     */
+    hasButton(customId) {
+        return this.buttonHandlers.has(customId) ||
+            this.buttonHandlers.has(customId.split(':')[0]);
+    }
+    /**
+     * Check if a select menu handler is registered.
+     *
+     * @param customId - The select menu's custom ID
+     * @returns true if a handler exists (exact or base ID match)
+     */
+    hasSelect(customId) {
+        return this.selectHandlers.has(customId) ||
+            this.selectHandlers.has(customId.split(':')[0]);
+    }
+    /**
+     * Clear all registered handlers.
+     *
+     * Useful for cleanup during bot shutdown or testing.
+     */
+    clear() {
+        this.buttonHandlers.clear();
+        this.selectHandlers.clear();
+        // Clear all timeouts
+        for (const timeoutId of this.timeouts.values()) {
+            clearTimeout(timeoutId);
+        }
+        this.timeouts.clear();
+        this.logger?.info('Cleared all component handlers', 'component-manager');
+    }
+    /**
+     * Get the total number of registered button handlers.
+     */
+    get buttonCount() {
+        return this.buttonHandlers.size;
+    }
+    /**
+     * Get the total number of registered select menu handlers.
+     */
+    get selectCount() {
+        return this.selectHandlers.size;
+    }
+    /**
+     * Get all registered button IDs.
+     */
+    getButtonIds() {
+        return Array.from(this.buttonHandlers.keys());
+    }
+    /**
+     * Get all registered select menu IDs.
+     */
+    getSelectIds() {
+        return Array.from(this.selectHandlers.keys());
+    }
+}

package/package.json

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