update collectors (#1616)

* start new collector stuff

* bugfixes

* remove pointless cleanup method

* rename methods, events, and options; remove extraneous methods,

* update doc ref

src/structures/interfaces/Collector.js

@@ -12,6 +12,7 @@ const EventEmitter = require('events');
  * Options to be applied to the collector.
  * @typedef {Object} CollectorOptions
  * @property {number} [time] How long to run the collector for
+ * @property {boolean} [dispose=false] Whether to dispose data when it's deleted
  */
 
 /**
@@ -61,23 +62,19 @@ class Collector extends EventEmitter {
      */
     this._timeout = null;
 
-    /**
-     * Call this to handle an event as a collectable element
-     * Accepts any event data as parameters
-     * @type {Function}
-     * @private
-     */
-    this.listener = this._handle.bind(this);
+    this.handleCollect = this.handleCollect.bind(this);
+    this.handleDispose = this.handleDispose.bind(this);
+
     if (options.time) this._timeout = this.client.setTimeout(() => this.stop('time'), options.time);
   }
 
   /**
+   * Call this to handle an event as a collectable element. Accepts any event data as parameters.
    * @param {...*} args The arguments emitted by the listener
    * @emits Collector#collect
-   * @private
    */
-  _handle(...args) {
-    const collect = this.handle(...args);
+  handleCollect(...args) {
+    const collect = this.collect(...args);
     if (!collect || !this.filter(...args)) return;
 
     this.collected.set(collect.key, collect.value);
@@ -86,12 +83,34 @@ class Collector extends EventEmitter {
      * Emitted whenever an element is collected.
      * @event Collector#collect
      * @param {*} element The element that got collected
-     * @param {Collector} collector The collector
+     * @param {...*} args The arguments emitted by the listener
      */
-    this.emit('collect', collect.value, this);
+    this.emit('collect', collect.value, ...args);
+    this.checkEnd();
+  }
 
-    const post = this.postCheck(...args);
-    if (post) this.stop(post);
+  /**
+   * Call this to remove an element from the collection. Accepts any event data as parameters.
+   * @param {...*} args The arguments emitted by the listener
+   * @emits Collector#dispose
+   */
+  handleDispose(...args) {
+    if (!this.options.dispose) return;
+
+    const dispose = this.dispose(...args);
+    if (!dispose || !this.filter(...args) || !this.collected.has(dispose)) return;
+
+    const value = this.collected.get(dispose);
+    this.collected.delete(dispose);
+
+    /**
+     * Emitted whenever an element has been disposed.
+     * @event Collector#dispose
+     * @param {*} element The element that was disposed
+     * @param {...*} args The arguments emitted by the listener
+     */
+    this.emit('dispose', value, ...args);
+    this.checkEnd();
   }
 
   /**
@@ -137,7 +156,6 @@ class Collector extends EventEmitter {
 
     if (this._timeout) this.client.clearTimeout(this._timeout);
     this.ended = true;
-    this.cleanup();
 
     /**
      * Emitted when the collector is finished collecting.
@@ -148,30 +166,41 @@ class Collector extends EventEmitter {
     this.emit('end', this.collected, reason);
   }
 
+  /**
+   * Check whether the collector should end, and if so, end it.
+   */
+  checkEnd() {
+    const reason = this.endReason();
+    if (reason) this.stop(reason);
+  }
+
   /* eslint-disable no-empty-function, valid-jsdoc */
   /**
-   * Handles incoming events from the `listener` function. Returns null if the event should not be collected,
-   * or returns an object describing the data that should be stored.
-   * @see Collector#listener
+   * Handles incoming events from the `handleCollect` function. Returns null if the event should not
+   * be collected, or returns an object describing the data that should be stored.
+   * @see Collector#handleCollect
    * @param {...*} args Any args the event listener emits
-   * @returns {?{key: string, value}} Data to insert into collection, if any
+   * @returns {?{key, value}} Data to insert into collection, if any
    * @abstract
    */
-  handle() {}
+  collect() {}
 
   /**
-   * This method runs after collection to see if the collector should finish.
+   * Handles incoming events from the the `handleDispose`. Returns null if the event should not
+   * be disposed, or returns the key that should be removed.
+   * @see Collector#handleDispose
    * @param {...*} args Any args the event listener emits
+   * @returns {?*} Key to remove from the collection, if any
+   * @abstract
+   */
+  dispose() {}
+
+  /**
+   * The reason this collector has ended or will end with.
    * @returns {?string} Reason to end the collector, if any
    * @abstract
    */
-  postCheck() {}
-
-  /**
-   * Called when the collector is ending.
-   * @abstract
-   */
-  cleanup() {}
+  endReason() {}
   /* eslint-enable no-empty-function, valid-jsdoc */
 }