doc: improvements

Author: fourcolverleaf

src/index.ts

@@ -31,6 +31,7 @@ import type {
   SelectMenuMiddleware,
   CommandMiddleware,
   CommandbuilderType,
+  GenericMiddleware,
 } from "./interactionRouter/internal.js";
 
 import type { MessageMentionOptions } from "discord.js";
@@ -135,7 +136,8 @@ class Client extends HttpInteractionServer {
    *
    * Receives raw {@link APIInteraction} payload and response object.
    *
-   * @param fns - Middleware functions to execute.
+   * @param fns - {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
+   *
    */
 
   middleware(...fns: GeneralMiddleware[]) {
@@ -145,7 +147,7 @@ class Client extends HttpInteractionServer {
   /**
    * Adds global middleware for unknown interactions.
    *
-   * @param fns - Functions executed when no handler matches an interaction.
+   * @param fns - Async Functions executed when no handler matches an interaction. See {@link UnknownMiddleware} for callback parameters.
    */
   unknown(...fns: UnknownMiddleware[]) {
     this.router._unknownInteraction.push(...fns);
@@ -172,17 +174,19 @@ class Client extends HttpInteractionServer {
   /**
    * Registers a command with its associated middleware.
    *
+   * @param commandbuilder - Function returning a {@link SlashCommandBuilder}.
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
+   * @returns {@link AutoCompleteKeyBuilder} for autocomplete options.
    * @example
+   *
    * ```ts
    * router.command(
-   *   (builder) => builder.setName("Ping!").setDescription("Returns Pong!"),
-   *   async (interaction) => interaction.reply({ content: "pong!" })
+   *   (builder) =>
+   *     builder.setName("Ping!").setDescription("Returns Pong!"),
+   *     pongHandle
    * );
    * ```
    *
-   * @param commandbuilder - Function returning a {@link SlashCommandBuilder}.
-   * @param fns - Middleware functions for the command.
-   * @returns An {@link AutoCompleteKeyBuilder} for autocomplete options.
    */
   command(commandbuilder: CommandbuilderType, ...fns: CommandMiddleware[]) {
     this.tryAsync(fns);
@@ -199,6 +203,7 @@ class Client extends HttpInteractionServer {
   /**
    * Registers a button interaction with its associated middleware.
    *
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
    * @example
    * ```ts
    * router.button("custom_button_id", buttonMiddleware);
@@ -212,6 +217,7 @@ class Client extends HttpInteractionServer {
   /**
    * Registers a modal interaction with its associated middleware.
    *
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
    * @example
    * ```ts
    * router.modal("custom_modal_id", modalMiddleware);
@@ -225,6 +231,7 @@ class Client extends HttpInteractionServer {
   /**
    * Registers a role select interaction with its associated middleware.
    *
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
    * @example
    * ```ts
    * router.roleSelect("roleSelectName", roleSelectMiddleware);
@@ -238,6 +245,7 @@ class Client extends HttpInteractionServer {
   /**
    * Registers a user select interaction with its associated middleware.
    *
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
    * @example
    * ```ts
    * router.userSelect("userSelectName", userSelectMiddleware);
@@ -250,6 +258,7 @@ class Client extends HttpInteractionServer {
   /**
    * Registers a string select interaction with its associated middleware.
    *
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
    * @example
    * ```ts
    * router.stringSelect("stringSelectName", stringSelectMiddleware);
@@ -263,6 +272,7 @@ class Client extends HttpInteractionServer {
   /**
    * Registers a channel select interaction with its associated middleware.
    *
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
    * @example
    * ```ts
    * router.channelSelect("channelSelectName", channelSelectMiddleware);
@@ -276,6 +286,7 @@ class Client extends HttpInteractionServer {
   /**
    * Registers a mentionable select interaction with its associated middleware.
    *
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
    * @example
    * ```ts
    * router.mentionableSelect("mentionableSelectName", mentionableSelectMiddleware);
@@ -288,7 +299,8 @@ class Client extends HttpInteractionServer {
 
   /**
    * Registers an autocomplete interaction with its associated middleware.
-   *
+   * 
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
    * @example
    * ```ts
    * const githubQuery = router.command(
@@ -326,6 +338,7 @@ class Client extends HttpInteractionServer {
   /**
    * Registers a user context menu interaction with its associated middleware.
    *
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
    * @example
    * ```ts
    * router.userContextMenu("userContextMenuId", userContextMenuMiddleware);
@@ -339,6 +352,7 @@ class Client extends HttpInteractionServer {
   /**
    * Registers a message context menu interaction with its associated middleware.
    *
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
    * @example
    * ```ts
    * router.messageContextMenu("messageContextMenu", messageContextMenuMiddleware);

src/interactionRouter/index.ts

@@ -24,7 +24,9 @@ import { SlashCommandBuilder } from "@discordjs/builders";
  *
  * @example
  * ```ts
- *  import { InteractionRouter } from 'discord.https/router';
+ * // utility/ping.js
+ *
+ * import { InteractionRouter } from 'discord.https/router';
  * const router = new InteractionRouter();
  * export deafult router.command(
  *   (builder) => builder.setName("Ping!").setDescription("Returns Pong!"),
@@ -88,7 +90,7 @@ class InteractionRouter {
    *
    * This does **not** affect other routers or collectors.
    *
-   * @param fns Async middleware functions.
+   * @param fns Async middleware functions. See {@link GenericMiddleware} for callback parameters
    */
 
   middleware(...fns: GeneralMiddleware[]) {
@@ -108,7 +110,7 @@ class InteractionRouter {
    * ```
    *
    * @param commandbuilder - Function returning a {@link SlashCommandBuilder}.
-   * @param fns - Middleware functions for the command.
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
    * @returns An {@link AutoCompleteKeyBuilder} for autocomplete options.
    */
   command(commandbuilder: CommandbuilderType, ...fns: CommandMiddleware[]) {
@@ -126,6 +128,7 @@ class InteractionRouter {
   /**
    * Registers a button interaction with its associated middleware.
    *
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
    * @example
    * ```ts
    * router.button("custom_button_id", buttonMiddleware);
@@ -139,6 +142,7 @@ class InteractionRouter {
   /**
    * Registers a modal interaction with its associated middleware.
    *
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
    * @example
    * ```ts
    * router.modal("custom_modal_id", modalMiddleware);
@@ -152,6 +156,7 @@ class InteractionRouter {
   /**
    * Registers a role select interaction with its associated middleware.
    *
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
    * @example
    * ```ts
    * router.roleSelect("roleSelectName", roleSelectMiddleware);
@@ -165,6 +170,7 @@ class InteractionRouter {
   /**
    * Registers a user select interaction with its associated middleware.
    *
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
    * @example
    * ```ts
    * router.userSelect("userSelectName", userSelectMiddleware);
@@ -177,6 +183,7 @@ class InteractionRouter {
   /**
    * Registers a string select interaction with its associated middleware.
    *
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
    * @example
    * ```ts
    * router.stringSelect("stringSelectName", stringSelectMiddleware);
@@ -190,6 +197,7 @@ class InteractionRouter {
   /**
    * Registers a channel select interaction with its associated middleware.
    *
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
    * @example
    * ```ts
    * router.channelSelect("channelSelectName", channelSelectMiddleware);
@@ -203,6 +211,7 @@ class InteractionRouter {
   /**
    * Registers a mentionable select interaction with its associated middleware.
    *
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
    * @example
    * ```ts
    * router.mentionableSelect("mentionableSelectName", mentionableSelectMiddleware);
@@ -216,18 +225,19 @@ class InteractionRouter {
   /**
    * Registers an autocomplete interaction with its associated middleware.
    *
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
    * @example
    * ```ts
    * const githubQuery = router.command(
    *   (builder) =>
    *     builder
-   *       .setName("weather")  // The command name
-   *       .setDescription("QuQuery weather information!")  // The command description
+   *       .setName("weather")
+   *       .setDescription("Query weather information!")
    *       .addStringOption(option =>
    *         option
-   *           .setName("city")  // Option name
-   *           .setDescription("City to get the weather for")  // Option description
-   *           .setAutocomplete(true) // Enable autocomplete for this option
+   *           .setName("city")
+   *           .setDescription("City to get the weather for")
+   *           .setAutocomplete(true)
    *       ),
    *   (interaction) => handler
    * );
@@ -249,6 +259,7 @@ class InteractionRouter {
   /**
    * Registers a user context menu interaction with its associated middleware.
    *
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
    * @example
    * ```ts
    * router.userContextMenu("userContextMenuId", userContextMenuMiddleware);
@@ -262,6 +273,7 @@ class InteractionRouter {
   /**
    * Registers a message context menu interaction with its associated middleware.
    *
+   * @param fns {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | Async} functions. See {@link GenericMiddleware} for callback parameters.
    * @example
    * ```ts
    * router.messageContextMenu("messageContextMenu", messageContextMenuMiddleware);
@@ -296,19 +308,25 @@ class InteractionRouter {
 /**
  * Collector for InteractionRouter.
  *
- *  @example
+ *
+ * @example
+ *
+ * Example: Organizing multiple interaction routes with a collector.
+ *
  * ```ts
- * import { InteractionRouter, InteractionRouterCollector } from 'discord.https/router';
+ * import { InteractionRouterCollector } from "discord.https/router";
  *
- * const router = new InteractionRouter()
- * router.command(
- * (builder) => builder.setName("Ping!").setDescription("Returns Pong!")
- * (interaction) => interaction.reply({
- * content: "pong!"
- * })
- * )
- * // Register routes
- * InteractionRouterCollector.register(router);
+ * // Recommend using PascalCase and ending with the 'Route' suffix
+ * // for variable naming convention
+ *
+ * import PingRoute from "./ping.js";
+ * import GithubRoute from "./github.js";
+ *
+ *
+ * export default new InteractionRouterCollector().register(
+ *   PingRoute,
+ *   GithubRoute
+ * );
  * ```
  */
 

src/interactionRouter/internal.ts

@@ -60,11 +60,37 @@ export interface Context {
     | APIContextMenuInteraction;
 }
 
+/**
+ * A middleware function executed during an HTTP interaction lifecycle.
+ *
+ * @typeParam T - The specific interaction type handled by the middleware.
+ *   Defaults to {@link Context.resolvedInteraction | Context["resolvedInteraction"]}.
+ */
 export type GenericMiddleware<T = Context["resolvedInteraction"]> = (
+  /**
+   * The resolved interaction for this request.
+   */
   interaction: T,
+
+  /**
+   * A read-only {@link REST} client instance.
+   * Use this to perform Discord REST API calls safely.
+   */
   client: Readonly<REST>,
+
+  /**
+   * A function you can call to immediately stop further
+   * middleware execution and end the request.
+   */
   flush: () => never,
-  // `res` will be removed in the near future, as the structure is complete.
+
+  /**
+   * The underlying {@link HttpAdapterSererResponse} object.
+   *
+   * This will be removed in the near future, as the structure is complete.
+   * This will only be available for unknown middleware
+   * (see {@link UnknownMiddleware}).
+   */
   res: HttpAdapterSererResponse
 ) => Promise<void>;
 
@@ -114,12 +140,35 @@ export type ContextMenuMiddleware =
   | MenuContextMenuMiddleware;
 
 // export type UnknownMiddleware = GenericMiddleware<DiscordHttpsAPIInteraction>;
+
+/**
+ * A middleware type for interactions that the library
+ * does not explicitly cover.
+ *
+ * @typeParam T - The Discord HTTPS API interaction type.
+ *   Defaults to {@link DiscordHttpsAPIInteraction}.
+ */
 export type UnknownMiddleware<T = DiscordHttpsAPIInteraction> = (
+  /**
+   * The raw Discord HTTPS API interaction.
+   */
   interaction: T,
+  /**
+   * A read-only {@link REST} client instance.
+   */
   client: Readonly<REST>,
+  /**
+   * Ends the middleware chain immediately.
+   * Calling `flush()` stops further middleware and never returns.
+   */
   flush: () => never,
-  // `res` should be provided to unknown middlewares only, as `UnknownMiddleware` is meant to be used
-  // only when the library doesn't cover that specific interaction.
+  /**
+   * The underlying {@link HttpAdapterSererResponse} object.
+   *
+   * `res` should be provided to unknown middlewares only,
+   * as {@link UnknownMiddleware} is meant to be used when the
+   * library does not yet cover a specific interaction.
+   */
   res: HttpAdapterSererResponse
 ) => Promise<void>;
 
@@ -169,6 +218,19 @@ interface UnknownRoute {
 
 type ResolvedRoute = KnownRoute | UnknownRoute;
 
+/**
+ *
+ * @internal
+ *
+ * Manages registration and routing of Discord interaction middlewares.
+ *
+ * The `InteractionRouterManager` stores middleware stacks for
+ * different Discord interaction types (commands, buttons, selects,
+ * context menus, etc.) and provides a registry for both known and
+ * unknown routes.
+ *
+ */
+
 class InteractionRouterManager {
   middlewares: GenericMiddleware<DiscordHttpsInteraction>[] = [];
   _unknownInteraction: GenericMiddleware<DiscordHttpsAPIInteraction>[] = [];