@wolfstar/plugin-gateway 0.8.0 → 0.9.0-next-20261002081721

package/dist/esm/index.d.ts

@@ -1,10 +1,11 @@
 import { Client, ClientOptions, Listener } from "@wolfstar/http-framework";
 import { OptionalWebSocketManagerOptions, ShardRange, WebSocketManager } from "@discordjs/ws";
 import { API, Client as Client$1 } from "@discordjs/core";
-import { Awaitable, Cache, CacheEntityName, CacheEntityTypes, CacheFactory, CachePolicies, EntityCache, GatewaySessionStore, IterableEntityCache } from "@wolfstar/plugin-cache";
+import { Awaitable, Cache as Cache$1, CacheEntityName, CacheEntityTypes, CacheFactory, CachePolicies, EntityCache, GatewaySessionStore, IterableEntityCache } from "@wolfstar/plugin-cache";
 import { APIActionRowComponent, APIAllowedMentions, APIApplication, APIApplicationCommand, APIAttachment, APIAuditLogChange, APIAuthorizingIntegrationOwnersMap, APIAutoModerationAction, APIAutoModerationRule, APIAutoModerationRuleTriggerMetadata, APIAvatarDecorationData, APIButtonComponentWithCustomId, APIButtonComponentWithSKUId, APIButtonComponentWithURL, APIChannel, APIChannelMention, APIChannelSelectComponent, APICheckboxComponent, APICheckboxGroupComponent, APICheckboxGroupOption, APICollectibles, APIComponentInActionRow, APIComponentInMessageActionRow, APIContainerComponent, APIEmbed, APIEmbedAuthor, APIEmbedField, APIEmbedFooter, APIEmbedImage, APIEmbedProvider, APIEmbedThumbnail, APIEmbedVideo, APIEmoji, APIEntitlement, APIExtendedInvite, APIFileComponent, APIFileUploadComponent, APIGuild, APIGuildForumDefaultReactionEmoji, APIGuildForumTag, APIGuildMember, APIGuildOnboarding, APIGuildOnboardingPrompt, APIGuildOnboardingPromptOption, APIGuildPreview, APIGuildScheduledEvent, APIGuildScheduledEventEntityMetadata, APIGuildScheduledEventRecurrenceRule, APIGuildScheduledEventRecurrenceRuleNWeekday, APIGuildWelcomeScreen, APIGuildWidget, APIGuildWidgetMember, APIIncidentsData, APIInviteChannel, APIInviteGuild, APILabelComponent, APIMediaGalleryComponent, APIMediaGalleryItem, APIMentionableSelectComponent, APIMessage, APIMessageActivity, APIMessageCall, APIMessageComponent, APIMessageComponentEmoji, APIMessageInteractionMetadata, APIMessageReference, APIMessageRoleSubscriptionData, APIMessageTopLevelComponent, APIModalComponent, APIOverwrite, APIPartialEmoji, APIPoll, APIPollAnswer, APIRadioGroupComponent, APIRadioGroupOption, APIReaction, APIRole, APIRoleSelectComponent, APIRoleTags, APISKU, APISectionComponent, APISelectMenuDefaultValue, APISelectMenuOption, APISeparatorComponent, APISoundboardSound, APIStageInstance, APISticker, APIStickerPack, APIStringSelectComponent, APISubscription, APITemplate, APITextDisplayComponent, APITextInputComponent, APIThreadChannel, APIThreadMember, APIThumbnailComponent, APIUnfurledMediaItem, APIUser, APIUserPrimaryGuild, APIUserSelectComponent, APIVoiceRegion, APIWebhook, ActivityFlags, ActivityType, AllowedMentionsTypes, ApplicationCommandOptionType, ApplicationFlags, AttachmentFlags, AuditLogEvent, AutoModerationActionType, AutoModerationRuleEventType, AutoModerationRuleKeywordPresetType, AutoModerationRuleTriggerType, ButtonStyle, ChannelFlags, ChannelType, FileUploadType, ForumLayoutType, GatewayActivity, GatewayActivityAssets, GatewayActivityUpdateData, GatewayAutoModerationActionExecutionDispatchData, GatewayChannelPinsUpdateDispatchData, GatewayDispatchEvents, GatewayDispatchPayload, GatewayGuildDeleteDispatchData, GatewayGuildIntegrationsUpdateDispatchData, GatewayGuildMemberRemoveDispatchData, GatewayGuildMembersChunkDispatchData, GatewayGuildRoleDeleteDispatchData, GatewayGuildScheduledEventUserAddDispatchData, GatewayGuildScheduledEventUserRemoveDispatchData, GatewayGuildSoundboardSoundDeleteDispatchData, GatewayIntegrationDeleteDispatchData, GatewayIntentBits, GatewayInviteCreateDispatchData, GatewayInviteDeleteDispatchData, GatewayMessageDeleteBulkDispatchData, GatewayMessageDeleteDispatchData, GatewayMessageReactionRemoveAllDispatchData, GatewayPresenceClientStatus, GatewayPresenceUpdateData, GatewayRateLimitedDispatchData, GatewayReadyDispatchData, GatewayThreadDeleteDispatchData, GatewayThreadListSync, GatewayThreadMembersUpdateDispatchData, GatewayTypingStartDispatchData, GatewayVoiceServerUpdateDispatchData, GatewayWebhooksUpdateDispatchData, GuildDefaultMessageNotifications, GuildExplicitContentFilter, GuildMemberFlags, GuildOnboardingMode, GuildOnboardingPromptType, GuildPremiumTier, GuildScheduledEventEntityType, GuildScheduledEventPrivacyLevel, GuildScheduledEventRecurrenceRuleFrequency, GuildScheduledEventRecurrenceRuleMonth, GuildScheduledEventRecurrenceRuleWeekday, GuildScheduledEventStatus, GuildSystemChannelFlags, GuildVerificationLevel, GuildWidgetStyle, InteractionType, InviteTargetType, InviteType, Locale, MessageActivityType, MessageFlags, MessageReferenceType, NameplatePalette, OverwriteType, PermissionFlagsBits, PollLayoutType, PresenceUpdateReceiveStatus, PresenceUpdateStatus, RESTAPIPoll, RESTGetAPIGuildVanityUrlResult, RESTPatchAPIChannelJSONBody, RESTPatchAPIGuildJSONBody, RESTPostAPIApplicationCommandsJSONBody, RESTPostAPIChannelMessageJSONBody, RESTPostAPIGuildsJSONBody, ReactionType, RoleFlags, SelectMenuDefaultValueType, SeparatorSpacingSize, Snowflake, SortOrderType, StageInstancePrivacyLevel, StickerFormatType, ThreadAutoArchiveDuration, ThreadChannelType, UserFlags, VideoQualityMode } from "discord-api-types/v10";
 import { APIActualInvite, ActionRowComponent, Activity as Activity$1, ActivityFlagsBitField as ActivityFlagsBitField$1, AnnouncementChannel as AnnouncementChannel$1, AnnouncementThreadChannel as AnnouncementThreadChannel$1, Attachment as Attachment$1, AttachmentFlagsBitField as AttachmentFlagsBitField$1, AutoModerationRule as AutoModerationRule$1, BitField, BitField as BitField$1, BitFieldResolvable, BitFieldResolvable as BitFieldResolvable$1, CategoryChannel as CategoryChannel$1, Channel as Channel$1, ChannelFlagsBitField as ChannelFlagsBitField$1, ChannelSelectMenuComponent as ChannelSelectMenuComponent$1, Component as Component$1, ContainerComponent as ContainerComponent$1, DMChannel as DMChannel$1, Embed as Embed$1, Emoji as Emoji$1, FileComponent as FileComponent$1, FileUploadComponent as FileUploadComponent$1, ForumChannel as ForumChannel$1, GroupDMChannel as GroupDMChannel$1, InteractiveButtonComponent as InteractiveButtonComponent$1, Invite, LinkButtonComponent as LinkButtonComponent$1, MediaChannel as MediaChannel$1, MediaGalleryComponent as MediaGalleryComponent$1, MediaGalleryItem as MediaGalleryItem$1, MentionableSelectMenuComponent as MentionableSelectMenuComponent$1, Message as Message$1, MessageFlagsBitField as MessageFlagsBitField$1, Partialize, PermissionsBitField, Poll as Poll$1, PollAnswer as PollAnswer$1, PremiumButtonComponent as PremiumButtonComponent$1, Presence as Presence$1, PrivateThreadChannel as PrivateThreadChannel$1, PublicThreadChannel as PublicThreadChannel$1, Reaction, RoleSelectMenuComponent as RoleSelectMenuComponent$1, SectionComponent as SectionComponent$1, SeparatorComponent as SeparatorComponent$1, SoundboardSound as SoundboardSound$1, StageChannel as StageChannel$1, StageInstance as StageInstance$1, Sticker as Sticker$1, StickerPack as StickerPack$1, StringSelectMenuComponent as StringSelectMenuComponent$1, Structure as Structure$1, TextChannel as TextChannel$1, TextDisplayComponent as TextDisplayComponent$1, TextInputComponent as TextInputComponent$1, ThumbnailComponent as ThumbnailComponent$1, UnfurledMediaItem as UnfurledMediaItem$1, User as User$1, UserSelectMenuComponent as UserSelectMenuComponent$1, VoiceChannel as VoiceChannel$1, VoiceState as VoiceState$1, Webhook as Webhook$1 } from "@discordjs/structures";
 import { BaseImageURLOptions, EmojiURLOptions, ImageURLOptions, REST, RawFile } from "@discordjs/rest";
