@wolfstar/plugin-gateway 0.5.0 → 0.6.0

package/README.md

@@ -303,6 +303,44 @@ the copy embedded in its payload.
 Swapping `createInMemoryCache()` for `createRedisCache({ redis })` changes nothing else, see
 [`@wolfstar/plugin-cache`](../plugin-cache).
 
+### Zero caching and cache control
+
+Every feature works without a cache, following the
+[discord.js RFC #11426](https://github.com/discordjs/discord.js/issues/11426): leave `cache` out
+and every `fetch` hits the API, every event is still emitted, and the previous state of update and
+delete events is `null` (or a partial, see [Partials](#partials)). Each entity kind can be cached,
+or not, on its own:
+
+```ts
+import { MemoryEntityCache } from "@wolfstar/plugin-cache";
+
+const client = new GatewayClient({
+  intents,
+  // Called once per entity kind: `null` not to cache it.
+  makeCache: (entity) =>
+    ["guilds", "channels", "roles"].includes(entity) ? new MemoryEntityCache() : null,
+  // Entry by entry, for dispatches and managers alike.
+  policies: { users: { filter: (user) => !user.bot }, messages: { ttl: () => 3_600_000 } },
+  // A failing store (e.g. Redis down) is a cache miss, reported through `cacheError`.
+  cacheErrors: "miss",
+});
+```
+
+`makeCache` takes precedence over `cache`, and `policies` apply to either. What needs a store:
+
+| Without the store of…        | What happens                                                               |
+| ---------------------------- | -------------------------------------------------------------------------- |
+| any entity                   | `get` resolves to `undefined`, `fetch` hits the API, previous state `null` |
+| `emojis` / `stickers`        | only `guildEmojisUpdate` / `guildStickersUpdate`, no granular diff events  |
+| `guilds` (able to enumerate) | guilds left while offline are not reconciled on `READY`                    |
+| `presences`                  | `presences.fetch` rejects: presences only come from the gateway            |
+| `roles`                      | overwrite types and member roles are read from one `GET /guilds/:id/roles` |
+| `threadMembers`              | `thread.joined` is `null` unless the payload carries the bot's member      |
+| a relation's entity          | the relation getter (`message.guild`, `member.voice`, ...) returns `null`  |
+
+`listCached` resolves to `[]` without a store, and throws a `TypeError` for a store that cannot
+enumerate its entries. With `cacheErrors: "throw"`, a failing store rejects instead of missing.
+
 ### Synchronous reads
 
 Every manager method above is asynchronous since the cache can be Redis, which makes a hot path
@@ -318,7 +356,7 @@ client.on("messageCreate", (message) => {
 });
 ```
 
-It returns `undefined` on a miss, or when the client has no cache, like `get`. An asynchronous cache
+It returns `undefined` on a miss, or when the entity is not cached, like `get`. An asynchronous cache
 cannot tell a miss apart without awaiting it, so there `cached` throws a `TypeError` rather than
 silently returning `undefined`; the same goes for a custom cache mixing both kinds, when a relation
 lives in an asynchronous entity cache. `manager.cache?.synchronous` tells which path to take:

package/dist/esm/index.d.ts

@@ -1,7 +1,7 @@
 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, EntityCache, GatewaySessionStore } from "@wolfstar/plugin-cache";
+import { Awaitable, Cache, CacheEntityName, CacheEntityTypes, CacheFactory, CachePolicies, EntityCache, GatewaySessionStore, IterableEntityCache } from "@wolfstar/plugin-cache";
 import { APIAllowedMentions, APIApplication, APIApplicationCommand, APIAttachment, APIAuditLogChange, APIAutoModerationAction, APIAutoModerationRule, APIAutoModerationRuleTriggerMetadata, APIAvatarDecorationData, APIChannel, APIChannelMention, APICollectibles, APIEmbed, APIEmbedAuthor, APIEmbedField, APIEmbedFooter, APIEmbedImage, APIEmbedProvider, APIEmbedThumbnail, APIEmbedVideo, APIEmoji, APIExtendedInvite, APIGuild, APIGuildForumDefaultReactionEmoji, APIGuildForumTag, APIGuildMember, APIGuildOnboarding, APIGuildOnboardingPrompt, APIGuildOnboardingPromptOption, APIGuildPreview, APIGuildScheduledEvent, APIGuildScheduledEventEntityMetadata, APIGuildScheduledEventRecurrenceRule, APIGuildWelcomeScreen, APIGuildWidget, APIGuildWidgetMember, APIIncidentsData, APIInviteChannel, APIInviteGuild, APIMessage, APIMessageTopLevelComponent, APIOverwrite, APIPartialEmoji, APIPoll, APIPollAnswer, APIReaction, APIRole, APIRoleTags, APISoundboardSound, APIStageInstance, APISticker, APIStickerPack, APITemplate, APIThreadChannel, APIThreadMember, APIUser, APIUserPrimaryGuild, APIVoiceRegion, APIWebhook, ActivityFlags, ActivityType, AllowedMentionsTypes, AttachmentFlags, AuditLogEvent, AutoModerationRuleEventType, AutoModerationRuleKeywordPresetType, AutoModerationRuleTriggerType, ChannelFlags, ChannelType, 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, GuildScheduledEventStatus, GuildSystemChannelFlags, GuildVerificationLevel, GuildWidgetStyle, InviteTargetType, InviteType, Locale, MessageFlags, OverwriteType, PermissionFlagsBits, PollLayoutType, PresenceUpdateReceiveStatus, PresenceUpdateStatus, RESTAPIPoll, RESTGetAPIGuildVanityUrlResult, RESTPatchAPIChannelJSONBody, RESTPatchAPIGuildJSONBody, RESTPostAPIChannelMessageJSONBody, RESTPostAPIGuildsJSONBody, ReactionType, RoleFlags, Snowflake, SortOrderType, StageInstancePrivacyLevel, StickerFormatType, ThreadAutoArchiveDuration, ThreadChannelType, UserFlags, VideoQualityMode } from "discord-api-types/v10";
 import { APIActualInvite, 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, DMChannel as DMChannel$1, Embed as Embed$1, Emoji as Emoji$1, ForumChannel as ForumChannel$1, GroupDMChannel as GroupDMChannel$1, Invite, MediaChannel as MediaChannel$1, Message as Message$1, MessageFlagsBitField as MessageFlagsBitField$1, Partialize, PermissionsBitField, Poll as Poll$1, PollAnswer as PollAnswer$1, Presence as Presence$1, PrivateThreadChannel as PrivateThreadChannel$1, PublicThreadChannel as PublicThreadChannel$1, Reaction, SoundboardSound as SoundboardSound$1, StageChannel as StageChannel$1, StageInstance as StageInstance$1, Sticker as Sticker$1, StickerPack as StickerPack$1, Structure as Structure$1, TextChannel as TextChannel$1, User as User$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";
@@ -390,12 +390,16 @@ export interface AddOptions {
   key?: string;
 }
 /**
- * The base class of every manager: 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}.
+ * 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}.
  *
  * @remarks
- * The cache only ever holds raw API data, building structures is always the manager's job. Without a cache, `get`
- * always resolves to `undefined` and `fetch` always hits the API.
+ * 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.
@@ -511,7 +515,7 @@ export declare abstract class CachedManager<Name extends CacheEntityName, Value
   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.createStructure}.
+   * as {@link CachedManager.construct}.
    *
    * @param data The raw data.
    */
@@ -544,12 +548,20 @@ 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}.
    */
-  abstract createStructure(data: CacheEntityTypes[Name]): Value;
+  createStructure(data: CacheEntityTypes[Name]): Value;
   /**
    * Gets the cache key of raw data.
    *
@@ -575,12 +587,29 @@ export declare abstract class CachedManager<Name extends CacheEntityName, Value
    * @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.
+   *
+   * @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"`.
+   */
+  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.
    *
@@ -621,7 +650,7 @@ export interface AutoModerationRuleCreateOptions extends AutoModerationRuleEditO
 export declare class AutoModerationRuleManager extends CachedManager<"autoModerationRules", AutoModerationRule, [ruleId: string]> {
   readonly guildId: string;
   constructor(client: GatewayClient, guildId: string);
-  createStructure(data: CacheEntityTypes["autoModerationRules"]): AutoModerationRule;
+  construct(data: CacheEntityTypes["autoModerationRules"]): AutoModerationRule;
   keyOf(data: CacheEntityTypes["autoModerationRules"]): string;
   resolveKey(ruleId: string): string;
   _hydrate(data: CacheEntityTypes["autoModerationRules"]): Awaitable<AutoModerationRule>;
@@ -1463,7 +1492,7 @@ export interface GuildMembersRequestOptions {
 export declare class GuildMemberManager extends CachedManager<"members", GuildMember, [guildId: string, userId: string]> {
   #private;
   constructor(client: GatewayClient);
-  createStructure(data: CacheEntityTypes["members"]): GuildMember;
+  construct(data: CacheEntityTypes["members"]): GuildMember;
   keyOf(data: CacheEntityTypes["members"]): string;
   /**
    * Adds a member to the cache, and its user to `client.users`.
@@ -1679,7 +1708,7 @@ export interface RolePosition {
  */
 export declare class RoleManager extends CachedManager<"roles", Role, [guildId: string, roleId: string]> {
   constructor(client: GatewayClient);
-  createStructure(data: CacheEntityTypes["roles"]): Role;
+  construct(data: CacheEntityTypes["roles"]): Role;
   keyOf(data: CacheEntityTypes["roles"]): string;
   _hydrate(data: CacheEntityTypes["roles"]): Awaitable<Role>;
   resolveKey(guildId: string, roleId: string): string;
@@ -2629,7 +2658,7 @@ export interface ThreadMemberListOptions {
  */
 export declare class ThreadMemberManager extends CachedManager<"threadMembers", ThreadMember, [threadId: string, userId: string]> {
   constructor(client: GatewayClient);
-  createStructure(data: CacheEntityTypes["threadMembers"]): ThreadMember;
+  construct(data: CacheEntityTypes["threadMembers"]): ThreadMember;
   keyOf(data: CacheEntityTypes["threadMembers"]): string;
   resolveKey(threadId: string, userId: string): string;
   /**
@@ -2736,9 +2765,11 @@ export declare class ThreadChannelMixin<Type extends ChannelType = ChannelType>
   get invitable(): boolean | null;
   /**
    * Whether the bot is a member of the thread, like discord.js's `ThreadChannel#joined`: from the thread member cache
-   * when the thread was built by a manager, else whether the payload carries the bot's thread member.
+   * when the thread was built by a manager, else `true` when the payload carries the bot's thread member.
+   *
+   * @returns `null` when it cannot be told: no thread member cache, and no thread member in the payload.
    */
-  get joined(): boolean;
+  get joined(): boolean | null;
   /**
    * The members of the thread.
    */
@@ -2888,7 +2919,7 @@ export interface FetchedThreads {
  */
 export declare class ThreadManager extends CachedManager<"threads", AnyThreadChannel, [threadId: string]> {
   constructor(client: GatewayClient);
-  createStructure(data: CacheEntityTypes["threads"]): AnyThreadChannel;
+  construct(data: CacheEntityTypes["threads"]): AnyThreadChannel;
   keyOf(data: CacheEntityTypes["threads"]): string;
   _hydrate(data: CacheEntityTypes["threads"]): Awaitable<AnyThreadChannel>;
   resolveKey(threadId: string): string;
@@ -2953,7 +2984,7 @@ export interface PinnedMessage {
  */
 export declare class MessageManager extends CachedManager<"messages", Message, [channelId: string, messageId: string]> {
   constructor(client: GatewayClient);
-  createStructure(data: CacheEntityTypes["messages"]): Message;
+  construct(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
@@ -3140,7 +3171,7 @@ export declare class GuildEmojiManager extends CachedManager<"emojis", GuildEmoj
    */
   readonly guildId: string;
   constructor(client: GatewayClient, guildId: string);
-  createStructure(data: CacheEntityTypes["emojis"]): GuildEmoji;
+  construct(data: CacheEntityTypes["emojis"]): GuildEmoji;
   keyOf(data: CacheEntityTypes["emojis"]): string;
   /**
    * Adds an emoji to the cache, and its uploader to `client.users`.
@@ -3186,6 +3217,9 @@ export declare class GuildEmojiManager extends CachedManager<"emojis", GuildEmoj
    * @remarks
    * It enumerates the whole entity cache, which a Redis store answers from its index: prefer `fetchAll` when the
    * cache may be incomplete.
+   *
+   * @returns The cached entries, `[]` when this entity is not cached.
+   * @throws {TypeError} When the store cannot enumerate its entries.
    */
   listCached(): Promise<GuildEmoji[]>;
   protected fetchRaw(emojiId: string): Promise<{
@@ -4373,7 +4407,7 @@ export interface GuildBanListOptions {
 export declare class GuildBanManager extends CachedManager<"bans", GuildBan, [userId: string]> {
   readonly guildId: string;
   constructor(client: GatewayClient, guildId: string);
-  createStructure(data: CacheEntityTypes["bans"]): GuildBan;
+  construct(data: CacheEntityTypes["bans"]): GuildBan;
   keyOf(data: CacheEntityTypes["bans"]): string;
   resolveKey(userId: string): string;
   /**
@@ -4580,7 +4614,7 @@ export interface GuildScheduledEventSubscriber {
 export declare class GuildScheduledEventManager extends CachedManager<"scheduledEvents", GuildScheduledEvent, [eventId: string]> {
   readonly guildId: string;
   constructor(client: GatewayClient, guildId: string);
-  createStructure(data: CacheEntityTypes["scheduledEvents"]): GuildScheduledEvent;
+  construct(data: CacheEntityTypes["scheduledEvents"]): GuildScheduledEvent;
   keyOf(data: CacheEntityTypes["scheduledEvents"]): string;
   resolveKey(eventId: string): string;
   /**
@@ -4711,7 +4745,7 @@ export interface SoundboardSoundCreateOptions extends SoundboardSoundEditOptions
 export declare class GuildSoundboardSoundManager extends CachedManager<"soundboardSounds", SoundboardSound, [soundId: string]> {
   readonly guildId: string;
   constructor(client: GatewayClient, guildId: string);
-  createStructure(data: CacheEntityTypes["soundboardSounds"]): SoundboardSound;
+  construct(data: CacheEntityTypes["soundboardSounds"]): SoundboardSound;
   keyOf(data: CacheEntityTypes["soundboardSounds"]): string;
   resolveKey(soundId: string): string;
   /**
@@ -4829,7 +4863,7 @@ export interface StageInstanceCreateOptions extends StageInstanceEditOptions {
 export declare class StageInstanceManager extends CachedManager<"stageInstances", StageInstance, [channelId: string]> {
   readonly guildId: string;
   constructor(client: GatewayClient, guildId: string);
-  createStructure(data: CacheEntityTypes["stageInstances"]): StageInstance;
+  construct(data: CacheEntityTypes["stageInstances"]): StageInstance;
   keyOf(data: CacheEntityTypes["stageInstances"]): string;
   resolveKey(channelId: string): string;
   _hydrate(data: CacheEntityTypes["stageInstances"]): Awaitable<StageInstance>;
@@ -4998,7 +5032,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);
-  createStructure(data: CacheEntityTypes["integrations"]): Integration;
+  construct(data: CacheEntityTypes["integrations"]): Integration;
   keyOf(data: CacheEntityTypes["integrations"]): string;
   resolveKey(integrationId: string): string;
   /**
@@ -5122,7 +5156,7 @@ export declare class GuildStickerManager extends CachedManager<"stickers", Stick
    */
   readonly guildId: string;
   constructor(client: GatewayClient, guildId: string);
-  createStructure(data: CacheEntityTypes["stickers"]): Sticker;
+  construct(data: CacheEntityTypes["stickers"]): Sticker;
   keyOf(data: CacheEntityTypes["stickers"]): string;
   /**
    * Adds a sticker to the cache, and its uploader to `client.users`.
@@ -5168,6 +5202,9 @@ export declare class GuildStickerManager extends CachedManager<"stickers", Stick
    * @remarks
    * It enumerates the whole entity cache, which a Redis store answers from its index: prefer `fetchAll` when the
    * cache may be incomplete.
+   *
+   * @returns The cached entries, `[]` when this entity is not cached.
+   * @throws {TypeError} When the store cannot enumerate its entries.
    */
   listCached(): Promise<Sticker[]>;
   protected fetchRaw(stickerId: string): Promise<{
@@ -5968,7 +6005,7 @@ export declare class GuildInviteManager extends CachedManager<"invites", GuildIn
    */
   readonly guildId: string;
   constructor(client: GatewayClient, guildId: string);
-  createStructure(data: CacheEntityTypes["invites"]): GuildInvite;
+  construct(data: CacheEntityTypes["invites"]): GuildInvite;
   keyOf(data: CacheEntityTypes["invites"]): string;
   /**
    * Adds an invite to the cache, and its inviter and target user to `client.users`.
@@ -6126,7 +6163,7 @@ export interface GuildOnboardingEditOptions {
  */
 export declare class GuildManager extends CachedManager<"guilds", Guild, [guildId: string]> {
   constructor(client: GatewayClient);
-  createStructure(data: CacheEntityTypes["guilds"]): Guild;
+  construct(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
@@ -7461,7 +7498,7 @@ export declare function createChannel(data: CacheEntityTypes["channels"], relati
  */
 export declare class ChannelManager extends CachedManager<"channels", AnyChannel, [channelId: string]> {
   constructor(client: GatewayClient);
-  createStructure(data: CacheEntityTypes["channels"]): AnyChannel;
+  construct(data: CacheEntityTypes["channels"]): AnyChannel;
   keyOf(data: CacheEntityTypes["channels"]): string;
   _hydrate(data: CacheEntityTypes["channels"]): Awaitable<AnyChannel>;
   /**
@@ -7539,7 +7576,7 @@ export declare class ChannelManager extends CachedManager<"channels", AnyChannel
  */
 export declare class VoiceStateManager extends CachedManager<"voiceStates", VoiceState, [guildId: string, userId: string]> {
   constructor(client: GatewayClient);
-  createStructure(data: CacheEntityTypes["voiceStates"]): VoiceState;
+  construct(data: CacheEntityTypes["voiceStates"]): VoiceState;
   keyOf(data: CacheEntityTypes["voiceStates"]): string;
   resolveKey(guildId: string, userId: string): string;
   _hydrate(data: CacheEntityTypes["voiceStates"]): Awaitable<VoiceState>;
@@ -7547,6 +7584,8 @@ export declare class VoiceStateManager extends CachedManager<"voiceStates", Voic
    * Lists the cached voice states of a guild.
    *
    * @param guildId The ID of the guild.
+   * @returns The cached entries, `[]` when this entity is not cached.
+   * @throws {TypeError} When the store cannot enumerate its entries.
    */
   listCached(guildId: string): Promise<VoiceState[]>;
   protected fetchRaw(guildId: string, userId: string): Promise<{
@@ -7576,7 +7615,7 @@ export declare class VoiceStateManager extends CachedManager<"voiceStates", Voic
  */
 export declare class PresenceManager extends CachedManager<"presences", Presence, [guildId: string, userId: string]> {
   constructor(client: GatewayClient);
-  createStructure(data: CacheEntityTypes["presences"]): Presence;
+  construct(data: CacheEntityTypes["presences"]): Presence;
   keyOf(data: CacheEntityTypes["presences"]): string;
   resolveKey(guildId: string, userId: string): string;
   _hydrate(data: CacheEntityTypes["presences"]): Awaitable<Presence>;
@@ -7584,6 +7623,8 @@ export declare class PresenceManager extends CachedManager<"presences", Presence
    * Lists the cached presences of a guild.
    *
    * @param guildId The ID of the guild.
+   * @returns The cached entries, `[]` when this entity is not cached.
+   * @throws {TypeError} When the store cannot enumerate its entries.
    */
   listCached(guildId: string): Promise<Presence[]>;
   protected fetchRaw(guildId: string, userId: string): Promise<CacheEntityTypes["presences"]>;
@@ -7595,7 +7636,7 @@ export declare class PresenceManager extends CachedManager<"presences", Presence
  */
 export declare class UserManager extends CachedManager<"users", User, [userId: string]> {
   constructor(client: GatewayClient);
-  createStructure(data: CacheEntityTypes["users"]): User;
+  construct(data: CacheEntityTypes["users"]): User;
   keyOf(data: CacheEntityTypes["users"]): string;
   resolveKey(userId: string): string;
   /**
@@ -7762,7 +7803,8 @@ export declare const DispatchHandlers: { [Type in GatewayDispatchEvents]?: AnyDi
  * The table of the dispatches that turn into several events, diffed against the cache.
  *
  * @remarks
- * Without a cache there is nothing to diff against, so these dispatches only reach `raw`.
+ * Their aggregate event (e.g. `guildEmojisUpdate`) is always emitted. Without a cache there is nothing to diff
+ * against, so the granular events are not.
  */
 export declare const MultiDispatchHandlers: { [Type in GatewayDispatchEvents]?: MultiDispatchHandler<Type>; };
 //#endregion
@@ -7914,9 +7956,58 @@ export interface GatewayClientOptions extends ClientOptions, GatewayClientMessag
    * 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.
    *
+   * @remarks
+   * Every entity cache is optional: an entity kind the cache does not hold is simply not cached, see
+   * `createInMemoryCache`'s `entities` option.
+   *
    * @default undefined
    */
   cache?: Cache;
+  /**
+   * 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}.
+   *
+   * @example
+   * ```typescript
+   * import { MemoryEntityCache } from '@wolfstar/plugin-cache';
+   *
+   * // Cache guilds, channels, and roles only.
+   * const client = new GatewayClient({
+   *   intents,
+   *   makeCache: (entity) => (['guilds', 'channels', 'roles'].includes(entity) ? new MemoryEntityCache() : null),
+   * });
+   * ```
+   *
+   * @default undefined
+   */
+  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.
+   *
+   * @example
+   * ```typescript
+   * // Do not cache bots, and forget messages after an hour.
+   * policies: { users: { filter: (user) => !user.bot }, messages: { ttl: () => 3_600_000 } }
+   * ```
+   *
+   * @default undefined
+   */
+  policies?: CachePolicies;
+  /**
+   * What the managers do when a cache read or write fails, e.g. while Redis is unreachable. A `cacheError` event is
+   * emitted either way.
+   *
+   * - `"miss"`: treat it as a cache miss, falling back to the API or to the data at hand.
+   * - `"throw"`: reject with the error.
+   *
+   * @remarks
+   * Dispatches follow {@link GatewayClientOptions.cacheFailure} instead.
+   *
+   * @default "miss"
+   */
+  cacheErrors?: "miss" | "throw";
   /**
    * Additional options for the underlying `@discordjs/ws` `WebSocketManager`, e.g. `compression` or
    * `initialPresence`.
@@ -8073,6 +8164,10 @@ export declare class GatewayClient extends Client {
    * What happens to a dispatch whose cache read or write fails, see {@link GatewayClientOptions.cacheFailure}.
    */
   readonly cacheFailure: "skip" | "emitUncached";
+  /**
+   * What the managers do when a cache read or write fails, see {@link GatewayClientOptions.cacheErrors}.
+   */
+  readonly cacheErrors: "miss" | "throw";
   /**
    * See {@link GatewayClientOptions.dispatchTimeout}.
    */
@@ -8199,6 +8294,8 @@ export declare class GatewayClient extends Client {
    * They are the guilds the bot left while it was disconnected, or while the process was down with a persistent
    * cache. Discord does not replay those removals on a new session, so the cache would otherwise keep them forever.
    *
+   * It needs a guilds cache able to enumerate its entries, and is skipped without one.
+   *
    * It is best effort: any failure (cache unreachable, unknown shard count) is reported through `error` and stops the
    * reconciliation, keeping the remaining guilds, but never fails `READY` itself.
    *
@@ -8335,6 +8432,23 @@ export declare class Typing extends Structure<GatewayTypingStartDispatchData> {
 }
 //#endregion
 //#region src/util/events.d.ts
+/**
+ * Where a cache failure reported by the `cacheError` event happened.
+ */
+export interface CacheErrorContext {
+  /**
+   * The entity cache that failed.
+   */
+  entity: CacheEntityName;
+  /**
+   * The key of the entry, `null` for operations spanning the whole cache.
+   */
+  key: string | null;
+  /**
+   * The operation that failed.
+   */
+  operation: "get" | "set" | "upsert" | "delete";
+}
 /**
  * What a reaction event says besides the reaction and the user.
  */
@@ -8397,6 +8511,11 @@ export interface GatewayEventMap {
    * Emitted when a shard runs into an error.
    */
   shardError: [error: Error, shardId: number];
+  /**
+   * Emitted when a manager's cache read or write fails, e.g. while Redis is unreachable. With the default
+   * `cacheErrors: "miss"`, the manager then carries on as if the entry was not cached.
+   */
+  cacheError: [error: unknown, context: CacheErrorContext];
   guildCreate: [guild: Guild];
   guildUpdate: [oldGuild: Guild | null, newGuild: Guild];
   /**
@@ -8470,12 +8589,21 @@ export interface GatewayEventMap {
   guildRoleDelete: [role: Role | null, data: GatewayGuildRoleDeleteDispatchData];
   userUpdate: [oldUser: User | null, newUser: User];
   /**
-   * Emitted for each emoji a `GUILD_EMOJIS_UPDATE` adds, compared with the cache. Without a cache, the emoji events
-   * are not emitted: listen to `raw` instead.
+   * Emitted for every `GUILD_EMOJIS_UPDATE`, with every emoji the guild now has. Always emitted, cache or not: the
+   * granular `emojiCreate`, `emojiUpdate`, and `emojiDelete` need the previous emojis, so the emojis cache.
+   */
+  guildEmojisUpdate: [guildId: string, emojis: GuildEmoji[]];
+  /**
+   * Emitted for each emoji a `GUILD_EMOJIS_UPDATE` adds, compared with the cache. Without an emojis cache (able to
+   * enumerate its entries), the emoji events are not emitted: listen to `guildEmojisUpdate` instead.
    */
   emojiCreate: [emoji: GuildEmoji];
   emojiUpdate: [oldEmoji: GuildEmoji, newEmoji: GuildEmoji];
   emojiDelete: [emoji: GuildEmoji];
+  /**
+   * Emitted for every `GUILD_STICKERS_UPDATE`, with every sticker the guild now has, like `guildEmojisUpdate`.
+   */
+  guildStickersUpdate: [guildId: string, stickers: Sticker[]];
   /**
    * Emitted for each sticker a `GUILD_STICKERS_UPDATE` adds, compared with the cache, like the emoji events.
    */
@@ -8577,6 +8705,7 @@ export declare enum GatewayEvents {
   ShardResume = "shardResume",
   ShardClose = "shardClose",
   ShardError = "shardError",
+  CacheError = "cacheError",
   GuildCreate = "guildCreate",
   GuildUpdate = "guildUpdate",
   GuildDelete = "guildDelete",
@@ -8609,9 +8738,11 @@ export declare enum GatewayEvents {
   GuildRoleUpdate = "guildRoleUpdate",
   GuildRoleDelete = "guildRoleDelete",
   UserUpdate = "userUpdate",
+  GuildEmojisUpdate = "guildEmojisUpdate",
   EmojiCreate = "emojiCreate",
   EmojiUpdate = "emojiUpdate",
   EmojiDelete = "emojiDelete",
+  GuildStickersUpdate = "guildStickersUpdate",
   StickerCreate = "stickerCreate",
   StickerUpdate = "stickerUpdate",
   StickerDelete = "stickerDelete",
@@ -8968,5 +9099,5 @@ export declare function computeTargetPermissions(guildId: Snowflake, overwrites:
  */
 export declare function computePermissionsIn(channel: AnyChannel | Snowflake, target: GuildMember | Role | Snowflake): Promise<PermissionsBitField>;
 //#endregion
-export { type AttachmentPayload, type AttachmentResolvable, type BaseMessageOptions, BitField, type BitFieldResolvable, type BufferResolvable, type ForwardOptions, type GatewayClientMessageDefaults, type JSONEncodable, type MessageCreateOptions, type MessageEditOptions, type MessageMentionOptions, type MessagePayloadContext, type MessagePayloadOptions, type MessagePayloadResolvable, type MessageTarget, PermissionsBitField, type PollCreateData, type RawAPIType, type ReplyOptions, type ResolvedMessagePayload, type StructureCreator, type WebhookMessageCreateOptions, type WebhookMessageEditOptions, type WebhookMessageOptions, type WebhookThreadOptions, type isPromiseLike, type pickCached, type whenAll, type whenCachedMap };
+export { type AttachmentPayload, type AttachmentResolvable, CachedManager as BaseManager, type BaseMessageOptions, BitField, type BitFieldResolvable, type BufferResolvable, type ForwardOptions, type GatewayClientMessageDefaults, type JSONEncodable, type MessageCreateOptions, type MessageEditOptions, type MessageMentionOptions, type MessagePayloadContext, type MessagePayloadOptions, type MessagePayloadResolvable, type MessageTarget, PermissionsBitField, type PollCreateData, type RawAPIType, type ReplyOptions, type ResolvedMessagePayload, type StructureCreator, type WebhookMessageCreateOptions, type WebhookMessageEditOptions, type WebhookMessageOptions, type WebhookThreadOptions, type isPromiseLike, type pickCached, type whenAll, type whenCachedMap };
 //# sourceMappingURL=index.d.ts.map