refactor(Collector): make filter an option (#5903)

Co-authored-by: SpaceEEC <spaceeec@yahoo.com>

src/structures/Message.js

@@ -399,18 +399,17 @@ class Message extends Base {
 
   /**
    * Creates a reaction collector.
-   * @param {CollectorFilter} filter The filter to apply
    * @param {ReactionCollectorOptions} [options={}] Options to send to the collector
    * @returns {ReactionCollector}
    * @example
    * // Create a reaction collector
    * const filter = (reaction, user) => reaction.emoji.name === '👌' && user.id === 'someID';
-   * const collector = message.createReactionCollector(filter, { time: 15000 });
+   * const collector = message.createReactionCollector({ filter, time: 15000 });
    * collector.on('collect', r => console.log(`Collected ${r.emoji.name}`));
    * collector.on('end', collected => console.log(`Collected ${collected.size} items`));
    */
-  createReactionCollector(filter, options = {}) {
-    return new ReactionCollector(this, filter, options);
+  createReactionCollector(options = {}) {
+    return new ReactionCollector(this, options);
   }
 
   /**
@@ -422,19 +421,18 @@ class Message extends Base {
   /**
    * Similar to createReactionCollector but in promise form.
    * Resolves with a collection of reactions that pass the specified filter.
-   * @param {CollectorFilter} filter The filter function to use
    * @param {AwaitReactionsOptions} [options={}] Optional options to pass to the internal collector
    * @returns {Promise<Collection<string, MessageReaction>>}
    * @example
    * // Create a reaction collector
    * const filter = (reaction, user) => reaction.emoji.name === '👌' && user.id === 'someID'
-   * message.awaitReactions(filter, { time: 15000 })
+   * message.awaitReactions({ filter, time: 15000 })
    *   .then(collected => console.log(`Collected ${collected.size} reactions`))
    *   .catch(console.error);
    */
-  awaitReactions(filter, options = {}) {
+  awaitReactions(options = {}) {
     return new Promise((resolve, reject) => {
-      const collector = this.createReactionCollector(filter, options);
+      const collector = this.createReactionCollector(options);
       collector.once('end', (reactions, reason) => {
         if (options.errors && options.errors.includes(reason)) reject(reactions);
         else resolve(reactions);
@@ -444,42 +442,41 @@ class Message extends Base {
 
   /**
    * Creates a message component interaction collector.
-   * @param {CollectorFilter} filter The filter to apply
    * @param {MessageComponentInteractionCollectorOptions} [options={}] Options to send to the collector
    * @returns {MessageComponentInteractionCollector}
    * @example
    * // Create a message component interaction collector
    * const filter = (interaction) => interaction.customID === 'button' && interaction.user.id === 'someID';
-   * const collector = message.createMessageComponentInteractionCollector(filter, { time: 15000 });
+   * const collector = message.createMessageComponentInteractionCollector({ filter, time: 15000 });
    * collector.on('collect', i => console.log(`Collected ${i.customID}`));
    * collector.on('end', collected => console.log(`Collected ${collected.size} items`));
    */
-  createMessageComponentInteractionCollector(filter, options = {}) {
-    return new MessageComponentInteractionCollector(this, filter, options);
+  createMessageComponentInteractionCollector(options = {}) {
+    return new MessageComponentInteractionCollector(this, options);
   }
 
   /**
    * An object containing the same properties as CollectorOptions, but a few more:
    * @typedef {Object} AwaitMessageComponentInteractionOptions
+   * @property {CollectorFilter} [filter] The filter applied to this collector
    * @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 {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, { time: 15000 })
+   * message.awaitMessageComponentInteraction({ filter, time: 15000 })
    *   .then(interaction => console.log(`${interaction.customID} was clicked!`))
    *   .catch(console.error);
    */
-  awaitMessageComponentInteraction(filter, { time } = {}) {
+  awaitMessageComponentInteraction(options = {}) {
     return new Promise((resolve, reject) => {
-      const collector = this.createMessageComponentInteractionCollector(filter, { max: 1, time });
+      const collector = this.createMessageComponentInteractionCollector({ ...options, max: 1 });
       collector.once('end', (interactions, reason) => {
         const interaction = interactions.first();
         if (interaction) resolve(interaction);

src/structures/MessageCollector.js

@@ -17,12 +17,11 @@ const { Events } = require('../util/Constants');
 class MessageCollector extends Collector {
   /**
    * @param {TextChannel|DMChannel} channel The channel
-   * @param {CollectorFilter} filter The filter to be applied to this collector
    * @param {MessageCollectorOptions} options The options to be applied to this collector
    * @emits MessageCollector#message
    */
-  constructor(channel, filter, options = {}) {
-    super(channel.client, filter, options);
+  constructor(channel, options = {}) {
+    super(channel.client, options);
 
     /**
      * The channel

src/structures/MessageComponentInteractionCollector.js

@@ -21,11 +21,10 @@ class MessageComponentInteractionCollector extends Collector {
   /**
    * @param {Message|TextChannel|DMChannel|NewsChannel} source
    * The source from which to collect message component interactions
-   * @param {CollectorFilter} filter The filter to apply to this collector
    * @param {MessageComponentInteractionCollectorOptions} [options={}] The options to apply to this collector
    */
-  constructor(source, filter, options = {}) {
-    super(source.client, filter, options);
+  constructor(source, options = {}) {
+    super(source.client, options);
 
     /**
      * The message from which to collect message component interactions, if provided

src/structures/ReactionCollector.js

@@ -20,11 +20,10 @@ const { Events } = require('../util/Constants');
 class ReactionCollector extends Collector {
   /**
    * @param {Message} message The message upon which to collect reactions
-   * @param {CollectorFilter} filter The filter to apply to this collector
    * @param {ReactionCollectorOptions} [options={}] The options to apply to this collector
    */
-  constructor(message, filter, options = {}) {
-    super(message.client, filter, options);
+  constructor(message, options = {}) {
+    super(message.client, options);
 
     /**
      * The message upon which to collect reactions
@@ -82,10 +81,10 @@ class ReactionCollector extends Collector {
    * Handles an incoming reaction for possible collection.
    * @param {MessageReaction} reaction The reaction to possibly collect
    * @param {User} user The user that added the reaction
-   * @returns {?(Snowflake|string)}
+   * @returns {Promise<Snowflake|string>}
    * @private
    */
-  collect(reaction, user) {
+  async collect(reaction, user) {
     /**
      * Emitted whenever a reaction is collected.
      * @event ReactionCollector#collect
@@ -102,7 +101,7 @@ class ReactionCollector extends Collector {
      * @param {MessageReaction} reaction The reaction that was added
      * @param {User} user The user that added the reaction
      */
-    if (reaction.count === 1 && this.filter(reaction, user, this.collected)) {
+    if (reaction.count === 1 && (await this.filter(reaction, user, this.collected))) {
       this.emit('create', reaction, user);
     }
 

src/structures/interfaces/Collector.js

@@ -16,6 +16,7 @@ const Util = require('../../util/Util');
 /**
  * Options to be applied to the collector.
  * @typedef {Object} CollectorOptions
+ * @property {CollectorFilter} [filter] The filter applied to this collector
  * @property {number} [time] How long to run the collector for in milliseconds
  * @property {number} [idle] How long to stop the collector after inactivity in milliseconds
  * @property {boolean} [dispose=false] Whether to dispose data when it's deleted
@@ -26,7 +27,7 @@ const Util = require('../../util/Util');
  * @abstract
  */
 class Collector extends EventEmitter {
-  constructor(client, filter, options = {}) {
+  constructor(client, options = {}) {
     super();
 
     /**
@@ -40,8 +41,9 @@ class Collector extends EventEmitter {
     /**
      * The filter applied to this collector
      * @type {CollectorFilter}
+     * @returns {boolean|Promise<boolean>}
      */
-    this.filter = filter;
+    this.filter = options.filter ?? (() => true);
 
     /**
      * The options of this collector
@@ -75,8 +77,8 @@ class Collector extends EventEmitter {
      */
     this._idletimeout = null;
 
-    if (typeof filter !== 'function') {
-      throw new TypeError('INVALID_TYPE', 'filter', 'function');
+    if (typeof this.filter !== 'function') {
+      throw new TypeError('INVALID_TYPE', 'options.filter', 'function');
     }
 
     this.handleCollect = this.handleCollect.bind(this);
@@ -89,6 +91,7 @@ class Collector extends EventEmitter {
   /**
    * Call this to handle an event as a collectable element. Accepts any event data as parameters.
    * @param {...*} args The arguments emitted by the listener
+   * @returns {Promise<void>}
    * @emits Collector#collect
    */
   async handleCollect(...args) {
@@ -115,13 +118,14 @@ class Collector extends EventEmitter {
   /**
    * Call this to remove an element from the collection. Accepts any event data as parameters.
    * @param {...*} args The arguments emitted by the listener
+   * @returns {Promise<void>}
    * @emits Collector#dispose
    */
-  handleDispose(...args) {
+  async handleDispose(...args) {
     if (!this.options.dispose) return;
 
     const dispose = this.dispose(...args);
-    if (!dispose || !this.filter(...args) || !this.collected.has(dispose)) return;
+    if (!dispose || !(await this.filter(...args)) || !this.collected.has(dispose)) return;
     this.collected.delete(dispose);
 
     /**

src/structures/interfaces/TextBasedChannel.js

@@ -275,18 +275,17 @@ class TextBasedChannel {
 
   /**
    * Creates a Message Collector.
-   * @param {CollectorFilter} filter The filter to create the collector with
    * @param {MessageCollectorOptions} [options={}] The options to pass to the collector
    * @returns {MessageCollector}
    * @example
    * // Create a message collector
    * const filter = m => m.content.includes('discord');
-   * const collector = channel.createMessageCollector(filter, { time: 15000 });
+   * const collector = channel.createMessageCollector({ filter, time: 15000 });
    * collector.on('collect', m => console.log(`Collected ${m.content}`));
    * collector.on('end', collected => console.log(`Collected ${collected.size} items`));
    */
-  createMessageCollector(filter, options = {}) {
-    return new MessageCollector(this, filter, options);
+  createMessageCollector(options = {}) {
+    return new MessageCollector(this, options);
   }
 
   /**
@@ -298,20 +297,19 @@ class TextBasedChannel {
   /**
    * Similar to createMessageCollector but in promise form.
    * Resolves with a collection of messages that pass the specified filter.
-   * @param {CollectorFilter} filter The filter function to use
    * @param {AwaitMessagesOptions} [options={}] Optional options to pass to the internal collector
    * @returns {Promise<Collection<Snowflake, Message>>}
    * @example
    * // Await !vote messages
    * const filter = m => m.content.startsWith('!vote');
    * // Errors: ['time'] treats ending because of the time limit as an error
-   * channel.awaitMessages(filter, { max: 4, time: 60000, errors: ['time'] })
+   * channel.awaitMessages({ filter, max: 4, time: 60000, errors: ['time'] })
    *   .then(collected => console.log(collected.size))
    *   .catch(collected => console.log(`After a minute, only ${collected.size} out of 4 voted.`));
    */
-  awaitMessages(filter, options = {}) {
+  awaitMessages(options = {}) {
     return new Promise((resolve, reject) => {
-      const collector = this.createMessageCollector(filter, options);
+      const collector = this.createMessageCollector(options);
       collector.once('end', (collection, reason) => {
         if (options.errors && options.errors.includes(reason)) {
           reject(collection);
@@ -324,36 +322,34 @@ class TextBasedChannel {
 
   /**
    * Creates a button interaction collector.
-   * @param {CollectorFilter} filter The filter to apply
    * @param {MessageComponentInteractionCollectorOptions} [options={}] Options to send to the collector
    * @returns {MessageComponentInteractionCollector}
    * @example
    * // Create a button interaction collector
    * const filter = (interaction) => interaction.customID === 'button' && interaction.user.id === 'someID';
-   * const collector = channel.createMessageComponentInteractionCollector(filter, { time: 15000 });
+   * const collector = channel.createMessageComponentInteractionCollector({ filter, time: 15000 });
    * collector.on('collect', i => console.log(`Collected ${i.customID}`));
    * collector.on('end', collected => console.log(`Collected ${collected.size} items`));
    */
-  createMessageComponentInteractionCollector(filter, options = {}) {
-    return new MessageComponentInteractionCollector(this, filter, options);
+  createMessageComponentInteractionCollector(options = {}) {
+    return new MessageComponentInteractionCollector(this, options);
   }
 
   /**
    * 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 {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';
-   * channel.awaitMessageComponentInteraction(filter, { time: 15000 })
+   * channel.awaitMessageComponentInteraction({ filter, time: 15000 })
    *   .then(interaction => console.log(`${interaction.customID} was clicked!`))
    *   .catch(console.error);
    */
-  awaitMessageComponentInteraction(filter, { time } = {}) {
+  awaitMessageComponentInteraction(options = {}) {
     return new Promise((resolve, reject) => {
-      const collector = this.createMessageComponentInteractionCollector(filter, { max: 1, time });
+      const collector = this.createMessageComponentInteractionCollector({ ...options, max: 1 });
       collector.once('end', (interactions, reason) => {
         const interaction = interactions.first();
         if (interaction) resolve(interaction);