+import { Collection, ReadonlyCollection } from "@discordjs/collection";
 //#region src/util/PermissionsBitField.d.ts
 /**
  * The name of any permission.
@@ -688,6 +689,229 @@ export declare class AutoModerationRule extends AutoModerationRule$1 {
   private editTrigger;
 }
 //#endregion
+//#region src/util/cache.d.ts
+/**
+ * The raw API data a {@link StructureMixin | structure} wraps.
+ */
+type RawAPIType<Value extends StructureMixin<object>> = Value extends StructureMixin<infer Type> ? Type : never;
+/**
+ * A function building a {@link StructureMixin | structure} out of its raw API data.
+ */
+type StructureCreator<Value extends StructureMixin<object>, Raw extends RawAPIType<Value> = RawAPIType<Value>> = (data: Partial<Raw>) => Value;
+/**
+ * Whether an {@link Awaitable} is a promise, rather than the value itself.
+ *
+ * @internal
+ */
+declare function isPromiseLike<T>(value: Awaitable<T>): value is Promise<T>;
+/**
+ * Waits for a list of {@link Awaitable}s like `Promise.all`, then calls a function with their values. Unlike
+ * `Promise.all`, it stays synchronous when none of them is a promise, which is what lets a synchronous cache build
+ * structures without awaiting them.
+ *
+ * @param values The values, some of which may be promises.
+ * @param callback The function to call with the values.
+ * @internal
+ */
+declare function whenAll<const T extends readonly unknown[], R>(values: T, callback: (values: { -readonly [Index in keyof T]: Awaited<T[Index]>; }) => Awaitable<R>): Awaitable<R>;
+/**
+ * Resolves the relations of a structure again from its current data, and assigns them to that same structure: what
+ * keeps a long-lived instance from holding the relations of the day it was built. Synchronous when `hydrate` is.
+ *
+ * @param value The structure.
+ * @param hydrate Builds a structure of the same data, with its relations.
+ * @returns The structure it was given.
+ * @internal
+ */
+declare function refreshRelations<Value extends StructureMixin<object>>(value: Value, hydrate: (data: RawAPIType<Value>) => Awaitable<StructureMixin<object>>): Awaitable<Value>;
+/**
+ * Picks the cached structures of some IDs, in their order, skipping the ones that are not cached: the equivalent of
+ * the collections discord.js fills from its caches, e.g. `MessageMentions#channels`.
+ *
+ * @param ids The IDs.
+ * @param cached The cached structures, by ID.
+ * @internal
+ */
+declare function pickCached<Value>(ids: readonly string[], cached: ReadonlyMap<string, Value> | undefined): Map<string, Value>;
+/**
+ * Reads the cached structures of some IDs, synchronously when every read is, skipping duplicates and the IDs that
+ * are not cached. The {@link Awaitable} counterpart of discord.js's collections filled from its caches.
+ *
+ * @param ids The IDs.
+ * @param get Reads the structure of an ID.
+ * @internal
+ */
+declare function whenCachedMap<Value>(ids: Iterable<string>, get: (id: string) => Awaitable<Value | null | undefined>): Awaitable<Map<string, Value>>;
+/**
+ * The cache of a manager, as in the discord.js RFC #11426: it hands out {@link StructureMixin | structures}.
+ *
+ * @remarks
+ * Every method is {@link Awaitable}: synchronous on an in-memory cache ({@link Cache.synchronous}), a promise on a
+ * remote one. `await` works with both.
+ *
+ * @typeParam Value The structure the cache hands out.
+ * @typeParam Raw The raw API data the structure wraps.
+ */
+interface Cache<Value extends StructureMixin<object>, Raw extends RawAPIType<Value> = RawAPIType<Value>> {
+  /**
+   * Whether every method answers synchronously, never with a promise.
+   */
+  readonly synchronous: boolean;
+  /**
+   * The function used to construct instances of the structure this cache holds.
+   */
+  readonly construct: StructureCreator<Value, Raw>;
+  /**
+   * Adds or updates data in the cache, returning the instantiated structure. If the item exists, it patches it with
+   * the new data unless `overwrite` is true. If it does not exist, it constructs a new instance and stores it.
+   */
+  add(data: Partial<Raw>, overwrite?: boolean): Awaitable<Value>;
+  /**
+   * Clears all items from the cache.
+   */
+  clear(): Awaitable<void>;
+  /**
+   * Deletes an item from the cache.
+   */
+  delete(key: string): Awaitable<boolean>;
+  /**
+   * Retrieves an item from the cache.
+   */
+  get(key: string): Awaitable<Value | undefined>;
+  /**
+   * Gets the number of items in the cache.
+   */
+  getSize(): Awaitable<number>;
+  /**
+   * Checks if an item exists in the cache.
+   */
+  has(key: string): Awaitable<boolean>;
+  /**
+   * Sets an item in the cache.
+   */
+  set(key: string, value: Value): Awaitable<this>;
+}
+/**
+ * The options of the cache of one entity, set per entity through the client's `cacheOptions` option.
+ */
+interface CacheEntityOptions {
+  /**
+   * The maximum amount of entries the cache holds, the oldest one being evicted when a new one would exceed it. `0`
+   * holds nothing.
+   *
+   * @default Infinity
+   */
+  maxSize?: number;
+}
+/**
+ * What a {@link CacheConstructor} receives as its third argument: how the client keys and refreshes the entity, and
+ * the entity's `cacheOptions`.
+ */
+interface CacheConstructorOptions<Value extends StructureMixin<object>, Raw extends RawAPIType<Value> = RawAPIType<Value>> extends CacheEntityOptions {
+  /**
+   * Gets the cache key of raw data. {@link Cache.add} must store under it: most entities are not keyed by their
+   * `id` alone (a member is keyed by its guild and user, a message by its channel and ID, ...).
+   */
+  keyOf: (data: Partial<Raw>) => string;
+  /**
+   * Resolves the relations of an instance again (e.g. `member.voice`), and returns that same instance. Call it on
+   * what {@link Cache.get} and {@link Cache.add} hand out, or long-lived instances keep the relations of the day
+   * they were built.
+   */
+  refresh: (value: Value) => Value;
+}
+/**
+ * A class building the {@link Cache} of an entity, as in the discord.js RFC #11426: what the client's
+ * `cacheConstructor` option takes. It is instantiated once per entity.
+ *
+ * @remarks
+ * The constructor receives `(creator, name, options)`:
+ *
+ * - `creator` builds a structure out of raw data, it is the cache's {@link Cache.construct};
+ * - `name` is the name of the entity, e.g. `"users"`;
+ * - `options` are the {@link CacheConstructorOptions}: `keyOf`, which `add` must key its entries with, `refresh`,
+ *   to call on what `get` and `add` hand out, and the entity's `cacheOptions` (`maxSize`).
+ *
+ * Extending `CollectionCache` and forwarding the three arguments to `super` is the recommended way: it does all of
+ * the above. The cache must be synchronous.
+ *
+ * A cache that is not a `Map` cannot be enumerated, so what needs to list its entries does not work with it: the
+ * dispatch cascades (`GUILD_DELETE` and `CHANNEL_DELETE` leave the entries of the guild or channel behind), the
+ * reconciliation of the guilds left while offline on `READY`, the granular emoji and sticker diff events, and
+ * `listCached`.
+ *
+ * @example
+ * ```typescript
+ * class LoggingCache<
+ *   Value extends StructureMixin<object>,
+ *   Raw extends RawAPIType<Value> = RawAPIType<Value>,
+ * > extends CollectionCache<Value, Raw> {
+ *   public override delete(key: string): boolean {
+ *     console.log(`${this.name}: ${key} removed`);
+ *     return super.delete(key);
+ *   }
+ * }
+ *
+ * const client = new GatewayClient({ intents, cacheConstructor: LoggingCache });
+ * ```
+ */
+type CacheConstructor = new <Value extends StructureMixin<object>>(creator: StructureCreator<Value>, name: CacheEntityName, options: CacheConstructorOptions<Value>) => Cache<Value>;
+/**
+ * Reads what a {@link Cache} holds under a key as is: for a cache of instances (a `Map`, e.g. `CollectionCache`), the
+ * instance itself, without re-resolving its relations as `get` does. Other caches are read with `get`.
+ *
+ * @param cache The cache.
+ * @param key The key of the entry.
+ * @internal
+ */
+declare function peekCache<Value extends StructureMixin<object>, Raw extends RawAPIType<Value> = RawAPIType<Value>>(cache: Cache<Value, Raw>, key: string): Awaitable<Value | undefined>;
+//#endregion
+//#region src/managers/BaseManager.d.ts
+/**
+ * Manages the API methods of a data model, like discord.js's `BaseManager`.
+ */
+export declare abstract class BaseManager {
+  /**
+   * The client that instantiated this manager.
+   */
+  readonly client: GatewayClient;
+  constructor(client: GatewayClient);
+}
+//#endregion
+//#region src/managers/DataManager.d.ts
+/**
+ * Manages the API methods of a data model along with a collection of instances, like discord.js's `DataManager`.
+ *
+ * @typeParam Value The structure this manager holds.
+ * @typeParam Args The arguments identifying an entity, e.g. `[id]` or `[guildId, userId]`.
+ */
+export declare abstract class DataManager<Value extends StructureMixin<object>, Args extends readonly string[]> extends BaseManager {
+  /**
+   * The cache of the items this manager holds.
+   */
+  abstract readonly cache: Cache<Value>;
+  /**
+   * Gets the cache key of an entity, the one {@link DataManager.cache} takes.
+   *
+   * @param args The arguments identifying the entity.
+   */
+  abstract resolveKey(...args: Args): string;
+  /**
+   * Resolves a structure or a cache key to a structure.
+   *
+   * @param value A structure, returned as is, or the cache key of an entity (its ID, for managers keyed by ID).
+   * @returns The structure, or `null` if the key is not cached.
+   */
+  resolve(value: Value | string): Awaitable<Value | null>;
+  /**
+   * Resolves a structure or an ID to an ID.
+   *
+   * @param value A structure, or an ID.
+   * @returns The ID, or `null` if the value is neither.
+   */
+  resolveId(value: Value | string): string | null;
+}
+//#endregion
 //#region src/managers/CachedManager.d.ts
 /**
  * The options to fetch an entity with.
@@ -713,117 +937,94 @@ export interface AddOptions {
   /**
    * The cache key of the entity, when it cannot be derived from its data.
    */
-  key?: string;
+  id?: string;
+  /**
+   * Extra arguments handed to the manager's `createStructure`.
+   */
+  extras?: unknown[];
 }
 /**
- * The base class of every manager, the `BaseManager` of the discord.js RFC #11426: it reads raw data from one of the
- * client's entity caches, falls back to the REST API when asked to, and wraps the result in a
- * {@link StructureMixin | structure} with {@link CachedManager.construct}.
+ * Manages the API methods of a data model with a mutable cache of instances: the `CachedManager` of the discord.js
+ * RFC #11426.
  *
  * @remarks
- * The cache only ever holds raw API data, building structures is always the manager's job. Without a store for its
- * entity (see the client's `makeCache`), `get` always resolves to `undefined` and `fetch` always hits the API.
- *
- * A failing store (e.g. Redis being unreachable) emits `cacheError` and, with the client's default
- * `cacheErrors: "miss"`, is treated as a cache miss.
- *
- * Every method is asynchronous since the cache can be Redis, except {@link CachedManager.cached}, which reads a
- * synchronous cache (`createInMemoryCache`) without awaiting it.
+ * Reads go through {@link CachedManager.cache}: `client.users.cache.get(id)`. The cache is built by the client's
+ * `cacheConstructor` (`CollectionCache` by default) and shared by every manager of the same entity.
  *
- * Like discord.js's `CachedManager`, every payload coming from the API goes through {@link CachedManager._add}, which
- * patches the cached entry and builds the structure. Structures are built by {@link CachedManager.hydrate}, which
- * resolves their relations (a message's author, a member's user, ...) from the cache, so they carry the latest known
- * data rather than the copy embedded in the payload.
+ * Caches keyed by more than an ID take the key built by `resolveKey`:
+ * `client.members.cache.get(client.members.resolveKey(guildId, userId))`.
  *
- * @typeParam Name The name of the entity cache this manager reads from.
+ * @typeParam Name The name of the entity this manager holds.
  * @typeParam Value The structure this manager builds.
  * @typeParam Args The arguments identifying an entity, e.g. `[id]` or `[guildId, userId]`.
  */
