@hyperneutrino/djs-lite 1.6.0 → 1.7.0

package/index.ts

@@ -35,16 +35,62 @@ const identity = <T>(value: T): T => value;
 
 type Wrapper<T extends Function> = (fn: T) => T;
 
-type Handler<T extends CommandInteraction | AutocompleteInteraction | MessageComponentInteraction | ModalSubmitInteraction> = (
+type Handleable = CommandInteraction | AutocompleteInteraction | MessageComponentInteraction | ModalSubmitInteraction;
+
+type Handler<T extends Handleable> = (
     interaction: T,
     ...args: T extends MessageComponentInteraction | ModalSubmitInteraction ? (string | undefined)[] : []
 ) => Awaitable<unknown>;
 
+type WrapperConfig<R extends Record<string, Handleable>> = {
+    [K in keyof R]?: Wrapper<Handler<R[K]>>;
+};
+
+/**
+ * This is the type of `config.wrappers` in `loadCommands`. This type is exported so that you can expose the wrappers upstream if you are making a library
+ * surrounding this library.
+ */
+export interface CommandWrappers extends WrapperConfig<{
+    slashCommands: ChatInputCommandInteraction;
+    userCommands: UserContextMenuCommandInteraction;
+    messageCommands: MessageContextMenuCommandInteraction;
+    autocompletes: AutocompleteInteraction;
+}> {}
+
+/**
+ * This is the type of `config.wrappers` in `loadInteractions`. This type is exported so that you can expose the wrappers upstream if you are making a library
+ * surrounding this library.
+ */
+export interface InteractionWrappers extends WrapperConfig<{
+    modal: ModalSubmitInteraction;
+    button: ButtonInteraction;
+    stringSelectMenu: StringSelectMenuInteraction;
+    userSelectMenu: UserSelectMenuInteraction;
+    roleSelectMenu: RoleSelectMenuInteraction;
+    mentionableSelectMenu: MentionableSelectMenuInteraction;
+    channelSelectMenu: ChannelSelectMenuInteraction;
+}> {}
+
+/**
+ * This is a union type of `CommandWrappers` and `InteractionWrappers` so you can expose all of them at once (since there is no overlap in the field names).
+ */
+export interface Wrappers extends CommandWrappers, InteractionWrappers {}
+
 abstract class Command<T extends BaseApplicationCommandData, U extends CommandInteraction, Z extends boolean = false> {
+    /** This is the command data for the configured command. */
     data: T;
+
+    /** This is the handler for the configured command. */
     handler: Handler<U>;
+
+    /** This is the handler for the configured command's autocomplete fields (always null if not on a slash command). */
     autocomplete: Handler<AutocompleteInteraction> | null;
 
+    /**
+     * @param object This object should contain all of the fields that would be present in this command type's command data except for the `type`.
+     * @param object.handler This parameter must be a function that takes the interaction as the sole parameter and processes it.
+     * @param object.autocomplete If this is a slash command, this parameter may be a function that takes an autocomplete interaction as the sole parameter.
+     */
     constructor({ handler, ...data }: T & { handler: Handler<U> } & (Z extends true ? { autocomplete?: Handler<AutocompleteInteraction> } : {})) {
         if ("autocomplete" in data) {
             const { autocomplete, ...rest } = data;
@@ -59,56 +105,116 @@ abstract class Command<T extends BaseApplicationCommandData, U extends CommandIn
     }
 }
 
+/** This is a slash command configuration object. Prefer {@link SlashCommandWithSubcommands} unless you are sure you want to do subcommand routing manually. */
 export class SlashCommand extends Command<Omit<ChatInputApplicationCommandData, "type">, ChatInputCommandInteraction, true> {}
+
+/** This is a user context menu command configuration object. */
 export class UserCommand extends Command<Omit<UserApplicationCommandData, "type">, UserContextMenuCommandInteraction> {}
+
+/** This is a message context menu command configuration object. */
 export class MessageCommand extends Command<Omit<MessageApplicationCommandData, "type">, MessageContextMenuCommandInteraction> {}
 
+/**
+ * This is a slash command configuration object when the slash command has subcommands/subcommand groups.
+ * There is no handler here; the handler is specified in each subcommand.
+ */
 export class SlashCommandWithSubcommands {
+    /** This is the command data for the root command with the options omitted. */
     data: Omit<ChatInputApplicationCommandData, "options" | "type">;
 
+    /**
+     * @param data This is the command data for the root command with the options ommitted.
+     */
     constructor(data: typeof this.data) {
         this.data = data;
     }
 }
 
+/** This is a slash command subcommand group configuration object. There is no handler here; the handler is specified in each subcommand. */
 export class SubcommandGroup {
+    /** This is the subcommand group data with the options omitted. */
     data: Omit<ApplicationCommandSubGroupData, "options" | "type">;
 
+    /**
+     * @param data This is the subcommand group data with the options omitted.
+     */
     constructor(data: typeof this.data) {
         this.data = data;
     }
 }
 
+/** This is a slash command subcommand configuration object. */
 export class Subcommand {
+    /** This is the subcommand data for the configured subcommand. */
     data: Omit<ApplicationCommandSubCommandData, "type">;
+
+    /** This is the handler for the configured subcommand. */
     handler: Handler<ChatInputCommandInteraction>;
 
-    constructor({ handler, ...data }: typeof this.data & { handler: Subcommand["handler"] }) {
+    /** This is the handler for the configured subcommand's autocomplete fields. */
+    autocomplete: Handler<AutocompleteInteraction> | null;
+
+    /**
+     * @param object This object should contain all of the fields that would be present in this command type's command data except for the `type`.
+     * @param object.handler This parameter must be a function that takes the interaction as the sole parameter and processes it.
+     * @param object.autocomplete If this is a slash command, this parameter may be a function that takes an autocomplete interaction as the sole parameter.
+     */
+    constructor({ handler, autocomplete, ...data }: typeof this.data & { handler: Subcommand["handler"]; autocomplete?: Subcommand["autocomplete"] }) {
         this.data = data;
         this.handler = handler;
+        this.autocomplete = autocomplete ?? null;
     }
 }
 
 abstract class ComponentHandler<T extends ModalSubmitInteraction | MessageComponentInteraction> {
+    /** This is the handler for the configured interaction. */
     handler: Handler<T>;
 
+    /**
+     * @param handler This parameter must be a function that takes the interaction as the first parameter and processes it. Subsequent parameters are possible
+     * and will all be strings if present. These are derived from the interaction's `customId`; see {@link loadInteractions} for instructions.
+     */
     constructor(handler: Handler<T>) {
         this.handler = handler;
     }
 }
 
+/** This is a modal submit interaction configuration object. */
 export class ModalHandler extends ComponentHandler<ModalSubmitInteraction> {}
+
+/** This is a button component interaction configuration object. */
 export class ButtonHandler extends ComponentHandler<ButtonInteraction> {}
+
+/** This is a string select menu component interaction configuration object. */
 export class StringSelectMenuHandler extends ComponentHandler<StringSelectMenuInteraction> {}
+
+/** This is a user select menu component interaction configuration object. */
 export class UserSelectMenuHandler extends ComponentHandler<UserSelectMenuInteraction> {}
+
+/** This is a role select menu component interaction configuration object. */
 export class RoleSelectMenuHandler extends ComponentHandler<RoleSelectMenuInteraction> {}
+
+/** This is a mentionable select menu component interaction configuration object. */
 export class MentionableSelectMenuHandler extends ComponentHandler<MentionableSelectMenuInteraction> {}
+
+/** This is a channel select menu component interaction configuration object. */
 export class ChannelSelectMenuHandler extends ComponentHandler<ChannelSelectMenuInteraction> {}
 
+/**
+ * This is an event handler configuration object.
+ */
 export class EventHandler<T extends keyof ClientEvents> {
+    /** This is the event to watch. */
     event: T;
+
+    /** This is the handler for the configured event type. */
     handler: (...args: ClientEvents[T]) => unknown;
 
+    /**
+     * @param object.event This is the event to watch. This automatically configures the generic type argument.
+     * @param object.handler This is the handler for the configured event type. The parameter types are automatically configured from the generic type
+     * argument.
+     */
     constructor({ event, handler }: { event: T; handler: (...args: ClientEvents[T]) => unknown }) {
         this.event = event;
         this.handler = handler;
@@ -136,45 +242,44 @@ async function importAll(
     );
 }
 
-async function loadSubcommands(directory: string): Promise<{
-    options: ApplicationCommandSubCommandData[];
-    handlers: Map<string, Handler<ChatInputCommandInteraction>>;
-}> {
+async function loadSubcommands(directory: string) {
     if (!(await fs.exists(directory))) throw new Error(`Loading subcommands within a group failed: ${directory} is required but could not be found.`);
 
     const options: ApplicationCommandSubCommandData[] = [];
     const handlers = new Map<string, Handler<ChatInputCommandInteraction>>();
+    const autocompletes = new Map<string, Handler<AutocompleteInteraction>>();
 
     await importAll({ directory, recursive: false }, async ({ file, absolutePath, item }) => {
         if (item instanceof Subcommand) {
             options.push({ ...item.data, type: ApplicationCommandOptionType.Subcommand });
             handlers.set(item.data.name, item.handler);
+            if (item.autocomplete) autocompletes.set(item.data.name, item.autocomplete);
         } else throw new Error(`Loading commands failed: export from ${absolutePath} (third-level in commands folder) was not an instance of Subcommand.`);
 
         if (item.data.name !== file.name.replace(/.[^/.]+$/, ""))
             throw new Error(`Code style enforcement: name exported from ${absolutePath} does not match the filename`);
     });
 
-    return { options, handlers };
+    return { options, handlers, autocompletes };
 }
 
-async function loadSubcommandsAndGroups(directory: string): Promise<{
-    options: (ApplicationCommandSubGroupData | ApplicationCommandSubCommandData)[];
-    handler: Handler<ChatInputCommandInteraction>;
-}> {
+async function loadSubcommandsAndGroups(directory: string) {
     if (!(await fs.exists(directory))) throw new Error(`Loading subcommands/groups failed: ${directory} is required but could not be found.`);
 
     const options: (ApplicationCommandSubGroupData | ApplicationCommandSubCommandData)[] = [];
     const handlers = new Map<string, Handler<ChatInputCommandInteraction>>();
+    const autocompletes = new Map<string, Handler<AutocompleteInteraction>>();
 
     await importAll({ directory, recursive: false }, async ({ file, absolutePath, relativePath, item }) => {
         if (item instanceof Subcommand) {
             options.push({ ...item.data, type: ApplicationCommandOptionType.Subcommand });
             handlers.set(`/${item.data.name}`, item.handler);
+            if (item.autocomplete) autocompletes.set(`/${item.data.name}`, item.autocomplete);
         } else if (item instanceof SubcommandGroup) {
             const subcommands = await loadSubcommands(relativePath.replace(/\.[^/.]+$/, ""));
             options.push({ ...item.data, type: ApplicationCommandOptionType.SubcommandGroup, options: subcommands.options });
             subcommands.handlers.entries().forEach(([key, handler]) => handlers.set(`${item.data.name}/${key}`, handler));
+            subcommands.autocompletes.entries().forEach(([key, autocomplete]) => autocompletes.set(`${item.data.name}/${key}`, autocomplete));
         } else
             throw new Error(
                 `Loading commands failed: export from ${absolutePath} (second-level in commands folder) was not an instance of SubcommandGroup or Subcommand.`,
@@ -186,23 +291,38 @@ async function loadSubcommandsAndGroups(directory: string): Promise<{
 
     return {
         options,
-        handler: (cmd) => handlers.get(`${cmd.options.getSubcommandGroup(false) ?? ""}/${cmd.options.getSubcommand(true)}`)?.(cmd),
+        handler: (cmd: ChatInputCommandInteraction) => handlers.get(`${cmd.options.getSubcommandGroup(false) ?? ""}/${cmd.options.getSubcommand(true)}`)?.(cmd),
+        autocomplete: (cmd: AutocompleteInteraction) =>
+            autocompletes.get(`${cmd.options.getSubcommandGroup(false) ?? ""}/${cmd.options.getSubcommand(true)}`)?.(cmd),
     };
 }
 
-export async function loadCommands(
-    client: Client<true>,
-    directory: string,
-    config?: {
-        guildId?: string;
-        wrappers?: {
-            slashCommands?: Wrapper<Handler<ChatInputCommandInteraction>>;
-            userCommands?: Wrapper<Handler<UserContextMenuCommandInteraction>>;
-            messageCommands?: Wrapper<Handler<MessageContextMenuCommandInteraction>>;
-            autocompletes?: Wrapper<Handler<AutocompleteInteraction>>;
-        };
-    },
-) {
+/**
+ * Load commands from a directory to a client. This will attach the command listeners. If the command data has been changed (based on the local .cache/
+ * directory), then the commands will be automatically set on the client (or the guild if `config.guildId` is set).
+ *
+ * Each file within the directory should be `command-name.{ts,js}` exporting a {@link SlashCommand}, {@link UserCommand}, {@link MessageCommand}, or
+ * {@link SlashCommandWithSubcommands}. If the file exports {@link SlashCommandWithSubcommands}, there should be a directory with the same command name.
+ *
+ * Each file within that subdirectory should be `subcommand-name.{ts,js}` exporting a {@link Subcommand} or `subcommand-group-name.{ts,js}` exporting a
+ * {@link SubcommandGroup}. If it exports a {@link SubcommandGroup}, there should be a directory with the same subcommand group name.
+ *
+ * Each file within the third directory level should be `subcommand-name.{ts,js}` exporting a {@link Subcommand}.
+ *
+ * The file name must match the command (or subcommand group, or subcommand) name for all types.
+ *
+ * @param client The post-login client into which to load the commands.
+ * @param directory The relative path (from your execution point) containing your command handlers.
+ * @param config Command-related configuration values.
+ * @param config.guildId The ID of the guild to which to set the commands.
+ * @param config.wrappers A set of wrappers which transform all handler functions for each handler type.
+ * @returns `commands`, the loaded command data (an array of objects).
+ * @returns `slashCommandHandlers`, the map from each slash command name to its handler.
+ * @returns `userCommandHandlers`, the map from each user context menu command name to its handler.
+ * @returns `messageCommandHandlers`, the map from each message context menu command name to its handler.
+ * @returns `setCommands`, indicating whether or not the commands were pushed to the Discord API.
+ */
+export async function loadCommands(client: Client<true>, directory: string, config?: { guildId?: string; wrappers?: CommandWrappers }) {
     const commandData: (ChatInputApplicationCommandData | UserApplicationCommandData | MessageApplicationCommandData)[] = [];
 
     const slashCommandHandlers = new Map<string, Handler<ChatInputCommandInteraction>>();
@@ -223,9 +343,10 @@ export async function loadCommands(
             commandData.push({ ...item.data, type: ApplicationCommandType.Message });
             messageCommandHandlers.set(item.data.name, (config?.wrappers?.messageCommands ?? identity)(item.handler));
         } else if (item instanceof SlashCommandWithSubcommands) {
-            const { options, handler } = await loadSubcommandsAndGroups(relativePath.replace(/\.[^/.]+$/, ""));
+            const { options, handler, autocomplete } = await loadSubcommandsAndGroups(relativePath.replace(/\.[^/.]+$/, ""));
             commandData.push({ ...item.data, options });
             slashCommandHandlers.set(item.data.name, (config?.wrappers?.slashCommands ?? identity)(handler));
+            slashCommandAutocompletes.set(item.data.name, (config?.wrappers?.autocompletes ?? identity)(autocomplete));
         } else {
             throw new Error(`Loading commands failed: export from ${absolutePath} was not an instance of <Type>Command.`);
         }
@@ -266,20 +387,44 @@ export async function loadCommands(
     return { commands: commandData, slashCommandHandlers, userCommandHandlers, messageCommandHandlers, setCommands: commandDataHasBeenUpdated };
 }
 
+/**
+ * Load interactions from a directory to a client. This will attach the interaction (modal submit and message component) listeners.
+ *
+ * Each file within the directory (recursively) should be `*.{ts,js}` exporting a {@link ModalHandler}, {@link ButtonHandler}, {@link StringSelectMenuHandler},
+ * {@link UserSelectMenuHandler}, {@link RoleSelectMenuHandler}, {@link MentionableSelectMenuHandler}, or {@link ChannelSelectMenuHandler}.
+ *
+ * To use these interactions, the `customId` on the modal/message component must start with the argument separator (`config.argumentSeparator`, which defaults
+ * to `:`). You can optionally put a user ID after this to restrict who can interact with that component. Otherwise, place another argument separator
+ * immediately. Since modals are only submittable by the user to whom they're shown, setting a user ID is not recommended as you should control who sees the
+ * modal at all instead, but it will technically work. If this ID is set, any other users will simply be ignored and your handler will not be invoked.
+ *
+ * After the second argument separator, specify the path (separated by slashes regardless of your operating system). This will be looked up relative to the
+ * provided directory, so if you provide `src/interactions` and the path argument of `customId` is `pages/next`, then this will point to
+ * `src/interactions/pages/next.{ts,js}`.
+ *
+ * You can specify any number of additional string arguments, separating each with the argument separator. The `customId` will be naively `.split()` on this
+ * separator, so it is impossible to include the separator symbol/sequence anywhere in any of the arguments. Your handler will receive these as additional
+ * arguments.
+ *
+ * @param client The client (may be pre-login) into which to load the interaction handlers.
+ * @param directory The relative path (from your execution point) containing your interaction handlers.
+ * @param config Interaction-related configuration values.
+ * @param config.argumentSeparator The separator used to split custom IDs. This defaults to `:`.
+ * @param config.wrappers A set of wrappers which transform all handler functions for each handler type.
+ * @returns `modalHandlers`, the map from each modal submit handler's configuration file path to its handler function.
+ * @returns `buttonHandlers`, the map from each button handler's configuration file path to its handler function.
+ * @returns `stringSelectMenuHandlers`, the map from each string select menu handler's file path to its handler function.
+ * @returns `userSelectMenuHandlers`, the map from each user select menu handler's file path to its handler function.
+ * @returns `roleSelectMenuHandlers`, the map from each role select menu handler's file path to its handler function.
+ * @returns `mentionableSelectMenuHandlers`, the map from each mentionable select menu handler's file path to its handler function.
+ * @returns `channelSelectMenuHandlers`, the map from each channel select menu handler's file path to its handler function.
+ */
 export async function loadInteractions(
     client: Client,
     directory: string,
     config?: {
         argumentSeparator?: string;
-        wrappers?: {
-            modal?: Wrapper<Handler<ModalSubmitInteraction>>;
-            button?: Wrapper<Handler<ButtonInteraction>>;
-            stringSelectMenu?: Wrapper<Handler<StringSelectMenuInteraction>>;
-            userSelectMenu?: Wrapper<Handler<UserSelectMenuInteraction>>;
-            roleSelectMenu?: Wrapper<Handler<RoleSelectMenuInteraction>>;
-            mentionableSelectMenu?: Wrapper<Handler<MentionableSelectMenuInteraction>>;
-            channelSelectMenu?: Wrapper<Handler<ChannelSelectMenuInteraction>>;
-        };
+        wrappers?: InteractionWrappers;
     },
 ) {
     const modalHandlers = new Map<string, Handler<ModalSubmitInteraction>>();
@@ -335,6 +480,23 @@ export async function loadInteractions(
     };
 }
 
+/**
+ * Load event listeners from a directory to a client.
+ *
+ * Each file within the directory should be `*.{ts,js}` exporting an {@link EventHandler}. The generic type argument of {@link EventHandler} will automatically
+ * be inferred by its {@link EventHandler.event} property, which will automatically establish the type for the handler.
+ *
+ * Whether the files are loaded recursively depends on {@link recursive} which is `false` by default. If it is `false`, then subdirectories will not be
+ * scanned, allowing you to place utility functions and similar files within them.
+ *
+ * Unlike with {@link loadCommands} and {@link loadInteractions}, event handler files can be named anything and the name is purely cosmetic.
+ *
+ * @param client The client (may be pre-login) into which to load the event handlers.
+ * @param directory The relative path (from your execution point) containing your event handlers.
+ * @param recursive Whether to load recursively from the directory (defaults to false).
+ * @returns `handlers`, a partial record from each event type to an array of its handler functions.
+ * @returns `filenames`, a partial record from each event type to an array of its files' paths (relative from `directory`).
+ */
 export async function loadEvents(client: Client, directory: string, recursive: boolean = false) {
     const handlers: Partial<{ [K in keyof ClientEvents]: ((...args: ClientEvents[K]) => unknown)[] }> = {};
     const filenames: Partial<{ [K in keyof ClientEvents]: string[] }> = {};

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@hyperneutrino/djs-lite",
     "private": false,
-    "version": "1.6.0",
+    "version": "1.7.0",
     "module": "index.ts",
     "type": "module",
     "devDependencies": {