@wolfstar/plugin-gateway 0.9.0-next-20261002163719 → 0.9.0

package/README.md

@@ -65,6 +65,7 @@ On top of the `Client` options:
 | `intents`             | —                 | The gateway intents.                                                                                                               |
 | `cacheConstructor`    | `CollectionCache` | Builds `manager.cache`, the cache of structure instances each manager reads through, see [Cache](#cache).                          |
 | `cacheOptions`        | `undefined`       | Per-entity options of those caches, e.g. `{ messages: { maxSize: 1_000 } }`, see [Bounding memory](#bounding-memory).              |
+| `sweepers`            | `undefined`       | Periodically evicts entries from those caches, e.g. `DefaultSweeperSettings`, see [Sweepers](#sweepers).                           |
 | `cache`               | `undefined`       | A `@wolfstar/plugin-cache` cache whose raw stores back the managers instead, see [Cache](#cache).                                  |
 | `shardCount`          | `null`            | Total shards across every process, `null` for Discord's recommendation.                                                            |
 | `shardIds`            | `null`            | The shards this client runs, as an array or a `{ start, end }` range. `null` for all.                                              |
@@ -381,7 +382,7 @@ Only `manager.cache.get` (and `fetch`, `resolve`, which read it) returns the cac
 
 ### Bounding memory
 
-With the default cache, nothing is evicted unless a dispatch removes it. There are three ways to bound it:
+With the default cache, nothing is evicted unless a dispatch removes it. There are four ways to bound it:
 
 - **`cacheOptions`** sets a `maxSize` per entity: once reached, the oldest entry is evicted for each new one, and
   `0` holds nothing. It is passed to the `cacheConstructor`, the default `CollectionCache` included.
@@ -419,9 +420,68 @@ With the default cache, nothing is evicted unless a dispatch removes it. There a
   new GatewayClient({ intents, cache: null });
   ```
 
+- **[`sweepers`](#sweepers)** evict entries on a timer, e.g. messages nobody touched for a while.
+
+`cacheOptions` also takes a `keepOverLimit(value, key, cache)`, like discord.js's `LimitedCollection`: once `maxSize`
+is reached, the oldest entry it answers `false` for is evicted, and the cache grows past `maxSize` if it keeps them
+all. `cacheWithLimits` builds `cacheOptions` from plain numbers:
+
+```ts
+import { cacheWithLimits } from "@wolfstar/plugin-gateway";
+
+new GatewayClient({
+  intents,
+  // 200 messages, no presences, and up to 1000 members plus the ones in a voice channel.
+  cacheOptions: cacheWithLimits({
+    messages: 200,
+    presences: 0,
+    members: { maxSize: 1_000, keepOverLimit: (member) => member.voice?.channelId != null },
+  }),
+});
+```
+
 `cacheOptions` only applies to caches built by a constructor: like `cacheConstructor`, combining it with `cache` or
 `makeCache` throws (those stores have their own bounds), and it is ignored with `cache: null`.
 
+### Sweepers
+
+Like discord.js's, `sweepers` evict the entries of a cache every `interval` seconds. Each entity takes either a
+`lifetime` (in seconds) or a `filter` factory that returns the predicate of that sweep, or `null` to skip it. Only
+`invites`, `messages` and `threads` take a `lifetime`: a message is swept when it was last edited or created longer
+ago than that, a thread when it has been archived for longer, an invite when it has expired for longer.
+
+```ts
+import { GatewayClient, Sweepers } from "@wolfstar/plugin-gateway";
+
+const client = new GatewayClient({
+  intents,
+  sweepers: {
+    messages: { interval: 3_600, lifetime: 1_800 },
+    users: { interval: 3_600, filter: () => (user) => user.bot },
+    // Evict what Sweepers.filterByLifetime selects, counted from a timestamp of your choosing.
+    members: {
+      interval: 3_600,
+      filter: Sweepers.filterByLifetime({
+        lifetime: 7_200,
+        getComparisonTimestamp: (member) => member.joinedTimestamp,
+        excludeFromSweep: (member) => member.voice?.channelId != null,
+      }),
+    },
+  },
+});
+
+// Or on demand, which returns how many entries were evicted.
+client.sweepers.sweepMessages(600);
+client.sweepers.sweepUsers(() => (user) => user.bot);
+```
+
+`DefaultSweeperSettings` sweeps messages untouched for 30 minutes and threads archived for four hours, every hour.
+Unlike discord.js's, it is not empty. Every sweep emits `cacheSweep(entity, swept)`, and a failing filter emits
+`cacheError` with `operation: "sweep"` instead of throwing out of the timer. `client.destroy()` stops the timers.
+
+Sweepers walk the caches of structure instances, so combining them with `cache` or `makeCache` throws: set the `ttl`
+of their `policies` instead.
+
 ### Custom caches
 
 `cacheConstructor` takes a class implementing `Cache`, instantiated once per entity with

package/dist/esm/index.d.ts

@@ -824,6 +824,14 @@ interface CacheEntityOptions {
    * @default Infinity
    */
   maxSize?: number;
+  /**
+   * Decides which entries `maxSize` never evicts, like discord.js's `LimitedCollection#keepOverLimit`: called with
+   * the oldest entries in turn, the first one it answers `false` for is evicted. When it answers `true` for all of
+   * them, the cache grows past `maxSize`.
+   *
+   * @default undefined
+   */
+  keepOverLimit?: (value: any, key: string, cache: Map<string, any>) => boolean;
 }
 /**
  * What a {@link CacheConstructor} receives as its third argument: how the client keys and refreshes the entity, and
@@ -10133,6 +10141,224 @@ export declare const Partials: {
  */
 export type Partials = (typeof Partials)[keyof typeof Partials];
 //#endregion
+//#region src/util/Sweepers.d.ts
+/**
+ * The structures held by the caches {@link Sweepers} can sweep, by entity.
+ */
+export interface SweepableEntities {
+  autoModerationRules: AutoModerationRule;
+  bans: GuildBan;
+  emojis: GuildEmoji;
+  invites: GuildInvite;
+  members: GuildMember;
+  messages: Message;
+  presences: Presence;
+  stageInstances: StageInstance;
+  stickers: Sticker;
+  threadMembers: ThreadMember;
+  threads: AnyThreadChannel;
+  users: User;
+  voiceStates: VoiceState;
+}
+/**
+ * The name of an entity whose cache {@link Sweepers} can sweep.
+ */
+export type SweepableEntityName = keyof SweepableEntities;
+/**
+ * Every {@link SweepableEntityName}.
+ */
+export declare const SweepableEntityNames: readonly ["autoModerationRules", "bans", "emojis", "invites", "members", "messages", "presences", "stageInstances", "stickers", "threadMembers", "threads", "users", "voiceStates"];
+/**
+ * The entities whose sweeper can be set with a `lifetime` instead of a `filter`.
+ */
+export type LifetimeSweepableEntityName = "invites" | "messages" | "threads";
+/**
+ * Decides whether a sweep evicts an entry: `true` evicts it.
+ */
+export type SweepFilter<Value> = (value: Value, key: string, collection: Collection<string, Value>) => boolean;
+/**
+ * Builds the {@link SweepFilter} of one sweep, called once per sweep so that it can read the clock. Answering `null`
+ * skips the sweep.
+ */
+export type SweepFilterFactory<Value> = () => SweepFilter<Value> | null;
+/**
+ * Sweeps an entity with a filter, every `interval` seconds.
+ */
+export interface SweeperFilterOptions<Value> {
+  /**
+   * The seconds between two sweeps. A non-positive or infinite interval does not schedule any.
+   */
+  interval: number;
+  /**
+   * Builds the filter of each sweep, see {@link SweepFilterFactory}.
+   */
+  filter: SweepFilterFactory<Value>;
+  lifetime?: never;
+}
+/**
+ * Sweeps an entity every `interval` seconds, evicting the entries older than `lifetime` seconds.
+ */
+export interface SweeperLifetimeOptions {
+  /**
+   * The seconds between two sweeps. A non-positive or infinite interval does not schedule any.
+   */
+  interval: number;
+  /**
+   * The seconds an entry lives: messages since they were created or last edited, threads since they were archived (an
+   * active thread is never swept), invites since they expired (an invite that never expires is never swept). A
+   * non-positive lifetime skips the sweep.
+   */
+  lifetime: number;
+  filter?: never;
+}
+/**
+ * The sweepers of the client, by entity, see {@link GatewayClientOptions.sweepers}.
+ */
+export type SweeperOptions = { [Name in SweepableEntityName]?: Name extends LifetimeSweepableEntityName ? SweeperFilterOptions<SweepableEntities[Name]> | SweeperLifetimeOptions : SweeperFilterOptions<SweepableEntities[Name]>; };
+/**
+ * The options of {@link Sweepers.filterByLifetime}.
+ */
+export interface FilterByLifetimeOptions<Value> {
+  /**
+   * The seconds an entry lives, a non-positive value skips the sweep.
+   *
+   * @default 14400
+   */
+  lifetime?: number;
+  /**
+   * Gets the timestamp the lifetime is counted from, an entry without one is never swept.
+   *
+   * @default (value) => value.createdTimestamp
+   */
+  getComparisonTimestamp?: (value: Value, key: string, collection: Collection<string, Value>) => number | null | undefined;
+  /**
+   * Whether an entry is never swept.
+   *
+   * @default () => false
+   */
+  excludeFromSweep?: SweepFilter<Value>;
+}
+/**
+ * Evicts entries from the caches of instances, on a schedule or on demand, like discord.js's `Sweepers`.
+ *
+ * @remarks
+ * It works with the caches the client builds from {@link GatewayClientOptions.cacheConstructor}, the default
+ * `CollectionCache` included: they are `Map`s. The stores of `@wolfstar/plugin-cache` hold raw data, and expire it
+ * with the `ttl` of their policies instead, so sweeping them throws.
+ *
+ * A sweep only evicts entries from the cache: it emits no event but `cacheSweep`, and the structures the application
+ * keeps stay valid.
+ *
+ * @example
+ * ```typescript
+ * const client = new GatewayClient({
+ *   intents,
+ *   sweepers: {
+ *     // Every hour, forget the messages not touched for half an hour.
+ *     messages: { interval: 3_600, lifetime: 1_800 },
+ *     // Every hour, forget the bots.
+ *     users: { interval: 3_600, filter: () => (user) => user.bot },
+ *   },
+ * });
+ *
+ * // On demand.
+ * client.sweepers.sweepMessages(600);
+ * ```
+ */
+export declare class Sweepers {
+  #private;
+  /**
+   * The options the sweepers were scheduled from.
+   */
+  readonly options: SweeperOptions;
+  constructor(client: GatewayClient, options?: SweeperOptions);
+  /**
+   * Evicts the entries of an entity's cache the filter answers `true` for.
+   *
+   * @param entity The name of the entity.
+   * @param filter Builds the filter of the sweep.
+   * @returns The amount of entries evicted, `0` when the filter skips the sweep or the entity is not cached.
+   */
+  sweep<Name extends SweepableEntityName>(entity: Name, filter: SweepFilterFactory<SweepableEntities[Name]>): number;
+  /**
+   * Evicts the auto moderation rules the filter answers `true` for.
+   */
+  sweepAutoModerationRules(filter: SweepFilterFactory<AutoModerationRule>): number;
+  /**
+   * Evicts the bans the filter answers `true` for.
+   */
+  sweepBans(filter: SweepFilterFactory<GuildBan>): number;
+  /**
+   * Evicts the emojis the filter answers `true` for.
+   */
+  sweepEmojis(filter: SweepFilterFactory<GuildEmoji>): number;
+  /**
+   * Evicts the invites that expired more than `lifetime` seconds ago.
+   *
+   * @param lifetime The seconds an invite lives past its expiration.
+   */
+  sweepInvites(lifetime?: number): number;
+  /**
+   * Evicts the members the filter answers `true` for.
+   */
+  sweepMembers(filter: SweepFilterFactory<GuildMember>): number;
+  /**
+   * Evicts the messages created or last edited more than `lifetime` seconds ago.
+   *
+   * @param lifetime The seconds a message lives.
+   */
+  sweepMessages(lifetime?: number): number;
+  /**
+   * Evicts the presences the filter answers `true` for.
+   */
+  sweepPresences(filter: SweepFilterFactory<Presence>): number;
+  /**
+   * Evicts the stage instances the filter answers `true` for.
+   */
+  sweepStageInstances(filter: SweepFilterFactory<StageInstance>): number;
+  /**
+   * Evicts the stickers the filter answers `true` for.
+   */
+  sweepStickers(filter: SweepFilterFactory<Sticker>): number;
+  /**
+   * Evicts the thread members the filter answers `true` for.
+   */
+  sweepThreadMembers(filter: SweepFilterFactory<ThreadMember>): number;
+  /**
+   * Evicts the threads archived more than `lifetime` seconds ago, see {@link Sweepers.outdatedThreadSweepFilter}.
+   *
+   * @param lifetime The seconds a thread lives past its archival.
+   */
+  sweepThreads(lifetime?: number): number;
+  /**
+   * Evicts the users the filter answers `true` for.
+   */
+  sweepUsers(filter: SweepFilterFactory<User>): number;
+  /**
+   * Evicts the voice states the filter answers `true` for.
+   */
+  sweepVoiceStates(filter: SweepFilterFactory<VoiceState>): number;
+  /**
+   * Stops the scheduled sweeps. On-demand sweeps keep working.
+   */
+  destroy(): void;
+  /**
+   * Builds a filter factory evicting the entries older than a lifetime, for {@link Sweepers.sweep} and the `filter`
+   * of a sweeper.
+   *
+   * @param options The lifetime, and what it is counted from.
+   */
+  static filterByLifetime<Value>(options?: FilterByLifetimeOptions<Value>): SweepFilterFactory<Value>;
+  /**
+   * Builds a filter factory evicting the archived threads that have been so for longer than a lifetime. Active
+   * threads are never evicted.
+   *
+   * @param lifetime The seconds a thread lives past its archival.
+   * @default 14400
+   */
+  static outdatedThreadSweepFilter(lifetime?: number): SweepFilterFactory<AnyThreadChannel>;
+}
+//#endregion
 //#region src/GatewayClient.d.ts
 export interface GatewayClientOptions extends ClientOptions, GatewayClientMessageDefaults {
   /**
@@ -10199,6 +10425,30 @@ export interface GatewayClientOptions extends ClientOptions, GatewayClientMessag
    * @default undefined
    */
   cacheOptions?: Partial<Record<CacheEntityName, CacheEntityOptions>>;
+  /**
+   * Evicts entries from the caches of instances on a schedule, like discord.js's `sweepers` option: each entity has
+   * its own sweeper, evicting what a `filter` selects or what outlived a `lifetime`, every `interval` seconds. See
+   * {@link Sweepers}, whose methods sweep on demand, and {@link DefaultSweeperSettings}.
+   *
+   * @remarks
+   * The timers do not keep the process alive, and stop on {@link GatewayClient.destroy}. A sweep that throws (e.g. a
+   * filter) is reported through `cacheError`, and the next one runs as scheduled.
+   *
+   * It only applies to caches built by a constructor, the default included: like `cacheConstructor`, combining it with
+   * {@link GatewayClientOptions.cache} or {@link GatewayClientOptions.makeCache} throws, their stores expire entries
+   * with the `ttl` of {@link GatewayClientOptions.policies}. With `cache: null` it is ignored.
+   *
+   * @example
+   * ```typescript
+   * sweepers: {
+   *   messages: { interval: 3_600, lifetime: 1_800 },
+   *   users: { interval: 3_600, filter: () => (user) => user.bot },
+   * }
+   * ```
+   *
+   * @default undefined
+   */
+  sweepers?: SweeperOptions;
   /**
    * A `@wolfstar/plugin-cache` cache (in memory or Redis) whose raw stores back the managers, instead of the
    * in-memory caches of instances built by {@link GatewayClientOptions.cacheConstructor}: structures are then built
@@ -10417,6 +10667,11 @@ export declare class GatewayClient extends Client {
   readonly templates: GuildTemplateManager;
   readonly voiceStates: VoiceStateManager;
   readonly presences: PresenceManager;
+  /**
+   * Evicts entries from the caches of instances, on the schedule of {@link GatewayClientOptions.sweepers} and on
+   * demand, like discord.js's `Client#sweepers`.
+   */
+  readonly sweepers: Sweepers;
   /**
    * What happens to a dispatch whose cache read or write fails, see {@link GatewayClientOptions.cacheFailure}.
    */
@@ -10479,6 +10734,13 @@ export declare class GatewayClient extends Client {
    * @param name The name of the entity.
    */
   CacheConstructor<Value extends StructureMixin<object>>(creator: StructureCreator<Value>, name: CacheEntityName): Cache<Value>;
+  /**
+   * Gets the cache of an entity if it was built already, without building it.
+   *
+   * @param name The name of the entity.
+   * @internal
+   */
+  cacheOf(name: CacheEntityName): Cache<any> | undefined;
   /**
    * Runs a raw store operation, reporting its failure through `cacheError`, see
    * {@link GatewayClientOptions.cacheErrors}. Synchronous when the operation is.
@@ -10779,7 +11041,7 @@ export interface CacheErrorContext {
   /**
    * The operation that failed.
    */
-  operation: "get" | "set" | "upsert" | "delete" | "has" | "clear" | "getSize" | "keys" | "entries";
+  operation: "get" | "set" | "upsert" | "delete" | "has" | "clear" | "getSize" | "keys" | "entries" | "sweep";
 }
 /**
  * What a reaction event says besides the reaction and the user.
@@ -10851,6 +11113,10 @@ export interface GatewayEventMap {
    * `cacheErrors: "miss"`, the manager then carries on as if the entry was not cached.
    */
   cacheError: [error: unknown, context: CacheErrorContext];
+  /**
+   * Emitted when a sweep of an entity's cache ran, with the amount of entries it evicted, see `Sweepers`.
+   */
+  cacheSweep: [entity: SweepableEntityName, swept: number];
   guildCreate: [guild: Guild];
   guildUpdate: [oldGuild: Guild | null, newGuild: Guild];
   /**
@@ -11041,6 +11307,7 @@ export declare enum GatewayEvents {
   ShardClose = "shardClose",
   ShardError = "shardError",
   CacheError = "cacheError",
+  CacheSweep = "cacheSweep",
   GuildCreate = "guildCreate",
   GuildUpdate = "guildUpdate",
   GuildDelete = "guildDelete",
@@ -11173,7 +11440,9 @@ export declare namespace EventGatewayListener {
 export declare const GatewayErrorMessages: {
   readonly ClientSessionStoreConflict: "sessionStore replaces gateway.retrieveSessionInfo and gateway.updateSessionInfo, pass one or the other";
   readonly ClientCacheConflict: "cacheConstructor and cacheOptions cannot be combined with cache or makeCache, pass one or the other";
+  readonly ClientSweepersConflict: "sweepers cannot be combined with cache or makeCache, whose stores hold raw data a sweep cannot filter: use their policies' ttl instead";
   readonly ClientNotConstructed: "No GatewayClient has been constructed yet";
+  readonly SweeperIntervalTooLong: (entity: string, interval: number) => string;
   readonly DispatchHandlerConflict: (event: string) => string;
   readonly DispatchTimeout: (type: string, shardId: number, partition: string | null, timeout: number) => string;
   readonly SessionStoreFailed: (operation: "get" | "set", shardId: number) => string;
@@ -11324,6 +11593,11 @@ export interface CollectionCacheOptions<Value, Raw> {
    * @default Infinity
    */
   maxSize?: number;
+  /**
+   * Decides which entries `maxSize` never evicts: the oldest one it answers `false` for is evicted instead. When it
+   * answers `true` for every entry, the cache grows past `maxSize`.
+   */
+  keepOverLimit?: (value: Value, key: string, cache: Map<string, Value>) => boolean;
 }
 /**
  * The default {@link Cache}: an in-memory `Collection` of structure instances, like discord.js's caches.
@@ -11620,6 +11894,37 @@ export declare class GatewaySessionStoreError extends GatewayError<"SessionStore
   constructor(operation: "get" | "set", shardId: number, cause: unknown);
 }
 //#endregion
+//#region src/util/limits.d.ts
+/**
+ * Builds the {@link GatewayClientOptions.cacheOptions} bounding the caches of some entities, like discord.js's
+ * `Options.cacheWithLimits`. A number is the `maxSize` of the entity, an object is its whole options.
+ *
+ * @example
+ * ```typescript
+ * const client = new GatewayClient({
+ *   intents,
+ *   // Keep the 200 most recent messages, no presences, and up to 1000 members, plus any member in a voice channel.
+ *   cacheOptions: cacheWithLimits({
+ *     messages: 200,
+ *     presences: 0,
+ *     members: { maxSize: 1_000, keepOverLimit: (member) => member.voice?.channelId != null },
+ *   }),
+ * });
+ * ```
+ *
+ * @param limits The `maxSize` or the options of each entity.
+ */
+export declare function cacheWithLimits(limits: Partial<Record<CacheEntityName, number | CacheEntityOptions>>): Partial<Record<CacheEntityName, CacheEntityOptions>>;
+/**
+ * Ready-made {@link GatewayClientOptions.sweepers}, for a bot that only needs recent messages and threads: every hour,
+ * messages untouched for 30 minutes are evicted, and so are threads archived for more than four hours.
+ *
+ * @remarks
+ * Unlike discord.js's `Options.DefaultSweeperSettings`, which is empty, it sweeps. Spread it to override an entity:
+ * `sweepers: { ...DefaultSweeperSettings, users: { interval: 3_600, filter: () => (user) => user.bot } }`.
+ */
+export declare const DefaultSweeperSettings: SweeperOptions;
+//#endregion
 //#region src/util/permissions.d.ts
 /**
  * What {@link computeGuildPermissions} needs to know about a member of a guild.