@wolfstar/plugin-gateway 0.2.0-next-20260926221130 → 0.2.0-next-20260926221949

package/README.md

@@ -102,6 +102,7 @@ On top of the `Client` options:
 | `guildMemberUpdate`                                       | `oldMember \| null`, `newMember`               |
 | `guildMemberRemove`                                       | `member \| null`, `data`                       |
 | `guildRoleCreate` / `guildRoleUpdate` / `guildRoleDelete` | same shapes as members                         |
+| `guildMembersChunk`                                       | `members`, `guild \| null`, `data`             |
 | `userUpdate`                                              | `oldUser \| null`, `newUser`                   |
 | `emojiCreate` / `emojiDelete`                             | `emoji`                                        |
 | `emojiUpdate`                                             | `oldEmoji`, `newEmoji`                         |
@@ -242,7 +243,8 @@ events.
   `{ force: true }` after the IDs to always hit the API, `{ cache: false }` not to store the result:
   `client.messages.fetch(channelId, messageId, { force: true })`;
 - `refresh` is `fetch` with `{ force: true }`;
-- `resolve` takes a structure (returned as is) or a cache key, like discord.js's `resolve`.
+- `resolve` takes a structure (returned as is) or a cache key, like discord.js's `resolve`;
+- `cached` is `get` without the `await`, for a synchronous cache, see below.
 
 Like discord.js's `CachedManager#_add`, every API payload goes through the manager's `_add`, which
 merges it into the cached entry (the fields a partial payload lacks keep their cached value) and
@@ -258,6 +260,32 @@ the copy embedded in its payload.
 Swapping `createInMemoryCache()` for `createRedisCache({ redis })` changes nothing else, see
 [`@wolfstar/plugin-cache`](../plugin-cache).
 
+### Synchronous reads
+
+Every manager method above is asynchronous since the cache can be Redis, which makes a hot path
+such as a message filter await every lookup even when the cache lives in memory. With a synchronous
+cache (`createInMemoryCache()`), `cached` takes the same arguments as `get` and returns the same
+structure, relations included, without a promise:
+
+```ts
+client.on("messageCreate", (message) => {
+  const member = client.members.cached(message.guildId!, message.author.id);
+  if (member?.roleIds.includes(mutedRoleId)) return;
+  // ...
+});
+```
+
+It returns `undefined` on a miss, or when the client has no cache, 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:
+
+```ts
+const user = client.users.cache?.synchronous
+  ? client.users.cached(userId)
+  : await client.users.get(userId);
+```
+
 ## Structures
 
 `User`, `Guild`, `Message`, `GuildMember`, and `Role` wrap the raw data behind typed getters.
@@ -327,7 +355,9 @@ The client also has discord.js's `fetchSticker`, `fetchStickerPacks`, and `fetch
 ### Users, members and roles
 
 They follow discord.js's API, with one difference: anything discord.js reads synchronously from its
