meocord 3.0.0 → 3.2.0

package/dist/cjs/_shared/controller.decorator-MUHA_A3z.cjs

@@ -0,0 +1,529 @@
+'use strict';
+
+require('reflect-metadata');
+var inversify = require('inversify');
+var enum_index = require('../enum/index.cjs');
+var metadataKey_enum = require('./metadata-key.enum-BzzvGUId.cjs');
+var discord_js = require('discord.js');
+
+/**
+ * The discord.js class each command type is handled by.
+ *
+ * One table rather than a chain of `isButton() || isStringSelectMenu() || ...`: the
+ * registration guard in `@Command`, the dispatcher, and the type-level
+ * `CommandInteractionType` all have to agree on what a command type accepts, and a
+ * chain repeated in three files drifts the moment a fifth select menu appears. Adding
+ * a `CommandType` member without an entry here is a compile error, not a silent
+ * fall-through to "Command not found!".
+ */ const INTERACTION_MATCHERS = {
+    [enum_index.CommandType.SLASH]: (interaction)=>interaction instanceof discord_js.ChatInputCommandInteraction,
+    [enum_index.CommandType.CONTEXT_MENU]: (interaction)=>interaction instanceof discord_js.ContextMenuCommandInteraction,
+    [enum_index.CommandType.PRIMARY_ENTRY_POINT]: (interaction)=>interaction instanceof discord_js.PrimaryEntryPointCommandInteraction,
+    [enum_index.CommandType.BUTTON]: (interaction)=>interaction instanceof discord_js.ButtonInteraction,
+    [enum_index.CommandType.SELECT_MENU]: (interaction)=>interaction instanceof discord_js.StringSelectMenuInteraction,
+    [enum_index.CommandType.USER_SELECT_MENU]: (interaction)=>interaction instanceof discord_js.UserSelectMenuInteraction,
+    [enum_index.CommandType.ROLE_SELECT_MENU]: (interaction)=>interaction instanceof discord_js.RoleSelectMenuInteraction,
+    [enum_index.CommandType.MENTIONABLE_SELECT_MENU]: (interaction)=>interaction instanceof discord_js.MentionableSelectMenuInteraction,
+    [enum_index.CommandType.CHANNEL_SELECT_MENU]: (interaction)=>interaction instanceof discord_js.ChannelSelectMenuInteraction,
+    [enum_index.CommandType.MODAL_SUBMIT]: (interaction)=>interaction instanceof discord_js.ModalSubmitInteraction
+};
+/** Command types Discord identifies by a registered name rather than by a customId. */ const NAME_ROUTED_TYPES = new Set([
+    enum_index.CommandType.SLASH,
+    enum_index.CommandType.CONTEXT_MENU,
+    enum_index.CommandType.PRIMARY_ENTRY_POINT
+]);
+/**
+ * Whether an interaction is the kind the given command type handles.
+ *
+ * @param type - The command type declared on `@Command`.
+ * @param interaction - The interaction being dispatched.
+ */ function matchesCommandType(type, interaction) {
+    const matches = INTERACTION_MATCHERS[type];
+    return matches !== undefined && matches(interaction);
+}
+/**
+ * Whether the command type is routed by matching a customId pattern.
+ *
+ * Components carry an application-defined customId and so are matched by pattern;
+ * commands carry a name Discord itself registered and are matched exactly.
+ *
+ * @param type - The command type declared on `@Command`.
+ */ function isCustomIdRouted(type) {
+    return !NAME_ROUTED_TYPES.has(type);
+}
+/**
+ * Whether an interaction carries a customId, and so can be routed by pattern.
+ *
+ * @param interaction - The interaction being dispatched.
+ */ function hasCustomId(interaction) {
+    return interaction instanceof discord_js.MessageComponentInteraction || interaction instanceof discord_js.ModalSubmitInteraction;
+}
+/** Separates a command from its subcommand group and subcommand in a route key. */ const COMMAND_PATH_SEPARATOR = ' ';
+/**
+ * The route keys a chat input interaction can be handled by, most specific first.
+ *
+ * Discord sends `/settings notify email` as one interaction named `settings`, so
+ * routing on `commandName` alone gives every subcommand of a command the same handler
+ * — and the framework would run whichever one was declared first. The full path is
+ * tried before the bare name so a command can either split its subcommands across
+ * methods or keep handling them in one, but never both by accident.
+ *
+ * A group is never dropped on the way down: `settings notify email` does not fall back
+ * to `settings email`, because a second group could declare its own `email` and the
+ * two would be indistinguishable.
+ *
+ * @param interaction - The chat input or autocomplete interaction being dispatched.
+ * @returns The keys to look up, most specific first.
+ */ function resolveCommandPaths(interaction) {
+    const { commandName } = interaction;
+    const options = interaction.options;
+    // Guarded rather than called directly: `options` is a stub on a hand-built test
+    // double, and an interaction whose command has no subcommands still has to route.
+    const group = typeof options?.getSubcommandGroup === 'function' ? options.getSubcommandGroup(false) : null;
+    const sub = typeof options?.getSubcommand === 'function' ? options.getSubcommand(false) : null;
+    const path = [
+        commandName,
+        group,
+        sub
+    ].filter((part)=>Boolean(part));
+    const full = path.join(COMMAND_PATH_SEPARATOR);
+    return full === commandName ? [
+        commandName
+    ] : [
+        full,
+        commandName
+    ];
+}
+/** Options that only wrap other options; their values live one level down. */ const NESTING_OPTION_TYPES = new Set([
+    discord_js.ApplicationCommandOptionType.Subcommand,
+    discord_js.ApplicationCommandOptionType.SubcommandGroup
+]);
+/**
+ * The value a handler should receive for one option.
+ *
+ * Discord sends entity options as a snowflake plus a `resolved` payload, and discord.js
+ * puts that payload on the option as `user`/`role`/`channel`/`attachment`. Passing
+ * `value` alone would hand the handler a bare id string for `@user`, forcing every
+ * handler to re-fetch what the gateway already delivered.
+ */ function resolveOptionValue(option) {
+    return option.attachment ?? option.channel ?? option.role ?? option.user ?? option.member ?? option.value;
+}
+/**
+ * Flattens a chat input interaction's options into the params record handlers receive.
+ *
+ * Subcommand and subcommand-group options are containers, not values — for
+ * `/settings notify email true` the top level holds only `notify`. Recursing past them
+ * means a subcommand handler sees `{ email: true }`, the same shape a flat command's
+ * handler sees.
+ *
+ * @param interaction - The chat input or autocomplete interaction being dispatched.
+ * @returns Each supplied option keyed by name, with entity options resolved.
+ */ function resolveOptionParams(interaction) {
+    const data = interaction.options?.data;
+    if (!Array.isArray(data)) return {};
+    const params = {};
+    const walk = (options)=>{
+        for (const option of options){
+            if (NESTING_OPTION_TYPES.has(option.type)) {
+                walk(option.options ?? []);
+                continue;
+            }
+            params[option.name] = resolveOptionValue(option);
+        }
+    };
+    walk(data);
+    return params;
+}
+/**
+ * The name of the option the user is currently typing, or `undefined`.
+ *
+ * `getFocused` throws when nothing is focused rather than returning null, and it is
+ * absent altogether on a hand-built test double. Neither is worth failing a dispatch
+ * over — an autocomplete with no focused option simply matches no option-specific
+ * handler.
+ *
+ * @param interaction - The autocomplete interaction being dispatched.
+ */ function focusedOptionName(interaction) {
+    if (typeof interaction.options?.getFocused !== 'function') return undefined;
+    try {
+        return interaction.options.getFocused(true)?.name;
+    } catch  {
+        return undefined;
+    }
+}
+/**
+ * Identifies an interaction in a log line, by whichever field would have routed it.
+ *
+ * @param interaction - The interaction that matched no handler.
+ */ function describeInteraction(interaction) {
+    // Captured before the narrowing below: the guards cover every member of the union,
+    // so by the fallback `interaction` is `never` and nothing can be read off it.
+    const { type } = interaction;
+    if (interaction.isAutocomplete()) {
+        const path = resolveCommandPaths(interaction)[0];
+        const focused = focusedOptionName(interaction);
+        return focused === undefined ? `autocomplete for "${path}"` : `autocomplete for "${path}" option "${focused}"`;
+    }
+    if (interaction.isChatInputCommand()) {
+        return `command "${resolveCommandPaths(interaction)[0]}"`;
+    }
+    if (interaction.isContextMenuCommand() || interaction.isPrimaryEntryPointCommand()) {
+        return `command "${interaction.commandName}"`;
+    }
+    if (hasCustomId(interaction)) {
+        return `customId "${interaction.customId}"`;
+    }
+    return `interaction type ${type}`;
+}
+
+const COMMAND_METADATA_KEY = Symbol('commands');
+const MESSAGE_HANDLER_METADATA_KEY = Symbol('message_handlers');
+const REACTION_HANDLER_METADATA_KEY = Symbol('reaction_handlers');
+const AUTOCOMPLETE_METADATA_KEY = Symbol('autocomplete_handlers');
+/**
+ * Decorator to register message handlers in the controller.
+ *
+ * @param keyword - An optional keyword to filter messages this handler should respond to.
+ *
+ * @example
+ * ```typescript
+ * @MessageHandler('hello')
+ * async handleHelloMessage(message: Message) {
+ *   await message.reply('Hello! How can I help you?');
+ * }
+ *
+ * @MessageHandler()
+ * async handleAnyMessage(message: Message) {
+ *   console.log(`Received a message: ${message.content}`);
+ * }
+ * ```
+ */ function MessageHandler(keyword) {
+    return function(target, propertyKey, _descriptor) {
+        const handlers = Reflect.getMetadata(MESSAGE_HANDLER_METADATA_KEY, target) || [];
+        handlers.push({
+            keyword,
+            method: propertyKey.toString()
+        });
+        Reflect.defineMetadata(MESSAGE_HANDLER_METADATA_KEY, handlers, target);
+    };
+}
+/**
+ * Decorator to register reaction handlers in the controller.
+ *
+ * @param emoji - Optional emoji name to filter reactions this handler should respond to.
+ *
+ * @example
+ * ```typescript
+ * @ReactionHandler('👍')
+ * async handleThumbsUpReaction(reaction: MessageReaction, { user }: ReactionHandlerOptions) {
+ *   console.log(`User ${user.username} reacted with 👍`);
+ * }
+ *
+ * @ReactionHandler()
+ * async handleAnyReaction(reaction: MessageReaction, { user }: ReactionHandlerOptions) {
+ *   console.log(`User ${user.username} reacted with ${reaction.emoji.name}`);
+ * }
+ * ```
+ */ function ReactionHandler(emoji) {
+    return function(target, propertyKey, _descriptor) {
+        const handlers = Reflect.getMetadata(REACTION_HANDLER_METADATA_KEY, target) || [];
+        handlers.push({
+            emoji,
+            method: propertyKey.toString()
+        });
+        Reflect.defineMetadata(REACTION_HANDLER_METADATA_KEY, handlers, target);
+    };
+}
+/**
+ * Retrieves reaction handlers metadata from a given controller.
+ *
+ * @param controller - The controller class instance.
+ * @returns An array of reaction handler metadata objects.
+ */ function getReactionHandlers(controller) {
+    return Reflect.getMetadata(REACTION_HANDLER_METADATA_KEY, controller) || [];
+}
+/**
+ * Retrieves message handlers metadata from a given controller.
+ *
+ * @param controller - The controller class instance.
+ * @returns An array of message handler method names.
+ */ function getMessageHandlers(controller) {
+    return Reflect.getMetadata(MESSAGE_HANDLER_METADATA_KEY, controller) || [];
+}
+const PLACEHOLDER_PATTERN = /\{(\w+)}/g;
+/** The character a parameter will not cross, so one pattern segment maps to one value. */ const PARAM_SEPARATOR = '/';
+/** Escapes a literal stretch of a pattern so only placeholders stay meaningful. */ const escapeLiteral = (literal)=>literal.replace(/[/\\^$*+?.()|[\]{}]/g, '\\$&');
+/**
+ * Helper function to create regex and parameter mappings from a pattern string.
+ *
+ * A `{name}` matches anything up to the next `/`, the same rule Express and Rails use
+ * for a path segment. That is what lets a value the application does not control — a
+ * uuid, an opaque vendor id, a slug — be captured whole without the author annotating
+ * anything, since a hyphen inside it is data rather than structure.
+ *
+ * It also keeps neighbouring patterns apart: `profile/{uuid}` and `profile/{uuid}/{id}`
+ * cannot both match one id, because a parameter cannot swallow the separator between
+ * them. Patterns separated by `-` instead have no such boundary, so a pair like
+ * `profile-{uuid}` and `profile-{uuid}-{id}` is ambiguous — {@link findAmbiguousRoutes}
+ * reports those at registration.
+ *
+ * @param pattern - The pattern string to parse.
+ * @returns The regex, the parameter names, and how specific the pattern is.
+ */ function createRegexFromPattern(pattern) {
+    const params = [];
+    let regexPattern = '';
+    let cursor = 0;
+    let literalLength = 0;
+    PLACEHOLDER_PATTERN.lastIndex = 0;
+    let match;
+    while((match = PLACEHOLDER_PATTERN.exec(pattern)) !== null){
+        const [placeholder, param] = match;
+        const literal = pattern.slice(cursor, match.index);
+        const after = pattern[match.index + placeholder.length];
+        // A parameter has to own its segment. Sharing one with a literal leaves no
+        // boundary a sibling pattern can be told apart by, and the resulting overlap has
+        // no correct reading -- `profile-{uuid}` and `profile-{uuid}-{id}` both take
+        // `profile-a-b`. Registration is the last point where that is still fixable.
+        if (literal !== '' && !literal.endsWith(PARAM_SEPARATOR) || after !== undefined && after !== PARAM_SEPARATOR) {
+            throw new Error(`Invalid pattern "${pattern}": {${param}} must occupy a whole segment, so it has to be ` + `preceded and followed by "${PARAM_SEPARATOR}" or by the ends of the pattern. ` + `Write "a${PARAM_SEPARATOR}{${param}}" rather than "a-{${param}}".`);
+        }
+        literalLength += literal.length;
+        regexPattern += escapeLiteral(literal);
+        regexPattern += `(?<${param}>[^${PARAM_SEPARATOR}]+)`;
+        params.push(param);
+        cursor = match.index + placeholder.length;
+    }
+    const trailing = pattern.slice(cursor);
+    literalLength += trailing.length;
+    regexPattern += escapeLiteral(trailing);
+    const regex = new RegExp(`^${regexPattern}$`);
+    // Literal text is the signal: a pattern spelling out more of the id describes it
+    // more exactly than one leaving it to a parameter. Fewer parameters breaks a tie
+    // between equal-length patterns, so the ranking is total and never falls back to
+    // declaration order.
+    const specificity = literalLength * 1000 - params.length;
+    return {
+        regex,
+        params,
+        specificity
+    };
+}
+/**
+ * Decorator to register command methods in a controller.
+ *
+ * @param commandName - What the command is addressed by. Commands registered with
+ *   Discord use their name, and a subcommand its full path — `settings notify email`,
+ *   parts separated by a space, the way Discord displays it. Components use a customId
+ *   pattern, where `{name}` captures one `/`-separated segment.
+ * @param builderOrType - A command builder class, or a `CommandType` for a handler that
+ *   registers nothing of its own: every component, and every subcommand of a command
+ *   whose builder already describes it.
+ *
+ * @example
+ * ```typescript
+ * @Command('help', CommandType.SLASH)
+ * public async handleHelp(interaction: ChatInputCommandInteraction) {
+ *   await interaction.reply('This is the help command!')
+ * }
+ *
+ * @Command('settings notify email', CommandType.SLASH)
+ * public async handleNotifyEmail(interaction: ChatInputCommandInteraction, { enabled }) {
+ *   await interaction.reply(`Email notifications ${enabled ? 'on' : 'off'}`)
+ * }
+ *
+ * @Command('stats/{id}', CommandType.BUTTON)
+ * public async handleStats(interaction: ButtonInteraction, { id }) {
+ *   await interaction.reply(`Fetching stats for ID: ${id}`);
+ * }
+ *
+ * @Command('assign/{taskId}', CommandType.USER_SELECT_MENU)
+ * public async handleAssign(interaction: UserSelectMenuInteraction, { taskId }) {
+ *   await interaction.reply(`Assigned ${interaction.users.size} user(s) to ${taskId}`)
+ * }
+ * ```
+ */ function Command(commandName, builderOrType) {
+    return function(target, propertyKey, _descriptor) {
+        const originalMethod = _descriptor.value;
+        if (!originalMethod) {
+            throw new Error(`Missing implementation for method ${propertyKey}`);
+        }
+        // Wrap original method for interaction type validation
+        _descriptor.value = function(interaction, params) {
+            if (!matchesCommandType(commandType, interaction)) {
+                throw new Error(`Invalid interaction type passed to @Command for method: ${propertyKey}`);
+            }
+            return originalMethod.apply(this, [
+                interaction,
+                params
+            ]);
+        };
+        // Retrieve existing metadata or initialize it
+        const commands = Reflect.getMetadata(COMMAND_METADATA_KEY, target) || {};
+        let builderInstance;
+        let commandType;
+        let regex;
+        let dynamicParams = [];
+        let specificity;
+        // Determine command type and builder
+        if (typeof builderOrType === 'function') {
+            const builderObj = new builderOrType();
+            builderInstance = builderObj.build(commandName);
+            commandType = Reflect.getMetadata(metadataKey_enum.MetadataKey.CommandType, builderOrType);
+            if (!(commandType in enum_index.CommandType)) {
+                throw new Error(`Metadata for 'commandType' is missing on builder ${builderOrType.name}`);
+            }
+        } else {
+            commandType = builderOrType;
+        }
+        if (isCustomIdRouted(commandType)) {
+            const { regex: generatedRegex, params, specificity: patternSpecificity } = createRegexFromPattern(commandName);
+            regex = generatedRegex;
+            dynamicParams = params;
+            specificity = patternSpecificity;
+        }
+        // Ensure commandName supports multiple entries
+        if (!commands[commandName]) {
+            commands[commandName] = [];
+        }
+        commands[commandName].push({
+            methodName: propertyKey,
+            builder: builderInstance,
+            type: commandType,
+            regex,
+            dynamicParams,
+            specificity
+        });
+        Reflect.defineMetadata(COMMAND_METADATA_KEY, commands, target);
+    };
+}
+/**
+ * Retrieves the command map for a given controller.
+ *
+ * @param controller - The controller class instance.
+ * @returns A record containing command metadata indexed by command names.
+ */ function getCommandMap(controller) {
+    return Reflect.getMetadata(COMMAND_METADATA_KEY, controller);
+}
+/**
+ * Decorator to register an autocomplete handler for a chat input command's option.
+ *
+ * Autocomplete is a separate interaction from the command it belongs to, and Discord
+ * sends it while the user is still typing. It is not a `@Command`: nothing is
+ * registered for it — the option's own `setAutocomplete(true)` is what turns it on —
+ * and it is answered with `interaction.respond()` rather than a reply. Leaving it
+ * unhandled is not silent to the user: the client shows a loading state until the
+ * three-second window closes.
+ *
+ * @param commandPath - The command to complete, e.g. `settings` or `settings notify email`
+ *   for a subcommand. Parts are separated by a single space, as Discord displays them.
+ * @param optionName - The option to complete. Omit to handle every option of the command,
+ *   branching on `interaction.options.getFocused(true)`.
+ *
+ * @example
+ * ```typescript
+ * @Autocomplete('search', 'query')
+ * async completeQuery(interaction: AutocompleteInteraction) {
+ *   const { value } = interaction.options.getFocused(true)
+ *   await interaction.respond(this.search(value).map(name => ({ name, value: name })))
+ * }
+ * ```
+ */ function Autocomplete(commandPath, optionName) {
+    return function(target, propertyKey, _descriptor) {
+        const handlers = Reflect.getMetadata(AUTOCOMPLETE_METADATA_KEY, target) || [];
+        handlers.push({
+            commandPath,
+            optionName,
+            methodName: propertyKey.toString()
+        });
+        Reflect.defineMetadata(AUTOCOMPLETE_METADATA_KEY, handlers, target);
+    };
+}
+/**
+ * Retrieves autocomplete handler metadata from a given controller.
+ *
+ * Handlers naming an option come first, so a command-wide handler acts as the fallback
+ * for options no specific handler claimed rather than shadowing them by declaration order.
+ *
+ * @param controller - The controller class instance.
+ * @returns The registered autocomplete handlers, most specific first.
+ */ function getAutocompleteHandlers(controller) {
+    const handlers = Reflect.getMetadata(AUTOCOMPLETE_METADATA_KEY, controller) || [];
+    return [
+        ...handlers
+    ].sort((a, b)=>Number(Boolean(b.optionName)) - Number(Boolean(a.optionName)));
+}
+/**
+ * Decorator to mark a class as a controller that can later be registered to the App class `(app.ts)` using the `@MeoCord` decorator.
+ *
+ * @example
+ * ```typescript
+ * @Controller()
+ * export class PingSlashController {
+ *   constructor(private pingService: PingService) {}
+ *
+ *   @Command('ping', PingCommandBuilder)
+ *   async ping(interaction: ChatInputCommandInteraction) {
+ *     const response = await this.pingService.handlePing()
+ *     await interaction.reply(response)
+ *   }
+ * }
+ * ```
+ */ function Controller() {
+    return function(target) {
+        if (!Reflect.hasMetadata(metadataKey_enum.MetadataKey.Injectable, target)) {
+            inversify.injectable()(target);
+        }
+    };
+}
+/**
+ * Finds pattern pairs that can both match one customId.
+ *
+ * Patterns of different segment counts are disjoint, because a parameter cannot cross
+ * `/`. Within the same count, two patterns overlap unless some position holds literals
+ * that differ: `a/{x}/c` and `a/b/{y}` both take `a/b/c`, and neither is more literal
+ * than the other, so ranking cannot settle it either.
+ *
+ * @param patterns - The registered patterns.
+ * @returns Each ambiguous pair, once, in the order the patterns were given.
+ */ function findAmbiguousRoutes(patterns) {
+    const isParam = (segment)=>PLACEHOLDER_PATTERN.test(segment);
+    const segmentsOf = (pattern)=>pattern.split(PARAM_SEPARATOR);
+    const collisions = [];
+    for(let i = 0; i < patterns.length; i++){
+        for(let j = i + 1; j < patterns.length; j++){
+            const left = segmentsOf(patterns[i]);
+            const right = segmentsOf(patterns[j]);
+            if (left.length !== right.length) continue;
+            const disjoint = left.some((segment, index)=>{
+                PLACEHOLDER_PATTERN.lastIndex = 0;
+                const leftIsParam = isParam(segment);
+                PLACEHOLDER_PATTERN.lastIndex = 0;
+                const rightIsParam = isParam(right[index]);
+                return !leftIsParam && !rightIsParam && segment !== right[index];
+            });
+            if (!disjoint) collisions.push([
+                patterns[i],
+                patterns[j]
+            ]);
+        }
+    }
+    return collisions;
+}
+
+exports.Autocomplete = Autocomplete;
+exports.Command = Command;
+exports.Controller = Controller;
+exports.MessageHandler = MessageHandler;
+exports.PARAM_SEPARATOR = PARAM_SEPARATOR;
+exports.ReactionHandler = ReactionHandler;
+exports.describeInteraction = describeInteraction;
+exports.findAmbiguousRoutes = findAmbiguousRoutes;
+exports.focusedOptionName = focusedOptionName;
+exports.getAutocompleteHandlers = getAutocompleteHandlers;
+exports.getCommandMap = getCommandMap;
+exports.getMessageHandlers = getMessageHandlers;
+exports.getReactionHandlers = getReactionHandlers;
+exports.hasCustomId = hasCustomId;
+exports.matchesCommandType = matchesCommandType;
+exports.resolveCommandPaths = resolveCommandPaths;
+exports.resolveOptionParams = resolveOptionParams;