refactor(awaitMessageComponentInteraction): use options object for lib consistency (#5852)

src/errors/Messages.js

@@ -50,7 +50,7 @@ const Messages = {
   BUTTON_URL: 'MessageButton url must be a string',
   BUTTON_CUSTOM_ID: 'MessageButton customID must be a string',
 
-  INTERACTION_COLLECTOR_TIMEOUT: 'Collector timed out without receiving any interactions',
+  INTERACTION_COLLECTOR_ERROR: reason => `Collector received no interactions before ending with reason: ${reason}`,
 
   FILE_NOT_FOUND: file => `File could not be found: ${file}`,
 

src/structures/Message.js

@@ -439,26 +439,32 @@ class Message extends Base {
     return new MessageComponentInteractionCollector(this, filter, options);
   }
 
+  /**
+   * An object containing the same properties as CollectorOptions, but a few more:
+   * @typedef {Object} AwaitMessageComponentInteractionOptions
+   * @property {number} [time] Time to wait for an interaction before rejecting
+   */
+
   /**
    * Collects a single component interaction that passes the filter.
    * The Promise will reject if the time expires.
    * @param {CollectorFilter} filter The filter function to use
-   * @param {number} [time] Time to wait for an interaction before rejecting
+   * @param {AwaitMessageComponentInteractionOptions} [options={}] Options to pass to the internal collector
    * @returns {Promise<MessageComponentInteraction>}
    * @example
    * // Collect a message component interaction
    * const filter = (interaction) => interaction.customID === 'button' && interaction.user.id === 'someID';
-   * message.awaitMessageComponentInteraction(filter, 15000)
+   * message.awaitMessageComponentInteraction(filter, { time: 15000 })
    *   .then(interaction => console.log(`${interaction.customID} was clicked!`))
    *   .catch(console.error);
    */
-  awaitMessageComponentInteraction(filter, time) {
+  awaitMessageComponentInteraction(filter, { time } = {}) {
     return new Promise((resolve, reject) => {
       const collector = this.createMessageComponentInteractionCollector(filter, { max: 1, time });
-      collector.once('end', interactions => {
+      collector.once('end', (interactions, reason) => {
         const interaction = interactions.first();
-        if (!interaction) reject(new Error('INTERACTION_COLLECTOR_TIMEOUT'));
-        else resolve(interaction);
+        if (interaction) resolve(interaction);
+        else reject(new Error('INTERACTION_COLLECTOR_ERROR', reason));
       });
     });
   }

src/structures/interfaces/TextBasedChannel.js

@@ -342,22 +342,22 @@ class TextBasedChannel {
    * Collects a single component interaction that passes the filter.
    * The Promise will reject if the time expires.
    * @param {CollectorFilter} filter The filter function to use
-   * @param {number} [time] Time to wait for an interaction before rejecting
+   * @param {AwaitMessageComponentInteractionOptions} [options={}] Options to pass to the internal collector
    * @returns {Promise<MessageComponentInteraction>}
    * @example
-   * // Collect a button interaction
+   * // Collect a message component interaction
    * const filter = (interaction) => interaction.customID === 'button' && interaction.user.id === 'someID';
-   * channel.awaitMessageComponentInteraction(filter, 15000)
+   * channel.awaitMessageComponentInteraction(filter, { time: 15000 })
    *   .then(interaction => console.log(`${interaction.customID} was clicked!`))
    *   .catch(console.error);
    */
-  awaitMessageComponentInteraction(filter, time) {
+  awaitMessageComponentInteraction(filter, { time } = {}) {
     return new Promise((resolve, reject) => {
       const collector = this.createMessageComponentInteractionCollector(filter, { max: 1, time });
-      collector.once('end', interactions => {
+      collector.once('end', (interactions, reason) => {
         const interaction = interactions.first();
-        if (!interaction) reject(new Error('INTERACTION_COLLECTOR_TIMEOUT'));
-        else resolve(interaction);
+        if (interaction) resolve(interaction);
+        else reject(new Error('INTERACTION_COLLECTOR_ERROR', reason));
       });
     });
   }

typings/index.d.ts

@@ -1189,7 +1189,7 @@ declare module 'discord.js' {
     public reference: MessageReference | null;
     public awaitMessageComponentInteraction(
       filter: CollectorFilter<[MessageComponentInteraction]>,
-      time?: number,
+      options?: AwaitMessageComponentInteractionOptions,
     ): Promise<MessageComponentInteraction>;
     public awaitReactions(
       filter: CollectorFilter<[MessageReaction, User]>,
@@ -2373,7 +2373,7 @@ declare module 'discord.js' {
     typingCount: number;
     awaitMessageComponentInteraction(
       filter: CollectorFilter<[MessageComponentInteraction]>,
-      time?: number,
+      options?: AwaitMessageComponentInteractionOptions,
     ): Promise<MessageComponentInteraction>;
     awaitMessages(
       filter: CollectorFilter<[Message]>,
@@ -2581,6 +2581,10 @@ declare module 'discord.js' {
     new?: any;
   }
 
+  interface AwaitMessageComponentInteractionOptions {
+    time?: number;
+  }
+
   interface AwaitMessagesOptions extends MessageCollectorOptions {
     errors?: string[];
   }