-cache is asynchronous here, since the cache can be Redis.
+cache is asynchronous here, since the cache can be Redis. With an in-memory cache, `cached` reads
+`client.users`, `client.members` and `client.roles` synchronously, see
+[Synchronous reads](#synchronous-reads).
 
 ```ts
 const member = await client.members.fetch(guildId, userId);
@@ -352,6 +382,22 @@ member counts. Permissions are `PermissionsBitField`s, computed like Discord doe
 administrators get everything, everyone else `@everyone` plus their roles. Channel overwrites
 apply through `member.fetchPermissionsIn(channel)`, see below.
 
+`client.members.request(guildId, options)` (or `guild.requestMembers(options)`, discord.js:
+`guild.members.fetch()`) asks the guild's shard for its members over the gateway instead of REST:
+every member by default, those matching a `query` (with a `limit`), or up to 100 `userIds`, with
+their `presences` if asked. It resolves with the `GuildMember`s once Discord's last
+`GUILD_MEMBERS_CHUNK` for its `nonce` is cached, so `client.members.get` sees them, and rejects
+with a `GuildMembersTimeoutError` when no chunk arrives for `time` milliseconds (120 seconds by
+default), or a `GuildMembersRateLimitError` when Discord answers with `RATE_LIMITED`. Every chunk
+is also emitted as `guildMembersChunk`, whose `data.not_found` lists the requested IDs that are
+not members. Requesting every member or a query needs the `GuildMembers` intent, and presences the
+`GuildPresences` one. `@discordjs/ws` keeps the requests within the gateway's rate limit.
+
+```ts
+const members = await client.members.request(guildId); // every member
+const [wolf] = await client.members.request(guildId, { userIds: [userId], presences: true });
+```
+
 ### Channels and permissions
 
 Guild channels follow discord.js: `edit`, `setName`, `clone`, `delete`, and the setters of each

package/dist/esm/index.d.ts

@@ -2,7 +2,7 @@ import { Client, ClientOptions, Listener } from "@wolfstar/http-framework";
 import { OptionalWebSocketManagerOptions, ShardRange, WebSocketManager } from "@discordjs/ws";
 import { Client as Client$1 } from "@discordjs/core";
 import { Awaitable, Cache, CacheEntityName, CacheEntityTypes, EntityCache } from "@wolfstar/plugin-cache";
-import { 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, APIOverwrite, APIPartialEmoji, APIPoll, APIPollAnswer, APIReaction, APIRole, APIRoleTags, APISoundboardSound, APIStageInstance, APISticker, APIStickerPack, APITemplate, APIThreadChannel, APIThreadMember, APIUser, APIUserPrimaryGuild, APIVoiceRegion, APIWebhook, ActivityFlags, ActivityType, AttachmentFlags, AuditLogEvent, AutoModerationRuleEventType, AutoModerationRuleKeywordPresetType, AutoModerationRuleTriggerType, ChannelFlags, ChannelType, ForumLayoutType, GatewayActivity, GatewayActivityAssets, GatewayActivityUpdateData, GatewayAutoModerationActionExecutionDispatchData, GatewayChannelPinsUpdateDispatchData, GatewayDispatchEvents, GatewayDispatchPayload, GatewayGuildDeleteDispatchData, GatewayGuildIntegrationsUpdateDispatchData, GatewayGuildMemberRemoveDispatchData, GatewayGuildRoleDeleteDispatchData, GatewayGuildScheduledEventUserAddDispatchData, GatewayGuildScheduledEventUserRemoveDispatchData, GatewayGuildSoundboardSoundDeleteDispatchData, GatewayIntegrationDeleteDispatchData, GatewayIntentBits, GatewayInviteCreateDispatchData, GatewayInviteDeleteDispatchData, GatewayMessageDeleteBulkDispatchData, GatewayMessageDeleteDispatchData, GatewayMessageReactionRemoveAllDispatchData, GatewayPresenceClientStatus, GatewayPresenceUpdateData, GatewayReadyDispatchData, GatewayThreadDeleteDispatchData, GatewayThreadListSync, GatewayThreadMembersUpdateDispatchData, GatewayTypingStartDispatchData, GatewayVoiceServerUpdateDispatchData, GatewayWebhooksUpdateDispatchData, GuildDefaultMessageNotifications, GuildExplicitContentFilter, GuildMemberFlags, GuildOnboardingMode, GuildOnboardingPromptType, GuildPremiumTier, GuildScheduledEventEntityType, GuildScheduledEventPrivacyLevel, GuildScheduledEventStatus, GuildSystemChannelFlags, GuildVerificationLevel, GuildWidgetStyle, InviteTargetType, InviteType, Locale, MessageFlags, MessageType, OverwriteType, PermissionFlagsBits, PresenceUpdateReceiveStatus, PresenceUpdateStatus, RESTGetAPIGuildVanityUrlResult, RESTPatchAPIChannelJSONBody, RESTPatchAPIChannelMessageJSONBody, RESTPatchAPIGuildJSONBody, RESTPatchAPIWebhookWithTokenMessageJSONBody, RESTPostAPIChannelMessageJSONBody, RESTPostAPIGuildsJSONBody, RESTPostAPIWebhookWithTokenJSONBody, ReactionType, RoleFlags, Snowflake, SortOrderType, StageInstancePrivacyLevel, StickerFormatType, ThreadAutoArchiveDuration, ThreadChannelType, UserFlags, VideoQualityMode, WebhookType } from "discord-api-types/v10";
+import { 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, APIOverwrite, APIPartialEmoji, APIPoll, APIPollAnswer, APIReaction, APIRole, APIRoleTags, APISoundboardSound, APIStageInstance, APISticker, APIStickerPack, APITemplate, APIThreadChannel, APIThreadMember, APIUser, APIUserPrimaryGuild, APIVoiceRegion, APIWebhook, ActivityFlags, ActivityType, 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, MessageType, OverwriteType, PermissionFlagsBits, PresenceUpdateReceiveStatus, PresenceUpdateStatus, RESTGetAPIGuildVanityUrlResult, RESTPatchAPIChannelJSONBody, RESTPatchAPIChannelMessageJSONBody, RESTPatchAPIGuildJSONBody, RESTPatchAPIWebhookWithTokenMessageJSONBody, RESTPostAPIChannelMessageJSONBody, RESTPostAPIGuildsJSONBody, RESTPostAPIWebhookWithTokenJSONBody, ReactionType, RoleFlags, Snowflake, SortOrderType, StageInstancePrivacyLevel, StickerFormatType, ThreadAutoArchiveDuration, ThreadChannelType, UserFlags, VideoQualityMode, WebhookType } from "discord-api-types/v10";
 import { BaseImageURLOptions, EmojiURLOptions, ImageURLOptions, RawFile } from "@discordjs/rest";
 //#region src/structures/Structure.d.ts
 /*!
@@ -647,6 +647,9 @@ export interface AddOptions {
  * 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.
  *
+ * Every method is asynchronous since the cache can be Redis, except {@link CachedManager.cached}, which reads a
+ * synchronous cache (`createInMemoryCache`) without awaiting it.
+ *
  * 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
@@ -677,6 +680,36 @@ export declare abstract class CachedManager<Name extends CacheEntityName, Value
    * @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.
+   *
+   * @example
+   * ```typescript
+   * const member = client.members.cached(guildId, 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;
+  /**
+   * 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
+   */
+  _get(...args: Args): Awaitable<Value | undefined>;
   /**
    * Resolves a structure or a cache key to a structure, like discord.js's `DataManager#resolve`.
    *
@@ -710,12 +743,19 @@ export declare abstract class CachedManager<Name extends CacheEntityName, Value
    */
   resolveData(data: CacheEntityTypes[Name]): Promise<Value>;
   /**
-   * Gets a guild from the cache, to resolve the `guild` of a structure.
+   * The {@link Awaitable} counterpart of {@link CachedManager.resolveData}, synchronous when every cache it reads is.
+   *
+   * @param data The raw data.
+   * @internal
+   */
+  _resolveData(data: CacheEntityTypes[Name]): Awaitable<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.
    * @returns The guild, or `null` when there is no ID or the guild is not cached.
    */
-  protected cachedGuild(guildId: string | null | undefined): Promise<Guild | null>;
+  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}.
@@ -723,6 +763,15 @@ export declare abstract class CachedManager<Name extends CacheEntityName, Value
    * @param data The raw data.
    */
   hydrate(data: CacheEntityTypes[Name]): Promise<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.
+   *
+   * @param data The raw data.
+   * @internal
+   */
+  _hydrate(data: CacheEntityTypes[Name]): Awaitable<Value>;
   /**
    * Gets an entity from the cache, fetching it from the API (and caching it) on a cache miss.
    *
@@ -774,11 +823,11 @@ export declare abstract class CachedManager<Name extends CacheEntityName, Value
    */
   protected storeRaw(key: string, raw: CacheEntityTypes[Name]): Promise<void>;
   /**
-   * Gets an entity from the cache by its key.
+   * 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): Promise<Value | undefined>;
+  protected getByKey(key: string): Awaitable<Value | undefined>;
 }
 //#endregion
 //#region src/managers/AutoModerationRuleManager.d.ts
@@ -816,7 +865,7 @@ export declare class AutoModerationRuleManager extends CachedManager<"autoModera
   createStructure(data: CacheEntityTypes["autoModerationRules"]): AutoModerationRule;
   keyOf(data: CacheEntityTypes["autoModerationRules"]): string;
   resolveKey(ruleId: string): string;
-  hydrate(data: CacheEntityTypes["autoModerationRules"]): Promise<AutoModerationRule>;
+  _hydrate(data: CacheEntityTypes["autoModerationRules"]): Awaitable<AutoModerationRule>;
   /**
    * Fetches every rule of the guild, and caches them.
    */
@@ -1265,10 +1314,53 @@ export interface GuildPruneOptions {
   count?: boolean;
   reason?: string;
 }
+/**
+ * The options to request the members of a guild over the gateway with. Without `query` nor `userIds`, every member is
+ * requested.
+ */
+export interface GuildMembersRequestOptions {
+  /**
+   * The prefix of the usernames and nicknames to match, `""` for every member. Exclusive with `userIds`.
+   *
+   * @default ""
+   */
+  query?: string;
+  /**
+   * How many members to match with `query`, `0` for no limit (only with an empty `query`).
+   *
+   * @default 0
+   */
+  limit?: number;
+  /**
+   * The IDs of the users to request, up to 100. Exclusive with `query`. The ones that are not members are left out of
+   * the result, and listed in the `not_found` of the `guildMembersChunk` data. An empty array is ignored, like omitting
+   * it.
+   */
+  userIds?: readonly string[];
+  /**
+   * Whether to also receive (and cache) the members' presences. Needs the `GuildPresences` intent.
+   *
+   * @default false
+   */
+  presences?: boolean;
+  /**
+   * The nonce identifying the request's chunks, up to 32 bytes.
+   *
+   * @default A random one.
+   */
+  nonce?: string;
+  /**
+   * How long to wait for each chunk, in milliseconds, before rejecting with a `GuildMembersTimeoutError`.
+   *
+   * @default 120_000
+   */
+  time?: number;
+}
 /**
  * Manages the {@link GuildMember}s known to the client.
  */
 export declare class GuildMemberManager extends CachedManager<"members", GuildMember, [guildId: string, userId: string]> {
+  #private;
   constructor(client: GatewayClient);
   createStructure(data: CacheEntityTypes["members"]): GuildMember;
   keyOf(data: CacheEntityTypes["members"]): string;
@@ -1278,7 +1370,7 @@ export declare class GuildMemberManager extends CachedManager<"members", GuildMe
    * @internal
    */
   _add(data: CacheEntityTypes["members"], cache?: boolean, options?: AddOptions): Promise<GuildMember>;
-  hydrate(data: CacheEntityTypes["members"]): Promise<GuildMember>;
+  _hydrate(data: CacheEntityTypes["members"]): Awaitable<GuildMember>;
   resolveKey(guildId: string, userId: string): string;
   /**
    * Fetches the bot's own member in a guild.
@@ -1306,6 +1398,32 @@ export declare class GuildMemberManager extends CachedManager<"members", GuildMe
     query: string;
     limit?: number;
   }): Promise<GuildMember[]>;
+  /**
+   * Requests the members of a guild over the gateway, every one of them by default, and caches them. discord.js:
+   * `guild.members.fetch()` without a user.
+   *
+   * @remarks
+   * Unlike {@link GuildMemberManager.list}, it gets the members of a large guild in one go, in chunks of up to 1000
+   * that are also emitted as `guildMembersChunk`. Requesting every member or a `query` needs the `GuildMembers`
+   * intent. The request is sent on the guild's shard, which must be one this client runs.
+   *
+   * @param guildId The ID of the guild.
+   * @param options Which members to request.
+   * @returns The members, once the last chunk is cached.
+   */
+  request(guildId: string, options?: GuildMembersRequestOptions): Promise<GuildMember[]>;
+  /**
+   * Adds a cached chunk of members to the request with its nonce, resolving it with the last chunk.
+   *
+   * @internal
+   */
+  handleChunk(members: GuildMember[], data: GatewayGuildMembersChunkDispatchData): void;
+  /**
+   * Rejects the request a `RATE_LIMITED` dispatch refers to, which gets no chunks at all.
+   *
+   * @internal
+   */
+  handleRateLimited(data: GatewayRateLimitedDispatchData): void;
   /**
    * Adds a user to a guild, or fetches their member when they are in it already.
    *
@@ -1409,6 +1527,7 @@ export declare class GuildMemberManager extends CachedManager<"members", GuildMe
     guild_id: string;
   }>;
   private store;
+  private settle;
   private updateCachedRoles;
 }
 //#endregion
@@ -1452,7 +1571,7 @@ export declare class RoleManager extends CachedManager<"roles", Role, [guildId:
   constructor(client: GatewayClient);
   createStructure(data: CacheEntityTypes["roles"]): Role;
   keyOf(data: CacheEntityTypes["roles"]): string;
-  hydrate(data: CacheEntityTypes["roles"]): Promise<Role>;
+  _hydrate(data: CacheEntityTypes["roles"]): Awaitable<Role>;
   resolveKey(guildId: string, roleId: string): string;
   /**
    * Fetches every role of a guild from the API, and caches them.
@@ -2410,7 +2529,7 @@ export declare class ThreadMemberManager extends CachedManager<"threadMembers",
    * @internal
    */
   _add(data: CacheEntityTypes["threadMembers"], cache?: boolean, options?: AddOptions): Promise<ThreadMember>;
-  hydrate(data: CacheEntityTypes["threadMembers"]): Promise<ThreadMember>;
+  _hydrate(data: CacheEntityTypes["threadMembers"]): Awaitable<ThreadMember>;
   /**
    * Fetches a member of a thread from the API, bypassing the cache, and caches it.
    *
@@ -2639,7 +2758,7 @@ export declare class ThreadManager extends CachedManager<"threads", AnyThreadCha
   constructor(client: GatewayClient);
   createStructure(data: CacheEntityTypes["threads"]): AnyThreadChannel;
   keyOf(data: CacheEntityTypes["threads"]): string;
-  hydrate(data: CacheEntityTypes["threads"]): Promise<AnyThreadChannel>;
+  _hydrate(data: CacheEntityTypes["threads"]): Awaitable<AnyThreadChannel>;
   resolveKey(threadId: string): string;
   /**
    * Creates a thread in a channel. With `message`, creates a post of a forum or media channel.
@@ -2711,7 +2830,7 @@ export declare class MessageManager extends CachedManager<"messages", Message, [
    * @internal
    */
   _add(data: CacheEntityTypes["messages"], cache?: boolean, options?: AddOptions): Promise<Message>;
-  hydrate(data: CacheEntityTypes["messages"]): Promise<Message>;
+  _hydrate(data: CacheEntityTypes["messages"]): Awaitable<Message>;
   resolveKey(channelId: string, messageId: string): string;
   /**
    * Lists the messages of a channel, newest first, and caches them.
@@ -3745,7 +3864,7 @@ export declare class GuildBanManager extends CachedManager<"bans", GuildBan, [us
    * @internal
    */
   _add(data: CacheEntityTypes["bans"], cache?: boolean, options?: AddOptions): Promise<GuildBan>;
-  hydrate(data: CacheEntityTypes["bans"]): Promise<GuildBan>;
+  _hydrate(data: CacheEntityTypes["bans"]): Awaitable<GuildBan>;
   /**
    * Lists the bans of the guild, paginated by user ID, and caches them.
    *
@@ -3942,7 +4061,7 @@ export declare class GuildScheduledEventManager extends CachedManager<"scheduled
    * @internal
    */
   _add(data: CacheEntityTypes["scheduledEvents"], cache?: boolean, options?: AddOptions): Promise<GuildScheduledEvent>;
-  hydrate(data: CacheEntityTypes["scheduledEvents"]): Promise<GuildScheduledEvent>;
+  _hydrate(data: CacheEntityTypes["scheduledEvents"]): Awaitable<GuildScheduledEvent>;
   /**
    * Fetches every scheduled event of the guild, and caches them.
    *
@@ -4076,7 +4195,7 @@ export declare class GuildSoundboardSoundManager extends CachedManager<"soundboa
    * @internal
    */
   _add(data: CacheEntityTypes["soundboardSounds"], cache?: boolean, options?: AddOptions): Promise<SoundboardSound>;
-  hydrate(data: CacheEntityTypes["soundboardSounds"]): Promise<SoundboardSound>;
+  _hydrate(data: CacheEntityTypes["soundboardSounds"]): Awaitable<SoundboardSound>;
   /**
    * Fetches every soundboard sound of the guild, and caches them.
    */
@@ -4185,7 +4304,7 @@ export declare class StageInstanceManager extends CachedManager<"stageInstances"
   createStructure(data: CacheEntityTypes["stageInstances"]): StageInstance;
   keyOf(data: CacheEntityTypes["stageInstances"]): string;
   resolveKey(channelId: string): string;
-  hydrate(data: CacheEntityTypes["stageInstances"]): Promise<StageInstance>;
+  _hydrate(data: CacheEntityTypes["stageInstances"]): Awaitable<StageInstance>;
   /**
    * Starts a stage in a stage channel.
    *
@@ -4416,7 +4535,7 @@ export declare class GuildEmojiManager extends CachedManager<"emojis", GuildEmoj
    * @internal
    */
   _add(data: CacheEntityTypes["emojis"], cache?: boolean, options?: AddOptions): Promise<GuildEmoji>;
-  hydrate(data: CacheEntityTypes["emojis"]): Promise<GuildEmoji>;
+  _hydrate(data: CacheEntityTypes["emojis"]): Awaitable<GuildEmoji>;
   resolveKey(emojiId: string): string;
   /**
    * Fetches every emoji of the guild, and caches them.
@@ -4557,7 +4676,7 @@ export declare class GuildIntegrationManager extends CachedManager<"integrations
    * @internal
    */
   _add(data: CacheEntityTypes["integrations"], cache?: boolean, options?: AddOptions): Promise<Integration>;
-  hydrate(data: CacheEntityTypes["integrations"]): Promise<Integration>;
+  _hydrate(data: CacheEntityTypes["integrations"]): Awaitable<Integration>;
   /**
    * Fetches every integration of the guild, and caches them.
    */
@@ -4733,7 +4852,7 @@ export declare class GuildInviteManager extends CachedManager<"invites", GuildIn
    * @internal
    */
   _add(data: CacheEntityTypes["invites"], cache?: boolean, options?: AddOptions): Promise<GuildInvite>;
-  hydrate(data: CacheEntityTypes["invites"]): Promise<GuildInvite>;
+  _hydrate(data: CacheEntityTypes["invites"]): Awaitable<GuildInvite>;
   resolveKey(code: string): string;
   /**
    * Fetches every invite of the guild, with their metadata, and caches them.
@@ -4929,7 +5048,7 @@ export declare class GuildStickerManager extends CachedManager<"stickers", Stick
    * @internal
    */
   _add(data: CacheEntityTypes["stickers"], cache?: boolean, options?: AddOptions): Promise<Sticker>;
-  hydrate(data: CacheEntityTypes["stickers"]): Promise<Sticker>;
+  _hydrate(data: CacheEntityTypes["stickers"]): Awaitable<Sticker>;
   resolveKey(stickerId: string): string;
   /**
    * Fetches every sticker of the guild, and caches them.
@@ -5751,6 +5870,13 @@ export declare class Guild extends AnonymousGuild<CacheEntityTypes["guilds"]> {
    * Fetches the member owning this guild.
    */
   fetchOwner(): Promise<GuildMember>;
+  /**
+   * Requests the members of this guild over the gateway, every one of them by default, and caches them. discord.js:
+   * `guild.members.fetch()`. See `client.members.request`.
+   *
+   * @param options Which members to request.
+   */
+  requestMembers(options?: GuildMembersRequestOptions): Promise<GuildMember[]>;
   /**
    * Fetches every invite of this guild.
    */
@@ -6195,7 +6321,7 @@ export declare class VoiceStateManager extends CachedManager<"voiceStates", Voic
   createStructure(data: CacheEntityTypes["voiceStates"]): VoiceState;
   keyOf(data: CacheEntityTypes["voiceStates"]): string;
   resolveKey(guildId: string, userId: string): string;
-  hydrate(data: CacheEntityTypes["voiceStates"]): Promise<VoiceState>;
+  _hydrate(data: CacheEntityTypes["voiceStates"]): Awaitable<VoiceState>;
   /**
    * Lists the cached voice states of a guild.
    *
@@ -6232,7 +6358,7 @@ export declare class PresenceManager extends CachedManager<"presences", Presence
   createStructure(data: CacheEntityTypes["presences"]): Presence;
   keyOf(data: CacheEntityTypes["presences"]): string;
   resolveKey(guildId: string, userId: string): string;
-  hydrate(data: CacheEntityTypes["presences"]): Promise<Presence>;
+  _hydrate(data: CacheEntityTypes["presences"]): Awaitable<Presence>;
   /**
    * Lists the cached presences of a guild.
    *
@@ -7139,7 +7265,7 @@ export declare class ChannelManager extends CachedManager<"channels", AnyChannel
   constructor(client: GatewayClient);
   createStructure(data: CacheEntityTypes["channels"]): AnyChannel;
   keyOf(data: CacheEntityTypes["channels"]): string;
-  hydrate(data: CacheEntityTypes["channels"]): Promise<AnyChannel>;
+  _hydrate(data: CacheEntityTypes["channels"]): Awaitable<AnyChannel>;
   resolveKey(channelId: string): string;
   /**
    * Adds a channel to the cache, handing threads to `client.threads`, whose cache holds them.
@@ -7148,11 +7274,12 @@ export declare class ChannelManager extends CachedManager<"channels", AnyChannel
    */
   _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.
+   * Gets a channel from the cache, looking it up in the thread cache as well, which `get` and `cached` rely on.
    *
    * @param channelId The ID of the channel.
+   * @internal
    */
-  get(channelId: string): Promise<AnyChannel | undefined>;
+  _get(channelId: string): Awaitable<AnyChannel | undefined>;
   /**
    * Writes a channel to the cache, threads to the thread cache.
    *
@@ -7369,6 +7496,11 @@ interface GatewayEventMap {
   guildMemberAdd: [member: GuildMember];
   guildMemberUpdate: [oldMember: GuildMember | null, newMember: GuildMember];
   guildMemberRemove: [member: GuildMember | null, data: GatewayGuildMemberRemoveDispatchData];
+  /**
+   * Emitted for each chunk of members Discord sends in answer to `client.members.request`, once it is cached.
+   * `data` has the chunk's index and count, its nonce, and the requested IDs that are not members (`not_found`).
+   */
+  guildMembersChunk: [members: GuildMember[], guild: Guild | null, data: GatewayGuildMembersChunkDispatchData];
   guildRoleCreate: [role: Role];
   guildRoleUpdate: [oldRole: Role | null, newRole: Role];
   guildRoleDelete: [role: Role | null, data: GatewayGuildRoleDeleteDispatchData];
@@ -7561,6 +7693,22 @@ type RawAPIType<Value extends Structure<object>> = Value extends Structure<infer
  * A function building a {@link Structure} out of its raw API data.
  */
 type StructureCreator<Value extends Structure<object>, Raw extends RawAPIType<Value> = RawAPIType<Value>> = (data: 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>;
 //#endregion
 //#region src/util/container.d.ts
 /**
@@ -7646,6 +7794,45 @@ export declare class DispatchTimeoutError extends Error {
   readonly timeout: number;
   constructor(type: string, shardId: number, partition: string | null, timeout: number);
 }
+/**
+ * Thrown by `GuildMemberManager#request` when Discord stops sending the chunks of the requested members.
+ *
+ * @remarks
+ * The request is dropped: chunks arriving later still update the cache and emit `guildMembersChunk`.
+ */
+export declare class GuildMembersTimeoutError extends Error {
+  /**
+   * The ID of the guild whose members were requested.
+   */
+  readonly guildId: string;
+  /**
+   * The nonce of the request.
+   */
+  readonly nonce: string;
+  /**
+   * The timeout that was exceeded, in milliseconds.
+   */
+  readonly timeout: number;
+  constructor(guildId: string, nonce: string, timeout: number);
+}
+/**
+ * Thrown by `GuildMemberManager#request` when Discord answers with `RATE_LIMITED` instead of the members' chunks.
+ */
+export declare class GuildMembersRateLimitError extends Error {
+  /**
+   * The ID of the guild whose members were requested.
+   */
+  readonly guildId: string;
+  /**
+   * The nonce of the request.
+   */
+  readonly nonce: string;
+  /**
+   * How long to wait before requesting the members again, in milliseconds.
+   */
+  readonly retryAfter: number;
+  constructor(guildId: string, nonce: string, retryAfter: number);
+}
 //#endregion
 //#region src/util/permissions.d.ts
 /**
@@ -7717,5 +7904,5 @@ export declare function computeTargetPermissions(guildId: Snowflake, overwrites:
  */
 export declare function computePermissionsIn(channel: AnyChannel | Snowflake, target: GuildMember | Role | Snowflake): Promise<PermissionsBitField>;
 //#endregion
-export type { GatewayEventMap, GatewayEventName, MessageReactionEventDetails, RawAPIType, StructureCreator };
+export type { GatewayEventMap, GatewayEventName, MessageReactionEventDetails, RawAPIType, StructureCreator, isPromiseLike, whenAll };
 //# sourceMappingURL=index.d.ts.map