feat(Util): add SweptCollection for auto sweeping of caches (#6110)

Co-authored-by: DTrombett <73136330+DTrombett@users.noreply.github.com>
Co-authored-by: 1Computer1 <22125769+1Computer1@users.noreply.github.com>
Co-authored-by: Antonio Román <kyradiscord@gmail.com>
Co-authored-by: NotSugden <28943913+NotSugden@users.noreply.github.com>
Co-authored-by: Shino <shinotheshino@gmail.com>
Co-authored-by: SpaceEEC <24881032+SpaceEEC@users.noreply.github.com>
Co-authored-by: Noel <icrawltogo@gmail.com>
Co-authored-by: Vlad Frangu <kingdgrizzle@gmail.com>

.eslintrc.json

@@ -2,10 +2,10 @@
   "extends": ["eslint:recommended", "plugin:prettier/recommended"],
   "plugins": ["import"],
   "parserOptions": {
-    "ecmaVersion": 2020
+    "ecmaVersion": 2021
   },
   "env": {
-    "es2020": true,
+    "es2021": true,
     "node": true
   },
   "rules": {

package.json

@@ -46,7 +46,7 @@
   "homepage": "https://github.com/discordjs/discord.js#readme",
   "dependencies": {
     "@discordjs/builders": "^0.2.0",
-    "@discordjs/collection": "^0.1.6",
+    "@discordjs/collection": "^0.2.0",
     "@discordjs/form-data": "^3.0.1",
     "@sapphire/async-queue": "^1.1.4",
     "@types/ws": "^7.4.5",
@@ -77,7 +77,7 @@
     "typescript": "^4.3.4"
   },
   "engines": {
-    "node": ">=14.0.0",
+    "node": ">=14.6.0",
     "npm": ">=7.0.0"
   }
 }

src/client/Client.js

@@ -72,6 +72,20 @@ class Client extends BaseClient {
 
     this._validateOptions();
 
+    /**
+     * Functions called when a cache is garbage collected or the Client is destroyed
+     * @type {Set<Function>}
+     * @private
+     */
+    this._cleanups = new Set();
+
+    /**
+     * The finalizers used to cleanup items.
+     * @type {FinalizationRegistry}
+     * @private
+     */
+    this._finalizers = new FinalizationRegistry(this._finalize.bind(this));
+
     /**
      * The WebSocket manager of the client
      * @type {WebSocketManager}
@@ -161,6 +175,10 @@ class Client extends BaseClient {
     this.readyAt = null;
 
     if (this.options.messageSweepInterval > 0) {
+      process.emitWarning(
+        'The message sweeping client options are deprecated, use the makeCache option with a SweptCollection instead.',
+        'DeprecationWarning',
+      );
       this.sweepMessageInterval = setInterval(
         this.sweepMessages.bind(this),
         this.options.messageSweepInterval * 1000,
@@ -247,6 +265,10 @@ class Client extends BaseClient {
    */
   destroy() {
     super.destroy();
+
+    for (const fn of this._cleanups) fn();
+    this._cleanups.clear();
+
     if (this.sweepMessageInterval) clearInterval(this.sweepMessageInterval);
 
     this.ws.destroy();
@@ -346,6 +368,23 @@ class Client extends BaseClient {
     const data = await this.api('sticker-packs').get();
     return new Collection(data.sticker_packs.map(p => [p.id, new StickerPack(this, p)]));
   }
+  /**
+   * A last ditch cleanup function for garbage collection.
+   * @param {Function} options.cleanup The function called to GC
+   * @param {string} [options.message] The message to send after a successful GC
+   * @param {string} [options.name] The name of the item being GCed
+   */
+  _finalize({ cleanup, message, name }) {
+    try {
+      cleanup();
+      this._cleanups.delete(cleanup);
+      if (message) {
+        this.emit(Events.DEBUG, message);
+      }
+    } catch {
+      this.emit(Events.DEBUG, `Garbage collection failed on ${name ?? 'an unknown item'}.`);
+    }
+  }
 
   /**
    * Sweeps all text-based channels' messages and removes the ones older than the max message lifetime.

src/errors/Messages.js

@@ -145,6 +145,8 @@ const Messages = {
   INVITE_MISSING_SCOPES: 'At least one valid scope must be provided for the invite',
 
   NOT_IMPLEMENTED: (what, name) => `Method ${what} not implemented on ${name}.`,
+
+  SWEEP_FILTER_RETURN: 'The return value of the sweepFilter function was not false or a Function',
 };
 
 for (const [name, message] of Object.entries(Messages)) register(name, message);

src/index.js

@@ -27,6 +27,7 @@ module.exports = {
   Permissions: require('./util/Permissions'),
   RateLimitError: require('./rest/RateLimitError'),
   SnowflakeUtil: require('./util/SnowflakeUtil'),
+  SweptCollection: require('./util/SweptCollection'),
   SystemChannelFlags: require('./util/SystemChannelFlags'),
   ThreadMemberFlags: require('./util/ThreadMemberFlags'),
   UserFlags: require('./util/UserFlags'),

src/managers/ApplicationCommandPermissionsManager.js

@@ -16,6 +16,7 @@ class ApplicationCommandPermissionsManager extends BaseManager {
     /**
      * The manager or command that this manager belongs to
      * @type {ApplicationCommandManager|ApplicationCommand}
+     * @private
      */
     this.manager = manager;
 

src/managers/CachedManager.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const DataManager = require('./DataManager');
+const { _cleanupSymbol } = require('../util/Constants');
 
 /**
  * Manages the API methods of a data model with a mutable cache of instances.
@@ -13,6 +14,19 @@ class CachedManager extends DataManager {
 
     Object.defineProperty(this, '_cache', { value: this.client.options.makeCache(this.constructor, this.holds) });
 
+    let cleanup = this._cache[_cleanupSymbol];
+    if (cleanup) {
+      cleanup = cleanup.bind(this._cache);
+      client._cleanups.add(cleanup);
+      client._finalizers.register(this, {
+        cleanup,
+        message:
+          `Garbage Collection completed on ${this.constructor.name}, ` +
+          `which had a ${this._cache.constructor.name} of ${this.holds.name}.`,
+        name: this.constructor.name,
+      });
+    }
+
     if (iterable) {
       for (const item of iterable) {
         this._add(item);

src/managers/GuildEmojiRoleManager.js

@@ -72,7 +72,7 @@ class GuildEmojiRoleManager extends DataManager {
       resolvedRoleIds.push(roleId);
     }
 
-    const newRoles = this.cache.keyArray().filter(id => !resolvedRoleIds.includes(id));
+    const newRoles = [...this.cache.keys()].filter(id => !resolvedRoleIds.includes(id));
     return this.set(newRoles);
   }
 
@@ -97,7 +97,7 @@ class GuildEmojiRoleManager extends DataManager {
 
   clone() {
     const clone = new this.constructor(this.emoji);
-    clone._patch(this.cache.keyArray().slice());
+    clone._patch([...this.cache.keys()]);
     return clone;
   }
 

src/managers/GuildMemberRoleManager.js

@@ -172,7 +172,7 @@ class GuildMemberRoleManager extends DataManager {
 
   clone() {
     const clone = new this.constructor(this.member);
-    clone.member._roles = [...this.cache.keyArray()];
+    clone.member._roles = [...this.cache.keys()];
     return clone;
   }
 }

src/util/Collection.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const BaseCollection = require('@discordjs/collection');
+const { Collection: BaseCollection } = require('@discordjs/collection');
 const Util = require('./Util');
 
 class Collection extends BaseCollection {

src/util/Constants.js

@@ -971,6 +971,8 @@ exports.PrivacyLevels = createEnum([null, 'PUBLIC', 'GUILD_ONLY']);
  */
 exports.PremiumTiers = createEnum(['NONE', 'TIER_1', 'TIER_2', 'TIER_3']);
 
+exports._cleanupSymbol = Symbol('djsCleanup');
+
 function keyMirror(arr) {
   let tmp = Object.create(null);
   for (const value of arr) tmp[value] = value;

src/util/Options.js

@@ -35,10 +35,11 @@
  * (e.g. recommended shard count, shard count of the ShardingManager)
  * @property {CacheFactory} [makeCache] Function to create a cache.
  * You can use your own function, or the {@link Options} class to customize the Collection used for the cache.
- * @property {number} [messageCacheLifetime=0] How long a message should stay in the cache until it is considered
- * sweepable (in seconds, 0 for forever)
- * @property {number} [messageSweepInterval=0] How frequently to remove messages from the cache that are older than
- * the message cache lifetime (in seconds, 0 for never)
+ * @property {number} [messageCacheLifetime=0] DEPRECATED: Use `makeCache` with a `SweptCollection` instead.
+ * How long a message should stay in the cache until it is considered sweepable (in seconds, 0 for forever)
+ * @property {number} [messageSweepInterval=0] DEPRECATED: Use `makeCache` with a `SweptCollection` instead.
+ * How frequently to remove messages from the cache that are older than the message cache lifetime
+ * (in seconds, 0 for never)
  * @property {MessageMentionOptions} [allowedMentions] Default value for {@link MessageOptions#allowedMentions}
  * @property {number} [invalidRequestWarningInterval=0] The number of invalid REST requests (those that return
  * 401, 403, or 429) in a 10 minute window between emitted warnings (0 for no warnings). That is, if set to 500,
@@ -99,7 +100,15 @@ class Options extends null {
   static createDefault() {
     return {
       shardCount: 1,
-      makeCache: this.cacheWithLimits({ MessageManager: 200 }),
+      makeCache: this.cacheWithLimits({
+        MessageManager: 200,
+        ThreadManager: {
+          sweepFilter: require('./SweptCollection').filterByLifetime({
+            getComparisonTimestamp: e => e.archiveTimestamp,
+            excludeFromSweep: e => !e.archived,
+          }),
+        },
+      }),
       messageCacheLifetime: 0,
       messageSweepInterval: 0,
       invalidRequestWarningInterval: 0,
@@ -134,20 +143,52 @@ class Options extends null {
   }
 
   /**
-   * Create a cache factory using predefined limits.
-   * @param {Record<string, number>} [limits={}] Limits for structures.
+   * Create a cache factory using predefined settings to sweep or limit.
+   * @param {Object<string, SweptCollectionOptions|number>} [settings={}] Settings passed to the relevant constructor.
+   * If no setting is provided for a manager, it uses Collection.
+   * If SweptCollectionOptions are provided for a manager, it uses those settings to form a SweptCollection
+   * If a number is provided for a manager, it uses that number as the max size for a LimitedCollection
    * @returns {CacheFactory}
+   * @example
+   * // Store up to 200 messages per channel and discard archived threads if they were archived more than 4 hours ago.
+   * Options.cacheWithLimits({
+   *    MessageManager: 200,
+   *    ThreadManager: {
+   *      sweepFilter: SweptCollection.filterByLifetime({
+   *        getComparisonTimestamp: e => e.archiveTimestamp,
+   *        excludeFromSweep: e => !e.archived,
+   *      }),
+   *    },
+   *  });
+   * @example
+   * // Sweep messages every 5 minutes, removing messages that have not been edited or created in the last 30 minutes
+   * Options.cacheWithLimits({
+   *   MessageManager: {
+   *     sweepInterval: 300,
+   *     sweepFilter: SweptCollection.filterByLifetime({
+   *       lifetime: 1800,
+   *       getComparisonTimestamp: e => e.editedTimestamp ?? e.createdTimestamp,
+   *     })
+   *   }
+   * });
    */
-  static cacheWithLimits(limits = {}) {
+  static cacheWithLimits(settings = {}) {
     const Collection = require('./Collection');
     const LimitedCollection = require('./LimitedCollection');
+    const SweptCollection = require('./SweptCollection');
 
     return manager => {
-      const limit = limits[manager.name];
-      if (limit === null || limit === undefined || limit === Infinity) {
+      const setting = settings[manager.name];
+      if (typeof setting === 'number' && setting !== Infinity) return new LimitedCollection(setting);
+      if (
+        /* eslint-disable-next-line eqeqeq */
+        (setting?.sweepInterval == null && setting?.sweepFilter == null) ||
+        setting.sweepInterval <= 0 ||
+        setting.sweepInterval === Infinity
+      ) {
         return new Collection();
       }
-      return new LimitedCollection(limit);
+      return new SweptCollection(setting);
     };
   }