-export declare abstract class CachedManager<Name extends CacheEntityName, Value extends StructureMixin<object>, Args extends readonly string[]> {
-  /**
-   * The client this manager belongs to.
-   */
-  readonly client: GatewayClient;
+export declare abstract class CachedManager<Name extends CacheEntityName, Value extends StructureMixin<object>, Args extends readonly string[]> extends DataManager<Value, Args> {
   /**
-   * The name of the entity cache this manager reads from.
-   */
-  readonly entity: Name;
-  constructor(client: GatewayClient, entity: Name);
-  /**
-   * The entity cache this manager reads from, or `undefined` when the client has no cache.
-   */
-  get cache(): EntityCache<CacheEntityTypes[Name]> | undefined;
-  /**
-   * Gets an entity from the cache.
-   *
-   * @param args The arguments identifying the entity.
-   * @returns The entity, or `undefined` if it is not cached.
-   */
-  get(...args: Args): Promise<Value | undefined>;
-  /**
-   * Gets an entity from a synchronous cache, without awaiting it: the synchronous counterpart of
-   * {@link CachedManager.get}, for hot paths such as message filters.
-   *
-   * @remarks
-   * It builds the same structure as `get`, relations included, so the entity caches they are read from must be
-   * synchronous too, which they all are with `createInMemoryCache`. `manager.cache?.synchronous` tells whether it can
-   * be called.
-   *
-   * An asynchronous cache throws rather than returning `undefined`: it cannot tell whether the entity is cached, and
-   * reporting a miss would silently skip whatever the caller does with cached entities, e.g. a filter.
+   * The cache of this manager's entity.
    *
    * @example
    * ```typescript
-   * const member = client.members.cached(guildId, userId);
+   * const user = await client.users.cache.get(userId);
    * ```
-   *
-   * @param args The arguments identifying the entity.
-   * @returns The entity, or `undefined` if it is not cached or the client has no cache.
-   * @throws {TypeError} When the entity cache, or one of the caches its relations are read from, is asynchronous.
    */
-  cached(...args: Args): Value | undefined;
+  readonly cache: Cache<Value>;
   /**
-   * Gets an entity from the cache, synchronously when every cache it reads is: the {@link Awaitable} counterpart of
-   * {@link CachedManager.get}, which both `get` and {@link CachedManager.cached} rely on.
-   *
-   * @param args The arguments identifying the entity.
-   * @internal
+   * The name of the entity this manager holds.
    */
-  _get(...args: Args): Awaitable<Value | undefined>;
+  protected readonly name: Name;
   /**
-   * Resolves a structure or a cache key to a structure, like discord.js's `DataManager#resolve`.
+   * Wraps raw data in this manager's structure: the RFC's `StructureCreator`.
    *
-   * @param value A structure, returned as is, or the cache key of an entity (its ID, for managers keyed by ID).
-   * @returns The structure, or `null` if the key is not cached.
+   * @param data The raw data.
+   * @param extras The extra arguments passed to {@link CachedManager._add}.
+   */
+  protected abstract createStructure(data: CacheEntityTypes[Name], ...extras: unknown[]): Value;
+  constructor(client: GatewayClient, name: Name);
+  /**
+   * Gets {@link CachedManager.cache} from the client. Managers whose entity spans several caches override it.
    */
-  resolve(value: Value | string): Promise<Value | null>;
+  protected createCache(): Cache<Value>;
   /**
-   * Adds an API payload to the cache, patching the cached entry with it, and builds its structure. The counterpart of
-   * discord.js's `CachedManager#_add`, asynchronous since the cache can be remote.
+   * The raw store of this manager's entity, or `undefined` when it is not cached.
+   */
+  protected get rawStore(): EntityCache<CacheEntityTypes[Name]> | undefined;
+  /**
+   * Adds an API payload to the cache and returns its structure, as in the RFC.
    *
    * @remarks
-   * Like discord.js's `_patch`, the payload is shallowly merged into the cached entry, so the fields a partial payload
-   * lacks keep their cached value. With `cache` set to `false`, the merged entry is built but not written.
+   * The payload is written with `cache.add`: a cached entry is patched and returned, and with a cache of instances
+   * (`CollectionCache`) that is the very instance the application may already hold. An entity that is not cached is
+   * built and stored.
    *
-   * The merge is a read followed by a write, not an atomic operation: on a shared cache, a write landing in between
-   * (another process, or a dispatch outside the guild's queue) is overwritten. `@wolfstar/plugin-cache` merges partial
-   * dispatches the same way, and the fields at stake are refreshed by the next payload of the entity.
+   * With `cache` set to `false`, a patched clone is returned (or the entity is built) and the cache is left
+   * untouched. The same goes for an entry the `filter` of the entity's policy rejects, whose cached entry is deleted
+   * on top of that: a rejected update must not leave the outdated entry behind.
    *
    * @param data The raw data.
-   * @param cache Whether to write the merged entry to the cache.
-   * @param options The cache key, when it cannot be derived from the data.
+   * @param cache Whether to write to the cache.
+   * @param options The cache key, when it cannot be derived from the data, and the extras of `createStructure`.
    * @internal
    */
-  _add(data: CacheEntityTypes[Name], cache?: boolean, { key }?: AddOptions): Promise<Value>;
+  _add(data: CacheEntityTypes[Name], cache?: boolean, { id, extras }?: AddOptions): Promise<Value>;
   /**
-   * Gets the cached structure of the entity raw data describes, or builds one from the data when it is not cached.
-   * Used to resolve the relations of other structures, e.g. a message's author.
+   * Patches the cached entry of a key, if any, with the fields an endpoint answered without the entity itself.
    *
-   * @param data The raw data.
+   * @remarks
+   * Like every write of the managers, it follows the `filter` of the entity's policy: an entry whose patched data is
+   * rejected is deleted from the cache.
+   *
+   * @param key The cache key of the entry.
+   * @param patch The fields to patch, or a function computing them from the cached entry, `undefined` to leave it.
+   * @internal
    */
-  resolveData(data: CacheEntityTypes[Name]): Promise<Value>;
+  _patchCached(key: string, patch: Partial<CacheEntityTypes[Name]> | ((cached: Value) => Partial<CacheEntityTypes[Name]> | undefined)): Promise<void>;
+  private accepts;
+  private detached;
+  private derivedKey;
+  private resolveRelations;
   /**
-   * The {@link Awaitable} counterpart of {@link CachedManager.resolveData}, synchronous when every cache it reads is.
+   * Gets the cached structure of the entity raw data describes, or builds one from the data when it is not cached.
+   * Used to resolve the relations of other structures, e.g. a message's author. Synchronous when the cache is.
    *
    * @param data The raw data.
    * @internal
@@ -832,29 +1033,39 @@ export declare abstract class CachedManager<Name extends CacheEntityName, Value
   /**
    * Gets a guild from the cache, to resolve the `guild` of a structure. Synchronous when the guild cache is.
    *
-   * @param guildId The ID of the guild, if the structure belongs to one.
    * @remarks
    * The guild does not resolve its own channel relations, see `GuildManager._getShallow`.
    *
+   * @param guildId The ID of the guild, if the structure belongs to one.
    * @returns The guild, or `null` when there is no ID or the guild is not cached.
    */
   protected cachedGuild(guildId: string | null | undefined): Awaitable<Guild | null>;
   /**
-   * Builds the structure of raw data, resolving its relations from the cache. Without relations to resolve, the same
-   * as {@link CachedManager.construct}.
+   * Builds the structure of raw data, resolving its relations from the cache; synchronous when every cache the
+   * relations are read from is. Without relations to resolve, the same as `createStructure`.
+   *
+   * @param data The raw data.
+   * @param extras The extra arguments passed to {@link CachedManager._add}.
+   * @internal
+   */
+  _hydrate(data: CacheEntityTypes[Name], ...extras: unknown[]): Awaitable<Value>;
+  /**
+   * Wraps raw data in this manager's structure, bound to this manager's client, without resolving its relations: the
+   * creator handed to this entity's cache, always synchronous.
    *
    * @param data The raw data.
+   * @param extras The extra arguments passed to {@link CachedManager._add}.
+   * @internal
    */
-  hydrate(data: CacheEntityTypes[Name]): Promise<Value>;
+  _construct(data: CacheEntityTypes[Name], ...extras: unknown[]): Value;
   /**
-   * The {@link Awaitable} counterpart of {@link CachedManager.hydrate}, synchronous when every cache the relations
-   * are read from is. Managers resolving relations override this one, so `hydrate` and
-   * {@link CachedManager.cached} build the same structures.
+   * Builds the structure of raw data with {@link CachedManager._hydrate}, bound to this manager's client.
    *
    * @param data The raw data.
+   * @param extras The extra arguments passed to {@link CachedManager._add}.
    * @internal
    */
-  _hydrate(data: CacheEntityTypes[Name]): Awaitable<Value>;
+  _build(data: CacheEntityTypes[Name], extras?: unknown[]): Awaitable<Value>;
   /**
    * Gets an entity from the cache, fetching it from the API (and caching it) on a cache miss.
    *
@@ -874,32 +1085,12 @@ export declare abstract class CachedManager<Name extends CacheEntityName, Value
    * @param args The arguments identifying the entity.
    */
   refresh(...args: Args): Promise<Value>;
-  /**
-   * Wraps raw data in this manager's structure: the RFC's `StructureCreator`, which lives on the manager since the
-   * cache only holds raw data.
-   *
-   * @param data The raw data.
-   */
-  abstract construct(data: CacheEntityTypes[Name]): Value;
-  /**
-   * Wraps raw data in this manager's structure.
-   *
-   * @param data The raw data.
-   * @deprecated Use {@link CachedManager.construct}.
-   */
-  createStructure(data: CacheEntityTypes[Name]): Value;
   /**
    * Gets the cache key of raw data.
    *
    * @param data The raw data.
    */
   abstract keyOf(data: CacheEntityTypes[Name]): string;
-  /**
-   * Gets the cache key of an entity.
-   *
-   * @param args The arguments identifying the entity.
-   */
-  abstract resolveKey(...args: Args): string;
   /**
    * Fetches the raw data of an entity from the API.
    *
@@ -907,41 +1098,17 @@ export declare abstract class CachedManager<Name extends CacheEntityName, Value
    */
   protected abstract fetchRaw(...args: Args): Promise<CacheEntityTypes[Name]>;
   /**
-   * Writes raw data to the cache.
-   *
-   * @param key The cache key of the entity.
-   * @param raw The raw data of the entity.
-   */
-  protected storeRaw(key: string, raw: CacheEntityTypes[Name]): Promise<void>;
-  /**
-   * Gets this manager's store when it can enumerate its entries, for the `listCached` methods.
+   * Gets this entity's raw store when it can enumerate its entries, for the `listCached` methods.
    *
    * @returns The store, or `undefined` when this entity is not cached.
    * @throws {TypeError} When the store cannot enumerate its entries.
    */
   protected iterableCache(): IterableEntityCache<CacheEntityTypes[Name]> | undefined;
   /**
-   * Gets an entity from the cache by its key, synchronously when every cache it reads is.
-   *
-   * @param key The cache key of the entity.
-   */
-  protected getByKey(key: string): Awaitable<Value | undefined>;
-  /**
-   * Runs a cache operation, reporting its failure through `cacheError`. With the client's `cacheErrors: "miss"`, a
-   * failure resolves to `fallback`, otherwise it is rethrown. Synchronous when the operation is.
-   *
-   * @param operation The operation, for `cacheError`.
-   * @param key The key of the entry, for `cacheError`.
-   * @param run Runs the operation.
-   * @param fallback What a failure resolves to under `cacheErrors: "miss"`.
+   * Runs a raw store operation, reporting its failure through `cacheError`. With the client's `cacheErrors: "miss"`,
+   * a failure resolves to `fallback`, otherwise it is rethrown. Synchronous when the operation is.
    */
   protected guard<T>(operation: CacheErrorContext["operation"], key: string | null, run: () => Awaitable<T>, fallback: T): Awaitable<T>;
-  /**
-   * Builds the structure of raw data with {@link CachedManager._hydrate}, bound to this manager's client.
-   *
-   * @param data The raw data.
-   */
-  protected build(data: CacheEntityTypes[Name]): Awaitable<Value>;
 }
 //#endregion
 //#region src/managers/AutoModerationRuleManager.d.ts
@@ -979,7 +1146,7 @@ export interface AutoModerationRuleCreateOptions extends AutoModerationRuleEditO
 export declare class AutoModerationRuleManager extends CachedManager<"autoModerationRules", AutoModerationRule, [ruleId: string]> {
   readonly guildId: string;
   constructor(client: GatewayClient, guildId: string);
-  construct(data: CacheEntityTypes["autoModerationRules"]): AutoModerationRule;
+  protected createStructure(data: CacheEntityTypes["autoModerationRules"]): AutoModerationRule;
   keyOf(data: CacheEntityTypes["autoModerationRules"]): string;
   resolveKey(ruleId: string): string;
   _hydrate(data: CacheEntityTypes["autoModerationRules"]): Awaitable<AutoModerationRule>;
@@ -1085,8 +1252,7 @@ export interface ChannelPosition {
 /**
  * Manages the channels of one guild. Channels are cached by `client.channels`, which this manager writes to.
  */
-export declare class GuildChannelManager {
-  readonly client: GatewayClient;
+export declare class GuildChannelManager extends BaseManager {
   readonly guildId: string;
   constructor(client: GatewayClient, guildId: string);
   /**
@@ -1458,7 +1624,7 @@ export interface ThreadMemberListOptions {
  */
 export declare class ThreadMemberManager extends CachedManager<"threadMembers", ThreadMember, [threadId: string, userId: string]> {
   constructor(client: GatewayClient);
-  construct(data: CacheEntityTypes["threadMembers"]): ThreadMember;
+  protected createStructure(data: CacheEntityTypes["threadMembers"]): ThreadMember;
   keyOf(data: CacheEntityTypes["threadMembers"]): string;
   resolveKey(threadId: string, userId: string): string;
   /**
@@ -1510,8 +1676,7 @@ export declare class ThreadMemberManager extends CachedManager<"threadMembers",
 /**
  * Manages the members of one thread: `client.threadMembers`, with the thread's ID filled in.
  */
-export declare class ThreadChannelMemberManager {
-  readonly client: GatewayClient;
+export declare class ThreadChannelMemberManager extends BaseManager {
   readonly threadId: string;
   constructor(client: GatewayClient, threadId: string);
   /**
@@ -1706,7 +1871,7 @@ export interface FetchedThreads {
  */
 export declare class ThreadManager extends CachedManager<"threads", AnyThreadChannel, [threadId: string]> {
   constructor(client: GatewayClient);
-  construct(data: CacheEntityTypes["threads"]): AnyThreadChannel;
+  protected createStructure(data: CacheEntityTypes["threads"]): AnyThreadChannel;
   keyOf(data: CacheEntityTypes["threads"]): string;
   _hydrate(data: CacheEntityTypes["threads"]): Awaitable<AnyThreadChannel>;
   resolveKey(threadId: string): string;
@@ -1771,7 +1936,7 @@ export interface PinnedMessage {
  */
 export declare class MessageManager extends CachedManager<"messages", Message, [channelId: string, messageId: string]> {
   constructor(client: GatewayClient);
-  construct(data: CacheEntityTypes["messages"]): Message;
+  protected createStructure(data: CacheEntityTypes["messages"]): Message;
   keyOf(data: CacheEntityTypes["messages"]): string;
   /**
    * Adds a message to the cache, its author to `client.users` (unless a webhook sent it), and its member to
@@ -1919,9 +2084,14 @@ export declare class MessageManager extends CachedManager<"messages", Message, [
   }): Promise<User[]>;
   protected fetchRaw(channelId: string, messageId: string): Promise<APIMessage>;
   private store;
-  private patchCached;
 }
 //#endregion
+//#region src/util/roles.d.ts
+/**
+ * Several roles: an array of {@link RoleResolvable}s, or a `Collection` of roles, as discord.js takes them.
+ */
+type RoleResolvables = readonly RoleResolvable[] | ReadonlyCollection<Snowflake, Role>;
+//#endregion
 //#region src/managers/GuildEmojiManager.d.ts
 /**
  * The options to create an emoji with.
@@ -1934,9 +2104,9 @@ export interface GuildEmojiCreateOptions {
   attachment: ImageResolvable;
   name: string;
   /**
-   * The IDs of the roles allowed to use the emoji, everyone when omitted.
+   * The roles allowed to use the emoji, everyone when omitted: an array of roles or IDs, or a `Collection` of roles.
    */
-  roles?: readonly string[];
+  roles?: RoleResolvables;
   reason?: string;
 }
 /**
@@ -1945,9 +2115,10 @@ export interface GuildEmojiCreateOptions {
 export interface GuildEmojiEditOptions {
   name?: string;
   /**
-   * The IDs of the roles allowed to use the emoji, `null` or empty for everyone.
+   * The roles allowed to use the emoji, `null` or empty for everyone: an array of roles or IDs, or a `Collection`
+   * of roles.
    */
-  roles?: readonly string[] | null;
+  roles?: RoleResolvables | null;
   reason?: string;
 }
 /**
@@ -1959,7 +2130,7 @@ export declare class GuildEmojiManager extends CachedManager<"emojis", GuildEmoj
    */
   readonly guildId: string;
   constructor(client: GatewayClient, guildId: string);
-  construct(data: CacheEntityTypes["emojis"]): GuildEmoji;
+  protected createStructure(data: CacheEntityTypes["emojis"]): GuildEmoji;
   keyOf(data: CacheEntityTypes["emojis"]): string;
   /**
    * Adds an emoji to the cache, and its uploader to `client.users`.
@@ -2026,18 +2197,37 @@ export declare class GuildEmojiManager extends CachedManager<"emojis", GuildEmoj
 //#endregion
 //#region src/managers/GuildEmojiRoleManager.d.ts
 /**
- * Manages the roles allowed to use one custom emoji. When it has none, everyone can use it.
+ * Manages the roles allowed to use one custom emoji, like discord.js's `GuildEmojiRoleManager`. When it has none,
+ * everyone can use it.
+ *
+ * @remarks
+ * {@link GuildEmojiRoleManager.cache} is `Awaitable`, unlike discord.js's: synchronous with the default in-memory
+ * cache, a promise with a remote store.
  */
-export declare class GuildEmojiRoleManager {
-  #private;
-  readonly client: GatewayClient;
-  readonly guildId: string;
-  readonly emojiId: string;
-  constructor(client: GatewayClient, guildId: string, emojiId: string, roleIds: readonly string[]);
+export declare class GuildEmojiRoleManager extends BaseManager {
+  /**
+   * The emoji these roles belong to.
+   */
+  readonly emoji: GuildEmoji;
+  /**
+   * @param emoji The emoji.
+   */
+  constructor(emoji: GuildEmoji);
+  /**
+   * The emoji's guild, from the cache: `null` when it is not cached.
+   */
+  get guild(): Guild | null;
+  get guildId(): string;
+  get emojiId(): string;
   /**
    * The IDs of the allowed roles.
    */
   get ids(): readonly string[];
+  /**
+   * The allowed roles held in the cache, by ID. Roles that are not cached are skipped: use
+   * {@link GuildEmojiRoleManager.fetch} to get them all.
+   */
+  get cache(): Awaitable<Collection<Snowflake, Role>>;
   /**
    * Fetches the allowed roles, cache first.
    */
@@ -2045,21 +2235,29 @@ export declare class GuildEmojiRoleManager {
   /**
    * Allows more roles to use the emoji.
    *
-   * @param roles The ID of the role, or several IDs.
+   * @param roleOrRoles The role or its ID, or an array or `Collection` of them.
+   * @returns The emoji, patched.
    */
-  add(roles: string | readonly string[]): Promise<GuildEmoji>;
+  add(roleOrRoles: RoleResolvable | RoleResolvables): Promise<GuildEmoji>;
   /**
    * Stops allowing roles to use the emoji.
    *
-   * @param roles The ID of the role, or several IDs.
+   * @param roleOrRoles The role or its ID, or an array or `Collection` of them.
+   * @returns The emoji, patched.
    */
-  remove(roles: string | readonly string[]): Promise<GuildEmoji>;
+  remove(roleOrRoles: RoleResolvable | RoleResolvables): Promise<GuildEmoji>;
   /**
    * Replaces the allowed roles, everyone when empty.
    *
-   * @param roles The IDs of the roles.
+   * @param roles The roles: an array of roles or IDs, or a `Collection` of roles.
+   * @returns The emoji, patched.
    */
-  set(roles: readonly string[]): Promise<GuildEmoji>;
+  set(roles: RoleResolvables): Promise<GuildEmoji>;
+  /**
+   * Creates another manager of the same emoji's roles.
+   */
+  clone(): GuildEmojiRoleManager;
+  private resolve;
 }
 //#endregion
 //#region src/structures/emojis/GuildEmoji.d.ts
@@ -2134,8 +2332,7 @@ export declare class GuildEmoji extends Emoji<CacheEntityTypes["emojis"], GuildE
 /**
  * Manages the users who reacted to a message with one emoji.
  */
-export declare class ReactionUserManager {
-  readonly client: GatewayClient;
+export declare class ReactionUserManager extends BaseManager {
   readonly channelId: string;
   readonly messageId: string;
   /**
@@ -2267,9 +2464,8 @@ export declare class MessageReaction extends Reaction<"count" | "count_details">
 /**
  * Manages the reactions of one message, as they were in the message's payload.
  */
-export declare class ReactionManager {
+export declare class ReactionManager extends BaseManager {
   #private;
-  readonly client: GatewayClient;
   readonly channelId: string;
   readonly messageId: string;
   /**
@@ -3532,8 +3728,7 @@ export declare class Message extends Message$1<""> {
 /**
  * Manages the messages of one channel: `client.messages`, with the channel's ID filled in.
  */
-export declare class ChannelMessageManager {
-  readonly client: GatewayClient;
+export declare class ChannelMessageManager extends BaseManager {
   readonly channelId: string;
   constructor(client: GatewayClient, channelId: string);
   /**
@@ -3702,9 +3897,8 @@ export interface PermissionOverwriteEditOptions {
 /**
  * Manages the permission overwrites of one channel, as they were in the channel's payload.
  */
-export declare class PermissionOverwriteManager {
+export declare class PermissionOverwriteManager extends BaseManager {
   #private;
-  readonly client: GatewayClient;
   readonly channelId: string;
   readonly guildId: string | null;
   /**
@@ -3831,8 +4025,7 @@ export declare class CategoryChannel extends CategoryChannel$1 {
 /**
  * Manages the threads of one channel: `client.threads`, with the channel's ID filled in.
  */
-export declare class ChannelThreadManager {
-  readonly client: GatewayClient;
+export declare class ChannelThreadManager extends BaseManager {
   readonly channelId: string;
   readonly guildId: string | null;
   constructor(client: GatewayClient, channelId: string, guildId: string | null);
@@ -4036,8 +4229,7 @@ export interface WebhookEditOptions {
  * Methods taking a webhook's token call the API with it rather than with the bot's authorization, so they work for
  * webhooks of other applications too.
  */
-export declare class WebhookManager {
-  readonly client: GatewayClient;
+export declare class WebhookManager extends BaseManager {
   constructor(client: GatewayClient);
   /**
    * Fetches a webhook.
@@ -4314,7 +4506,7 @@ export interface GuildScheduledEventSubscriber {
 export declare class GuildScheduledEventManager extends CachedManager<"scheduledEvents", GuildScheduledEvent, [eventId: string]> {
   readonly guildId: string;
   constructor(client: GatewayClient, guildId: string);
-  construct(data: CacheEntityTypes["scheduledEvents"]): GuildScheduledEvent;
+  protected createStructure(data: CacheEntityTypes["scheduledEvents"]): GuildScheduledEvent;
   keyOf(data: CacheEntityTypes["scheduledEvents"]): string;
   resolveKey(eventId: string): string;
   /**
@@ -4545,7 +4737,7 @@ export interface StageInstanceCreateOptions extends StageInstanceEditOptions {
 export declare class StageInstanceManager extends CachedManager<"stageInstances", StageInstance, [channelId: string]> {
   readonly guildId: string;
   constructor(client: GatewayClient, guildId: string);
-  construct(data: CacheEntityTypes["stageInstances"]): StageInstance;
+  protected createStructure(data: CacheEntityTypes["stageInstances"]): StageInstance;
   keyOf(data: CacheEntityTypes["stageInstances"]): string;
   resolveKey(channelId: string): string;
   _hydrate(data: CacheEntityTypes["stageInstances"]): Awaitable<StageInstance>;
@@ -4686,7 +4878,7 @@ export interface SoundboardSoundCreateOptions extends SoundboardSoundEditOptions
 export declare class GuildSoundboardSoundManager extends CachedManager<"soundboardSounds", SoundboardSound, [soundId: string]> {
   readonly guildId: string;
   constructor(client: GatewayClient, guildId: string);
-  construct(data: CacheEntityTypes["soundboardSounds"]): SoundboardSound;
+  protected createStructure(data: CacheEntityTypes["soundboardSounds"]): SoundboardSound;
   keyOf(data: CacheEntityTypes["soundboardSounds"]): string;
   resolveKey(soundId: string): string;
   /**
@@ -5215,7 +5407,7 @@ export declare class GuildStickerManager extends CachedManager<"stickers", Stick
    */
   readonly guildId: string;
   constructor(client: GatewayClient, guildId: string);
-  construct(data: CacheEntityTypes["stickers"]): Sticker;
+  protected createStructure(data: CacheEntityTypes["stickers"]): Sticker;
   keyOf(data: CacheEntityTypes["stickers"]): string;
   /**
    * Adds a sticker to the cache, and its uploader to `client.users`.
@@ -5776,7 +5968,7 @@ export interface RolePosition {
  */
 export declare class RoleManager extends CachedManager<"roles", Role, [guildId: string, roleId: string]> {
   constructor(client: GatewayClient);
-  construct(data: CacheEntityTypes["roles"]): Role;
+  protected createStructure(data: CacheEntityTypes["roles"]): Role;
   keyOf(data: CacheEntityTypes["roles"]): string;
   _hydrate(data: CacheEntityTypes["roles"]): Awaitable<Role>;
   resolveKey(guildId: string, roleId: string): string;
@@ -6019,28 +6211,68 @@ export declare class Role<Omitted extends keyof CacheEntityTypes["roles"] | "" =
 //#endregion
 //#region src/managers/GuildMemberRoleManager.d.ts
 /**
- * Manages the roles of one {@link GuildMember}, reading them through the client's role manager.
+ * Manages the roles of one {@link GuildMember}, like discord.js's `GuildMemberRoleManager`.
  *
  * @remarks
- * discord.js's synchronous `member.roles.cache`, `highest`, `color`, ... become the `fetch*` methods here: the roles
- * are read from the (possibly asynchronous) cache, falling back to the API.
+ * The one deliberate difference from discord.js: {@link GuildMemberRoleManager.cache} and the getters reading it
+ * (`highest`, `hoist`, `color`, ...) are `Awaitable`, like `manager.cache.get`. They are synchronous with the default
+ * in-memory cache and a promise with a remote store, so `await` works with both.
+ *
+ * They only know the roles the cache holds. The `fetch*` methods fall back to the API when a role is not cached.
  */
-export declare class GuildMemberRoleManager {
-  #private;
-  readonly client: GatewayClient;
-  readonly guildId: string;
-  readonly userId: string;
+export declare class GuildMemberRoleManager extends BaseManager {
   /**
-   * @param client The client.
-   * @param guildId The ID of the guild.
-   * @param userId The ID of the member's user.
-   * @param roleIds The IDs of the member's roles, as known to the member structure.
+   * The member these roles belong to.
+   */
+  readonly member: GuildMember;
+  /**
+   * @param member The member.
+   */
+  constructor(member: GuildMember);
+  /**
+   * The member's guild, from the cache: `null` when it is not cached.
+   */
+  get guild(): Guild | null;
+  get guildId(): string;
+  /**
+   * The ID of the member's user.
+   *
+   * @throws {GatewayError} `GuildMemberUserUnknown` when the member's payload did not include its user.
    */
-  constructor(client: GatewayClient, guildId: string, userId: string, roleIds: readonly string[]);
+  get userId(): string;
   /**
    * The IDs of the member's roles, `@everyone` excluded.
    */
   get ids(): readonly string[];
+  /**
+   * The member's roles held in the cache, by ID, `@everyone` included. Roles that are not cached are skipped: use
+   * {@link GuildMemberRoleManager.fetch} to get them all.
+   */
+  get cache(): Awaitable<Collection<Snowflake, Role>>;
+  /**
+   * The member's highest cached role. `null` when none of their roles is cached, `@everyone` included.
+   */
+  get highest(): Awaitable<Role | null>;
+  /**
+   * The cached role the member is displayed under in the member list, if any.
+   */
+  get hoist(): Awaitable<Role | null>;
+  /**
+   * The highest cached role giving the member a color, if any.
+   */
+  get color(): Awaitable<Role | null>;
+  /**
+   * The highest cached role giving the member an icon, if any.
+   */
+  get icon(): Awaitable<Role | null>;
+  /**
+   * The server booster role, if the member has it and it is cached.
+   */
+  get premiumSubscriberRole(): Awaitable<Role | null>;
+  /**
+   * The role Discord manages for the member, when the member is a bot and the role is cached.
+   */
+  get botRole(): Awaitable<Role | null>;
   /**
    * Fetches the member's roles, `@everyone` included, highest first.
    */
@@ -6070,26 +6302,43 @@ export declare class GuildMemberRoleManager {
    */
   fetchBotRole(): Promise<Role | null>;
   /**
-   * Adds roles to the member.
+   * Adds a role, or several, to the member.
+   *
+   * @remarks
+   * A single role goes through its own endpoint and resolves to a copy of the member with the role added. Several
+   * roles replace the member's roles, like {@link GuildMemberRoleManager.set}.
    *
-   * @param roles The ID of the role, or several IDs.
+   * @param roleOrRoles The role or its ID, or an array or `Collection` of them.
    * @param reason The reason for the audit log.
+   * @returns The updated member.
    */
-  add(roles: string | readonly string[], reason?: string): Promise<void | GuildMember>;
+  add(roleOrRoles: RoleResolvable | RoleResolvables, reason?: string): Promise<GuildMember>;
   /**
-   * Removes roles from the member.
+   * Removes a role, or several, from the member.
    *
-   * @param roles The ID of the role, or several IDs.
+   * @remarks
+   * A single role goes through its own endpoint and resolves to a copy of the member with the role removed. Several
+   * roles replace the member's roles, like {@link GuildMemberRoleManager.set}.
+   *
+   * @param roleOrRoles The role or its ID, or an array or `Collection` of them.
    * @param reason The reason for the audit log.
+   * @returns The updated member.
    */
-  remove(roles: string | readonly string[], reason?: string): Promise<void | GuildMember>;
+  remove(roleOrRoles: RoleResolvable | RoleResolvables, reason?: string): Promise<GuildMember>;
   /**
    * Replaces the member's roles.
    *
-   * @param roles The IDs of the roles the member ends up with.
+   * @param roles The roles the member ends up with: an array of roles or IDs, or a `Collection` of roles.
    * @param reason The reason for the audit log.
+   * @returns The member, patched.
+   */
+  set(roles: RoleResolvables, reason?: string): Promise<GuildMember>;
+  /**
+   * Creates another manager of the same member's roles.
    */
-  set(roles: readonly string[], reason?: string): Promise<GuildMember>;
+  clone(): GuildMemberRoleManager;
+  private fromCache;
+  private resolveSingle;
 }
 //#endregion
 //#region src/structures/voice/VoiceState.d.ts
@@ -6268,7 +6517,7 @@ export declare class GuildMember extends Structure<CacheEntityTypes["members"]>
    */
   get roleIds(): readonly string[];
   /**
-   * The member's roles. It needs the member's user ID, which every payload but some partial ones carries.
+   * The member's roles. Changing them needs the member's user ID, which every payload but some partial ones carries.
    */
   get roles(): GuildMemberRoleManager;
   get joinedTimestamp(): number | null;
@@ -6416,7 +6665,12 @@ export declare class GuildMember extends Structure<CacheEntityTypes["members"]>
   timeout(duration: number | null, reason?: string): Promise<this>;
   kick(reason?: string): Promise<this>;
   ban(options?: BanOptions): Promise<this>;
-  createDM(): Promise<DMChannel>;
+  /**
+   * Opens a direct message channel with the member, reusing the cached one.
+   *
+   * @param force Whether to skip the cache lookup and always call the API.
+   */
+  createDM(force?: boolean): Promise<DMChannel>;
   deleteDM(): Promise<DMChannel>;
   send(options: MessagePayloadResolvable<MessageCreateOptions>): Promise<Message>;
   /**
@@ -6453,9 +6707,9 @@ export interface GuildMemberEditOptions {
    */
   nick?: string | null;
   /**
-   * The IDs of the roles the member ends up with.
+   * The roles the member ends up with: an array of roles or IDs, or a `Collection` of roles.
    */
-  roles?: readonly string[];
+  roles?: RoleResolvables;
   mute?: boolean;
   deaf?: boolean;
   /**
@@ -6489,7 +6743,10 @@ export interface GuildMemberEditMeOptions {
 export interface GuildMemberAddOptions {
   accessToken: string;
   nick?: string;
-  roles?: readonly string[];
+  /**
+   * The roles the member starts with: an array of roles or IDs, or a `Collection` of roles.
+   */
+  roles?: RoleResolvables;
   mute?: boolean;
   deaf?: boolean;
 }
@@ -6579,7 +6836,7 @@ export interface GuildMembersRequestOptions {
 export declare class GuildMemberManager extends CachedManager<"members", GuildMember, [guildId: string, userId: string]> {
   #private;
   constructor(client: GatewayClient);
-  construct(data: CacheEntityTypes["members"]): GuildMember;
+  protected createStructure(data: CacheEntityTypes["members"]): GuildMember;
   keyOf(data: CacheEntityTypes["members"]): string;
   /**
    * Adds a member to the cache, and its user to `client.users`.
@@ -6597,6 +6854,7 @@ export declare class GuildMemberManager extends CachedManager<"members", GuildMe
    * @internal
    */
   _hydrate(data: CacheEntityTypes["members"]): Awaitable<GuildMember>;
+  private readRelation;
   resolveKey(guildId: string, userId: string): string;
   /**
    * Fetches the bot's own member in a guild.
@@ -6778,7 +7036,7 @@ export interface GuildBanListOptions {
 export declare class GuildBanManager extends CachedManager<"bans", GuildBan, [userId: string]> {
   readonly guildId: string;
   constructor(client: GatewayClient, guildId: string);
-  construct(data: CacheEntityTypes["bans"]): GuildBan;
+  protected createStructure(data: CacheEntityTypes["bans"]): GuildBan;
   keyOf(data: CacheEntityTypes["bans"]): string;
   resolveKey(userId: string): string;
   /**
@@ -6907,7 +7165,7 @@ export declare class Integration extends Structure<CacheEntityTypes["integration
 export declare class GuildIntegrationManager extends CachedManager<"integrations", Integration, [integrationId: string]> {
   readonly guildId: string;
   constructor(client: GatewayClient, guildId: string);
-  construct(data: CacheEntityTypes["integrations"]): Integration;
+  protected createStructure(data: CacheEntityTypes["integrations"]): Integration;
   keyOf(data: CacheEntityTypes["integrations"]): string;
   resolveKey(integrationId: string): string;
   /**
@@ -7228,7 +7486,7 @@ export declare class GuildInviteManager extends CachedManager<"invites", GuildIn
    */
   readonly guildId: string;
   constructor(client: GatewayClient, guildId: string);
-  construct(data: CacheEntityTypes["invites"]): GuildInvite;
+  protected createStructure(data: CacheEntityTypes["invites"]): GuildInvite;
   keyOf(data: CacheEntityTypes["invites"]): string;
   /**
    * Adds an invite to the cache, and its inviter and target user to `client.users`.
@@ -7386,7 +7644,7 @@ export interface GuildOnboardingEditOptions {
  */
 export declare class GuildManager extends CachedManager<"guilds", Guild, [guildId: string]> {
   constructor(client: GatewayClient);
-  construct(data: CacheEntityTypes["guilds"]): Guild;
+  protected createStructure(data: CacheEntityTypes["guilds"]): Guild;
   keyOf(data: CacheEntityTypes["guilds"]): string;
   /**
    * Builds a guild, resolving its AFK, system, widget, rules, public updates, and safety alerts channels from the
@@ -7606,8 +7864,7 @@ export interface GuildTemplateCreateGuildOptions {
 /**
  * Manages guild templates. Discord does not send them over the gateway, so they are never cached.
  */
-export declare class GuildTemplateManager {
-  readonly client: GatewayClient;
+export declare class GuildTemplateManager extends BaseManager {
   constructor(client: GatewayClient);
   /**
    * Fetches a template by its code.
@@ -8339,9 +8596,16 @@ export declare class User extends User$1 {
    */
   guildTagBadgeURL(options?: BaseImageURLOptions): string | null;
   /**
-   * Opens a direct message channel with the user, or gets the existing one.
+   * The cached direct message channel with the user, see `UserManager#dmChannel`: `null` when there is none, or when
+   * the channel cache cannot be searched. Synchronous when the channel cache is.
+   */
+  get dmChannel(): Awaitable<DMChannel | null>;
+  /**
+   * Opens a direct message channel with the user, reusing the cached one.
+   *
+   * @param force Whether to skip the cache lookup and always call the API.
    */
-  createDM(): Promise<DMChannel>;
+  createDM(force?: boolean): Promise<DMChannel>;
   /**
    * Closes the direct message channel with the user.
    */
@@ -9061,12 +9325,13 @@ export declare function createChannel(data: CacheEntityTypes["channels"], relati
  * Manages the channels known to the client, threads included.
  *
  * @remarks
- * Threads live in their own entity cache, managed by `client.threads`, which {@link ChannelManager.get} falls back
+ * Threads live in their own entity cache, managed by `client.threads`, which {@link ChannelManager.cache} falls back
  * to, so a thread ID resolves like any other channel ID.
  */
 export declare class ChannelManager extends CachedManager<"channels", AnyChannel, [channelId: string]> {
   constructor(client: GatewayClient);
-  construct(data: CacheEntityTypes["channels"]): AnyChannel;
+  protected createCache(): Cache<AnyChannel>;
+  protected createStructure(data: CacheEntityTypes["channels"]): AnyChannel;
   keyOf(data: CacheEntityTypes["channels"]): string;
   _hydrate(data: CacheEntityTypes["channels"]): Awaitable<AnyChannel>;
   /**
@@ -9090,27 +9355,26 @@ export declare class ChannelManager extends CachedManager<"channels", AnyChannel
    * @internal
    */
   _getInGuild(channelId: string, guild: Guild): Awaitable<AnyChannel | null>;
-  resolveKey(channelId: string): string;
   /**
-   * Adds a channel to the cache, handing threads to `client.threads`, whose cache holds them.
+   * Finds the cached direct message channel with a user, for `client.users`.
    *
-   * @internal
-   */
-  _add(data: CacheEntityTypes["channels"], cache?: boolean, options?: AddOptions): Promise<AnyChannel>;
-  /**
-   * Gets a channel from the cache, looking it up in the thread cache as well, which `get` and `cached` rely on.
+   * @remarks
+   * Only a synchronous channel cache that can enumerate its entries is searched: scanning every channel of a remote
+   * store costs more than asking Discord for the channel.
    *
-   * @param channelId The ID of the channel.
+   * @param userId The ID of the user.
+   * @returns The channel, `null` when the cache was searched and holds none, `undefined` when it cannot be searched.
    * @internal
    */
-  _get(channelId: string): Awaitable<AnyChannel | undefined>;
+  _findDM(userId: string): Awaitable<DMChannel | null | undefined>;
+  private readRaw;
+  resolveKey(channelId: string): string;
   /**
-   * Writes a channel to the cache, threads to the thread cache.
+   * Adds a channel to the cache, handing threads to `client.threads`, whose cache holds them.
    *
-   * @param channelId The ID of the channel.
-   * @param raw The raw channel.
+   * @internal
    */
-  protected storeRaw(channelId: string, raw: CacheEntityTypes["channels"]): Promise<void>;
+  _add(data: CacheEntityTypes["channels"], cache?: boolean, options?: AddOptions): Promise<AnyChannel>;
   /**
    * Edits a channel.
    *
@@ -9144,7 +9408,7 @@ export declare class ChannelManager extends CachedManager<"channels", AnyChannel
  */
 export declare class VoiceStateManager extends CachedManager<"voiceStates", VoiceState, [guildId: string, userId: string]> {
   constructor(client: GatewayClient);
-  construct(data: CacheEntityTypes["voiceStates"]): VoiceState;
+  protected createStructure(data: CacheEntityTypes["voiceStates"]): VoiceState;
   keyOf(data: CacheEntityTypes["voiceStates"]): string;
   resolveKey(guildId: string, userId: string): string;
   _hydrate(data: CacheEntityTypes["voiceStates"]): Awaitable<VoiceState>;
@@ -9179,11 +9443,11 @@ export declare class VoiceStateManager extends CachedManager<"voiceStates", Voic
  *
  * @remarks
  * Presences only come from the gateway, with the `GuildPresences` intent: there is no API to fetch them, so `fetch`
- * rejects on a cache miss. Use `get`, which resolves to `undefined` instead.
+ * rejects on a cache miss. Use `cache.get`, which answers `undefined` instead.
  */
 export declare class PresenceManager extends CachedManager<"presences", Presence, [guildId: string, userId: string]> {
   constructor(client: GatewayClient);
-  construct(data: CacheEntityTypes["presences"]): Presence;
+  protected createStructure(data: CacheEntityTypes["presences"]): Presence;
   keyOf(data: CacheEntityTypes["presences"]): string;
   resolveKey(guildId: string, userId: string): string;
   _hydrate(data: CacheEntityTypes["presences"]): Awaitable<Presence>;
@@ -9199,39 +9463,93 @@ export declare class PresenceManager extends CachedManager<"presences", Presence
 }
 //#endregion
 //#region src/managers/UserManager.d.ts
+/**
+ * The options to open a direct message channel with.
+ */
+export interface CreateDMOptions {
+  /**
+   * Whether to skip the cache lookup and always call the API.
+   *
+   * @default false
+   */
+  force?: boolean;
+  /**
+   * Whether to store the channel fetched from the API in the cache.
+   *
+   * @default true
+   */
+  cache?: boolean;
+}
 /**
  * Manages the {@link User}s known to the client.
  */
 export declare class UserManager extends CachedManager<"users", User, [userId: string]> {
   constructor(client: GatewayClient);
-  construct(data: CacheEntityTypes["users"]): User;
+  protected createStructure(data: CacheEntityTypes["users"]): User;
   keyOf(data: CacheEntityTypes["users"]): string;
   resolveKey(userId: string): string;
   /**
-   * Opens a direct message channel with a user, or gets the existing one, and caches it.
+   * Resolves a {@link UserResolvable} to a user: the user of a member or a thread member, the author of a message, or
+   * the cached user of an ID.
+   *
+   * @param user The user, something holding one, or an ID.
+   * @returns The user, or `null` if it is not known.
+   */
+  resolve(user: UserResolvable): Awaitable<User | null>;
+  /**
+   * Resolves a {@link UserResolvable} to a user ID.
+   *
+   * @param user The user, something holding one, or an ID.
+   * @returns The ID, or `null` if the value holds none.
+   */
+  resolveId(user: UserResolvable): string | null;
+  /**
+   * Gets a user from the cache, fetching it from the API (and caching it) on a cache miss.
+   *
+   * @param user The user, something holding one, or an ID.
+   * @param options Whether to skip the cache, and whether to store the result.
+   */
+  fetch(user: UserResolvable, options?: FetchOptions): Promise<User>;
+  /**
+   * Gets the cached direct message channel with a user.
    *
    * @remarks
-   * Discord returns the existing channel when there is one, so this always calls the API: unlike discord.js, there is
-   * no synchronous `dmChannel` lookup to try first.
+   * It searches the channel cache, which only a synchronous cache that can enumerate its entries allows: the default
+   * `CollectionCache` and the in-memory stores. Other caches (a Redis store, `cache: null`) answer `null`.
    *
-   * @param userId The ID of the user.
+   * @param user The user, something holding one, or an ID.
+   * @returns The channel, or `null` when there is none or the cache cannot be searched.
    */
-  createDM(userId: string): Promise<DMChannel>;
+  dmChannel(user: UserResolvable): Awaitable<DMChannel | null>;
+  /**
+   * Opens a direct message channel with a user, and caches it. The cached channel is returned without calling the
+   * API, unless `force` is set.
+   *
+   * @param user The user, something holding one, or an ID.
+   * @param options Whether to skip the cache, and whether to store the result.
+   */
+  createDM(user: UserResolvable, { cache, force }?: CreateDMOptions): Promise<DMChannel>;
   /**
    * Closes the direct message channel with a user.
    *
-   * @param userId The ID of the user.
+   * @remarks
+   * When the channel cache cannot be searched (see {@link UserManager.dmChannel}), whether a channel exists is
+   * unknown: Discord is asked for it first, and nothing is thrown.
+   *
+   * @param user The user, something holding one, or an ID.
    * @returns The closed channel.
+   * @throws {GatewayError} `UserNoDMChannel` when the cache was searched and holds no channel with the user.
    */
-  deleteDM(userId: string): Promise<DMChannel>;
+  deleteDM(user: UserResolvable): Promise<DMChannel>;
   /**
    * Sends a direct message to a user.
    *
-   * @param userId The ID of the user.
+   * @param user The user, something holding one, or an ID.
    * @param options The message, or its content.
    */
-  send(userId: string, options: MessagePayloadResolvable<MessageCreateOptions>): Promise<Message>;
+  send(user: UserResolvable, options: MessagePayloadResolvable<MessageCreateOptions>): Promise<Message>;
   protected fetchRaw(userId: string): Promise<import("discord-api-types/v10").APIUser>;
+  private requireId;
 }
 //#endregion
 //#region src/structures/users/ClientUser.d.ts
@@ -9522,8 +9840,58 @@ export interface GatewayClientOptions extends ClientOptions, GatewayClientMessag
    */
   shardIds?: number[] | ShardRange | null;
   /**
-   * The cache to write every dispatch into, see `@wolfstar/plugin-cache`. Without one, the managers' `get` always
-   * resolve to `undefined`, update events receive `null` as their previous state, and `fetch` always hits the API.
+   * Builds the cache of each entity, the one its managers expose as `manager.cache`: the `cacheConstructor` of the
+   * discord.js RFC #11426. The caches hold structure instances, which dispatches patch in place.
+   *
+   * @remarks
+   * The class is instantiated once per entity with `(creator, name, options)`, see {@link CacheConstructor}:
+   * `options` carries `keyOf`, the key of raw data, which `add` must use since most entities are not keyed by their
+   * `id`, `refresh`, to call on what `get` and `add` hand out so that relations are resolved again, and the entity's
+   * {@link GatewayClientOptions.cacheOptions}. Extending {@link CollectionCache} is the recommended way.
+   *
+   * A cache that is not a `Map` cannot be enumerated: the dispatch cascades (`GUILD_DELETE`, `CHANNEL_DELETE`), the
+   * reconciliation on `READY`, the emoji and sticker diff events, and `listCached` do not work with it.
+   *
+   * It cannot be combined with {@link GatewayClientOptions.cache} or {@link GatewayClientOptions.makeCache}, which
+   * back the managers with raw `@wolfstar/plugin-cache` stores instead: passing both throws. `cache: null` wins over
+   * it: nothing is cached, and the class is never instantiated.
+   *
+   * The structures of a cache of instances are built synchronously, so the caches their relations are read from
+   * must be synchronous too.
+   *
+   * @default CollectionCache
+   */
+  cacheConstructor?: CacheConstructor;
+  /**
+   * The options of the cache of each entity, passed to {@link GatewayClientOptions.cacheConstructor} (the default
+   * `CollectionCache` included) next to `keyOf` and `refresh`. `maxSize` bounds the amount of entries of an entity,
+   * the oldest one being evicted first.
+   *
+   * @remarks
+   * By default every received entity stays in memory until a dispatch removes it: this is what bounds it, next to
+   * {@link GatewayClientOptions.policies} and `cache: null`.
+   *
+   * It only applies to caches built by a constructor. Like `cacheConstructor`, it cannot be combined with
+   * {@link GatewayClientOptions.cache} or {@link GatewayClientOptions.makeCache}, whose stores have their own
+   * bounds: passing both throws. With `cache: null` it is ignored.
+   *
+   * @example
+   * ```typescript
+   * // Keep the 1000 most recent messages, and no presence.
+   * const client = new GatewayClient({
+   *   intents,
+   *   cacheOptions: { messages: { maxSize: 1_000 }, presences: { maxSize: 0 } },
+   * });
+   * ```
+   *
+   * @default undefined
+   */
+  cacheOptions?: Partial<Record<CacheEntityName, CacheEntityOptions>>;
+  /**
+   * 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
+   * on every read. `null` disables caching: the managers' `cache.get` always answer `undefined`, update events
+   * receive `null` as their previous state, and `fetch` always hits the API.
    *
    * @remarks
    * Every entity cache is optional: an entity kind the cache does not hold is simply not cached, see
@@ -9531,11 +9899,12 @@ export interface GatewayClientOptions extends ClientOptions, GatewayClientMessag
    *
    * @default undefined
    */
-  cache?: Cache;
+  cache?: Cache$1 | null;
   /**
-   * Creates the store of each entity kind, `null` or `undefined` not to cache it: the `CacheConstructor` of the
-   * discord.js RFC #11426. Called once per entity kind when the client is constructed, and takes precedence over
-   * {@link GatewayClientOptions.cache}.
+   * Creates the raw `@wolfstar/plugin-cache` store of each entity kind, `null` or `undefined` not to cache it. Called
+   * once per entity kind when the client is constructed, and takes precedence over
+   * {@link GatewayClientOptions.cache}. Not to be confused with {@link GatewayClientOptions.cacheConstructor}, which
+   * builds caches of structure instances.
    *
    * @example
    * ```typescript
@@ -9553,7 +9922,13 @@ export interface GatewayClientOptions extends ClientOptions, GatewayClientMessag
   makeCache?: CacheFactory;
   /**
    * The policies deciding which entries get cached, and for how long, per entity kind, see `withPolicy`. They apply to
-   * every write, from dispatches as well as from the managers.
+   * every write, from dispatches as well as from the managers: an entry its `filter` rejects is not cached, and the
+   * entry already cached under its key is deleted.
+   *
+   * @remarks
+   * `ttl` only applies to `@wolfstar/plugin-cache` stores ({@link GatewayClientOptions.cache},
+   * {@link GatewayClientOptions.makeCache}): the caches of instances built by
+   * {@link GatewayClientOptions.cacheConstructor}, the default included, have no per-entry time-to-live.
    *
    * @example
    * ```typescript
@@ -9664,7 +10039,7 @@ export interface GatewayClientDestroyOptions {
 }
 /**
  * A {@link Client} that, on top of serving HTTP interactions, connects to the Discord gateway, writes every dispatch
- * into an optional {@link Cache}, and emits {@link GatewayEventMap} events carrying structures.
+ * into its cache, and emits {@link GatewayEventMap} events carrying structures.
  *
  * @example
  * ```typescript
@@ -9685,9 +10060,10 @@ export interface GatewayClientDestroyOptions {
 export declare class GatewayClient extends Client {
   #private;
   /**
-   * The cache every dispatch is written into, if any.
+   * The raw cache every dispatch is written into, if any: the `@wolfstar/plugin-cache` cache passed as
+   * {@link GatewayClientOptions.cache}, or a raw view of the managers' caches of instances.
    */
-  readonly cache: Cache | undefined;
+  readonly cache: Cache$1 | undefined;
   /**
    * The REST manager the gateway (for its gateway bot info) and every manager's API calls go through, like
    * discord.js's `Client#rest`.
@@ -9783,6 +10159,30 @@ export declare class GatewayClient extends Client {
    * @internal
    */
   runInGuildOrder<Value>(guildId: string, task: () => Promise<Value>): Promise<Value>;
+  /**
+   * Gets the cache of an entity, building it on first use: the `CacheConstructor` of the discord.js RFC #11426.
+   * Every manager of the same entity shares the same cache.
+   *
+   * @param creator Builds a structure from raw data, for entities the client does not know how to build.
+   * @param name The name of the entity.
+   */
+  CacheConstructor<Value extends StructureMixin<object>>(creator: StructureCreator<Value>, name: CacheEntityName): Cache<Value>;
+  /**
+   * Runs a raw store operation, reporting its failure through `cacheError`, see
+   * {@link GatewayClientOptions.cacheErrors}. Synchronous when the operation is.
+   *
+   * @internal
+   */
+  guardCache<T>(entity: CacheEntityName, operation: CacheErrorContext["operation"], key: string | null, run: () => Awaitable<T>, fallback: T): Awaitable<T>;
+  /**
+   * Gets the `filter` of an entity's policy the managers must apply themselves before writing to its cache, see
+   * {@link GatewayClientOptions.policies}.
+   *
+   * @param name The name of the entity.
+   * @returns The filter, or `undefined` when there is none or when the entity's store applies it already.
+   * @internal
+   */
+  cacheFilter(name: CacheEntityName): ((value: object, key: string) => boolean) | undefined;
   /**
    * Resolves once every dispatch received so far has been processed.
    */
@@ -10017,7 +10417,7 @@ export interface CacheErrorContext {
   /**
    * The operation that failed.
    */
-  operation: "get" | "set" | "upsert" | "delete";
+  operation: "get" | "set" | "upsert" | "delete" | "has" | "clear" | "getSize" | "keys" | "entries";
 }
 /**
  * What a reaction event says besides the reaction and the user.
@@ -10407,16 +10807,19 @@ 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 ClientNotConstructed: "No GatewayClient has been constructed yet";
   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;
   readonly SessionStoreTimeout: (timeout: number) => string;
   readonly CacheAsynchronous: (entity: string) => string;
-  readonly CacheRelationsAsynchronous: (entity: string) => string;
+  readonly CacheConstructorAsynchronous: (entity: string) => string;
   readonly CacheNotIterable: (entity: string) => string;
   readonly CacheKeyUnresolvable: (entity: string, reason: string) => string;
   readonly IdUnresolvable: "Cannot resolve an ID from a structure without one";
+  readonly InvalidType: (name: string, expected: string, an?: boolean) => string;
+  readonly InvalidElement: (type: string, name: string, element: unknown) => string;
   readonly ChannelGuildUnknown: (channelId: string) => string;
   readonly ChannelTypeChanged: (channelId: string, from: number, to: number) => string;
   readonly ChannelLockPermissionsConflict: "Pass either lockPermissions or permissionOverwrites, not both";
@@ -10436,6 +10839,7 @@ export declare const GatewayErrorMessages: {
   readonly GuildMembersRateLimited: (guildId: string, nonce: string, retryAfter: number) => string;
   readonly PresenceNotFetchable: (guildId: string, userId: string) => string;
   readonly InviteGuildUnknown: (code: string) => string;
+  readonly UserNoDMChannel: "No DM Channel exists!";
   readonly EmojiEmpty: "Cannot resolve an empty string to an emoji";
   readonly EmojiType: "Cannot resolve an emoji without an ID nor a name";
   readonly NotGuildSticker: "Only guild stickers can be edited or deleted";
@@ -10528,49 +10932,159 @@ export declare class GroupDMInvite extends BaseInvite {}
  */
 export declare function createInvite(data: InviteData, relations?: InviteRelations): BaseInvite;
 //#endregion
-//#region src/util/cache.d.ts
+//#region src/util/CollectionCache.d.ts
 /**
- * The raw API data a {@link StructureMixin | structure} wraps.
+ * The options of {@link CollectionCache}.
  */
-type RawAPIType<Value extends StructureMixin<object>> = Value extends StructureMixin<infer Type> ? Type : never;
+export interface CollectionCacheOptions<Value, Raw> {
+  /**
+   * Gets the key of raw data, for {@link CollectionCache.add}.
+   *
+   * @default (data) => data.id
+   */
+  keyOf?: (data: Partial<Raw>) => string;
+  /**
+   * Called with an instance every time it is read with `get` or updated with `add`, to bring what it holds besides
+   * its data (its relations) up to date. It returns the instance to hand out.
+   */
+  refresh?: (value: Value) => Value;
+  /**
+   * The maximum amount of entries, the oldest one being evicted when a new one would exceed it. `0` holds nothing:
+   * `add` still builds the structure, without keeping it.
+   *
+   * @default Infinity
+   */
+  maxSize?: number;
+}
 /**
- * A function building a {@link StructureMixin | structure} out of its raw API data.
+ * The default {@link Cache}: an in-memory `Collection` of structure instances, like discord.js's caches.
+ *
+ * @remarks
+ * `add` patches the cached instance in place, so a reference kept by the application sees later updates.
+ *
+ * Every method is synchronous. Being a `Collection`, it also has `find`, `filter`, `map`, ... which return plain
+ * collections. Instances reached by iterating carry the relations of their last `get`.
  */
-type StructureCreator<Value extends StructureMixin<object>, Raw extends RawAPIType<Value> = RawAPIType<Value>> = (data: Raw) => Value;
+export declare class CollectionCache<Value extends StructureMixin<object>, Raw extends RawAPIType<Value> = RawAPIType<Value>> extends Collection<string, Value> implements Cache<Value, Raw> {
+  #private;
+  static get [Symbol.species](): typeof Collection;
+  readonly synchronous = true;
+  readonly construct: StructureCreator<Value, Raw>;
+  /**
+   * The name of the entity this cache holds.
+   */
+  readonly name: CacheEntityName;
+  constructor(creator: StructureCreator<Value, Raw>, name: CacheEntityName, options?: CollectionCacheOptions<Value, Raw>);
+  add(data: Partial<Raw>, overwrite?: boolean): Value;
+  get(key: string): Value | undefined;
+  set(key: string, value: Value): this;
+  getSize(): number;
+}
+//#endregion
+//#region src/util/EntityStoreCache.d.ts
 /**
- * Whether an {@link Awaitable} is a promise, rather than the value itself.
- *
- * @internal
+ * Runs a store operation, reporting its failure and resolving it to a fallback or rethrowing it.
  */
-declare function isPromiseLike<T>(value: Awaitable<T>): value is Promise<T>;
+export type CacheGuard = <T>(operation: CacheErrorContext["operation"], key: string | null, run: () => Awaitable<T>, fallback: T) => Awaitable<T>;
 /**
- * Waits for a list of {@link Awaitable}s like `Promise.all`, then calls a function with their values. Unlike
- * `Promise.all`, it stays synchronous when none of them is a promise, which is what lets a synchronous cache build
- * structures without awaiting them.
- *
- * @param values The values, some of which may be promises.
- * @param callback The function to call with the values.
- * @internal
+ * The options of {@link EntityStoreCache}.
  */
-declare function whenAll<const T extends readonly unknown[], R>(values: T, callback: (values: { -readonly [Index in keyof T]: Awaited<T[Index]>; }) => Awaitable<R>): Awaitable<R>;
+export interface EntityStoreCacheOptions<Value, Raw> {
+  /**
+   * The raw store.
+   */
+  store: EntityCache<Raw>;
+  /**
+   * Gets the key of raw data, for {@link EntityStoreCache.add}.
+   */
+  keyOf: (data: Partial<Raw>) => string;
+  /**
+   * Builds the structure of raw data read from the store, with its relations. May be asynchronous.
+   *
+   * @default The creator.
+   */
+  hydrate?: (data: Raw) => Awaitable<Value>;
+  /**
+   * Whether every method answers synchronously. The structures read their relations from other stores, so a view over
+   * a synchronous store is only synchronous when those are too.
+   *
+   * @default () => store.synchronous === true
+   */
+  synchronous?: () => boolean;
+  /**
+   * Guards every store call.
+   *
+   * @default Lets errors through.
+   */
+  guard?: CacheGuard;
+}
 /**
- * Picks the cached structures of some IDs, in their order, skipping the ones that are not cached: the equivalent of
- * the collections discord.js fills from its caches, e.g. `MessageMentions#channels`.
+ * A {@link Cache} over a raw `@wolfstar/plugin-cache` store (in memory or Redis): the store holds raw API data, and a
+ * structure is built on every read.
  *
- * @param ids The IDs.
- * @param cached The cached structures, by ID.
- * @internal
+ * @remarks
+ * Unlike `CollectionCache`, two reads of the same key return two structures: do not rely on object identity.
  */
-declare function pickCached<Value>(ids: readonly string[], cached: ReadonlyMap<string, Value> | undefined): Map<string, Value>;
+export declare class EntityStoreCache<Value extends StructureMixin<object>, Raw extends RawAPIType<Value> = RawAPIType<Value>> implements Cache<Value, Raw> {
+  #private;
+  readonly construct: StructureCreator<Value, Raw>;
+  /**
+   * The name of the entity this cache holds.
+   */
+  readonly name: CacheEntityName;
+  /**
+   * The raw store.
+   */
+  readonly store: EntityCache<Raw>;
+  constructor(creator: StructureCreator<Value, Raw>, name: CacheEntityName, options: EntityStoreCacheOptions<Value, Raw>);
+  get synchronous(): boolean;
+  add(data: Partial<Raw>, overwrite?: boolean): Awaitable<Value>;
+  clear(): Awaitable<void>;
+  delete(key: string): Awaitable<boolean>;
+  get(key: string): Awaitable<Value | undefined>;
+  getSize(): Awaitable<number>;
+  has(key: string): Awaitable<boolean>;
+  set(key: string, value: Value): Awaitable<this>;
+}
+//#endregion
+//#region src/util/NullCache.d.ts
 /**
- * Reads the cached structures of some IDs, synchronously when every read is, skipping duplicates and the IDs that
- * are not cached. The {@link Awaitable} counterpart of discord.js's collections filled from its caches.
- *
- * @param ids The IDs.
- * @param get Reads the structure of an ID.
- * @internal
+ * The options of {@link NullCache}.
  */
-declare function whenCachedMap<Value>(ids: Iterable<string>, get: (id: string) => Awaitable<Value | null | undefined>): Awaitable<Map<string, Value>>;
+export interface NullCacheOptions<Value, Raw> {
+  /**
+   * Builds the structure {@link NullCache.add} answers with, with its relations. May be asynchronous.
+   *
+   * @default The creator.
+   */
+  hydrate?: (data: Raw) => Awaitable<Value>;
+  /**
+   * Whether `hydrate` answers synchronously.
+   *
+   * @default () => true
+   */
+  synchronous?: () => boolean;
+}
+/**
+ * The {@link Cache} of an entity that is not cached: always empty, writes are dropped.
+ */
+export declare class NullCache<Value extends StructureMixin<object>, Raw extends RawAPIType<Value> = RawAPIType<Value>> implements Cache<Value, Raw> {
+  #private;
+  readonly construct: StructureCreator<Value, Raw>;
+  /**
+   * The name of the entity this cache stands for.
+   */
+  readonly name: CacheEntityName;
+  constructor(creator: StructureCreator<Value, Raw>, name: CacheEntityName, options?: NullCacheOptions<Value, Raw>);
+  get synchronous(): boolean;
+  add(data: Partial<Raw>): Awaitable<Value>;
+  clear(): void;
+  delete(): boolean;
+  get(): undefined;
+  getSize(): number;
+  has(): boolean;
+  set(): this;
+}
 //#endregion
 //#region src/util/container.d.ts
 /**
@@ -11034,5 +11548,5 @@ export interface TransformedResolvedData {
  */
 export declare function transformResolved({ client, guildId }: SupportingResolvedData, { users, members, roles, channels }: ResolvableData): Awaitable<TransformedResolvedData>;
 //#endregion
-export { type AnnouncementChannelResolvable, type ApplicationCommandDataResolvable, type ApplicationCommandPermissionIdResolvable, type ApplicationCommandResolvable, type ApplicationResolvable, type AttachmentPayload, type AttachmentResolvable, type AutoModerationRuleResolvable, CachedManager as BaseManager, type BaseMessageOptions, BitField, type BitFieldResolvable, type BufferResolvable, type CategoryChannelResolvable, type ChannelResolvable, type ColorResolvable, type CommandOptionDataTypeResolvable, type ComponentEmojiResolvable, type DateResolvable, type EmojiResolvable, type EntitlementResolvable, type ForwardOptions, type GatewayClientMessageDefaults, type GuildAuditLogsResolvable, type GuildBanResolvable, type GuildBasedChannel, type GuildChannelResolvable, type GuildInvitableChannel, type GuildInvitableChannelResolvable, type GuildInviteResolvable, type GuildResolvable, type GuildScheduledEventResolvable, type GuildTemplateResolvable, type GuildTextChannelResolvable, type GuildVoiceChannelResolvable, type HexColorString, type InviteResolvable, type JSONEncodable, type MessageActionRowComponentResolvable, type MessageCreateOptions, type MessageEditOptions, type MessageMentionOptions, type MessagePayloadContext, type MessagePayloadOptions, type MessagePayloadResolvable, type MessageReactionResolvable, type MessageResolvable, type MessageTarget, type NonThreadGuildBasedChannel, type OverwriteResolvable, type PermissionOverwriteResolvable, PermissionsBitField, type PollCreateData, type PresenceResolvable, type RawAPIType, type ReplyOptions, type ResolvedMessagePayload, type RoleColorsEditResolvable, type RoleColorsResolvable, type RoleResolvable, type SKUResolvable, type SoundboardSoundResolvable, type StageChannelResolvable, type StageInstanceResolvable, type StickerResolvable, type StructureCreator, type SubscriptionResolvable, type TextBasedChannel, type TextBasedChannelResolvable, type TextChannelResolvable, type ThreadChannel, type ThreadChannelResolvable, type ThreadMemberResolvable, type UserResolvable, type VoiceBasedChannel, type VoiceChannelResolvable, type WebhookMessageCreateOptions, type WebhookMessageEditOptions, type WebhookMessageOptions, type WebhookThreadOptions, type isPromiseLike, type pickCached, type whenAll, type whenCachedMap };
+export { type AnnouncementChannelResolvable, type ApplicationCommandDataResolvable, type ApplicationCommandPermissionIdResolvable, type ApplicationCommandResolvable, type ApplicationResolvable, type AttachmentPayload, type AttachmentResolvable, type AutoModerationRuleResolvable, type BaseMessageOptions, BitField, type BitFieldResolvable, type BufferResolvable, type Cache, type CacheConstructor, type CacheConstructorOptions, type CacheEntityOptions, type CategoryChannelResolvable, type ChannelResolvable, type ColorResolvable, type CommandOptionDataTypeResolvable, type ComponentEmojiResolvable, type DateResolvable, type EmojiResolvable, type EntitlementResolvable, type ForwardOptions, type GatewayClientMessageDefaults, type GuildAuditLogsResolvable, type GuildBanResolvable, type GuildBasedChannel, type GuildChannelResolvable, type GuildInvitableChannel, type GuildInvitableChannelResolvable, type GuildInviteResolvable, type GuildResolvable, type GuildScheduledEventResolvable, type GuildTemplateResolvable, type GuildTextChannelResolvable, type GuildVoiceChannelResolvable, type HexColorString, type InviteResolvable, type JSONEncodable, type MessageActionRowComponentResolvable, type MessageCreateOptions, type MessageEditOptions, type MessageMentionOptions, type MessagePayloadContext, type MessagePayloadOptions, type MessagePayloadResolvable, type MessageReactionResolvable, type MessageResolvable, type MessageTarget, type NonThreadGuildBasedChannel, type OverwriteResolvable, type PermissionOverwriteResolvable, PermissionsBitField, type PollCreateData, type PresenceResolvable, type RawAPIType, type ReplyOptions, type ResolvedMessagePayload, type RoleColorsEditResolvable, type RoleColorsResolvable, type RoleResolvable, type RoleResolvables, type SKUResolvable, type SoundboardSoundResolvable, type StageChannelResolvable, type StageInstanceResolvable, type StickerResolvable, type StructureCreator, type SubscriptionResolvable, type TextBasedChannel, type TextBasedChannelResolvable, type TextChannelResolvable, type ThreadChannel, type ThreadChannelResolvable, type ThreadMemberResolvable, type UserResolvable, type VoiceBasedChannel, type VoiceChannelResolvable, type WebhookMessageCreateOptions, type WebhookMessageEditOptions, type WebhookMessageOptions, type WebhookThreadOptions, type isPromiseLike, type peekCache, type pickCached, type refreshRelations, type whenAll, type whenCachedMap };
 //# sourceMappingURL=index.d.ts.map