@wolfstar/plugin-gateway 0.14.0-next-20261009112235 → 0.14.0

package/dist/esm/index.js

@@ -8950,7 +8950,10 @@ function highestFirst(roles) {
 * (`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.
+* They only know the roles the cache holds, and skip the ones it lacks without an error. With a filtered cache or a
+* `plugin-broker` worker that makes `highest` answer a lower role than the member's real one. Call
+* {@link GuildMemberRoleManager.fetch} first, or {@link GuildMemberRoleManager.fetchHighest}, where a hierarchy check
+* must not under-report. The other `fetch*` methods fall back to the API when a role is not cached.
 */
 var GuildMemberRoleManager = class GuildMemberRoleManager extends BaseManager {
 	/**
@@ -8996,14 +8999,19 @@ var GuildMemberRoleManager = class GuildMemberRoleManager extends BaseManager {
 		return this.member.roleIds;
 	}
 	/**
-	* 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.
+	* The member's roles held in the cache, by ID, `@everyone` included. Roles that are not cached are skipped, without
+	* an error: use {@link GuildMemberRoleManager.fetch} to get them all.
 	*/
 	get cache() {
 		return cachedRoles(this.client, this.guildId, [...this.ids, this.guildId]);
 	}
 	/**
 	* The member's highest cached role. `null` when none of their roles is cached, `@everyone` included.
+	*
+	* @remarks
+	* Roles missing from the cache are skipped, not an error: the answer is the highest role the cache holds, so a
+	* hierarchy check can compare a higher-ranked member as a lower one. Use {@link GuildMemberRoleManager.fetchHighest}
+	* for an answer that is right on a cache miss, or `await member.roles.fetch()` before reading this.
 	*/
 	get highest() {
 		return this.fromCache(pick.highest);
@@ -9053,9 +9061,10 @@ var GuildMemberRoleManager = class GuildMemberRoleManager extends BaseManager {
 	/**
 	* Fetches the member's highest role, `@everyone` when they have no other.
 	*
-	* @deprecated Use {@link GuildMemberRoleManager.highest}. When some of the member's roles may be missing from the
-	* cache (a filtered cache, a `plugin-broker` worker), call {@link GuildMemberRoleManager.fetch} first, then read the
-	* getter.
+	* @remarks
+	* The call for a role-hierarchy check that must be right on a cache miss: unlike
+	* {@link GuildMemberRoleManager.highest}, it asks the API for the roles the cache lacks, so it never answers a lower
+	* role than the member's real one. With a complete cache it makes no request.
 	*/
 	async fetchHighest() {
 		return pick.highest(await this.fetch());
@@ -9372,6 +9381,11 @@ var GuildMember = class GuildMember extends Structure {
 	* The member's guild-wide permissions, before channel overwrites, like discord.js's `GuildMember#permissions`:
 	* computed from the cached guild and roles, skipping the roles that are not cached.
 	*
+	* @remarks
+	* A role missing from the cache is skipped, not an error, so the answer can hold fewer permissions than the member
+	* has. Use {@link GuildMember.fetchPermissions} for an answer that is right on a cache miss, or
+	* `await member.roles.fetch()` before reading this.
+	*
 	* @throws A `GatewayError`: `GuildUncached` when the guild is not cached.
 	*/
 	get permissions() {
@@ -9387,9 +9401,9 @@ var GuildMember = class GuildMember extends Structure {
 	* Fetches the member's guild-wide permissions, before channel overwrites: {@link GuildMember.permissions} with the
 	* guild and the roles fetched from the API when they are not cached, whatever the cache.
 	*
-	* @deprecated Use {@link GuildMember.permissions}. When the guild or some roles may be missing from the cache (a
-	* filtered cache, a `plugin-broker` worker), fetch them first (`client.guilds.fetch(guildId)`,
-	* `member.roles.fetch()`), then read the getter.
+	* @remarks
+	* The call for a permission check that must be right on a cache miss: the getter skips the roles the cache lacks
+	* and can answer fewer permissions than the member has.
 	*/
 	async fetchPermissions() {
 		const guild = await this.client.guilds.fetch(this.guildId);
@@ -9406,10 +9420,11 @@ var GuildMember = class GuildMember extends Structure {
 	* Fetches the member's permissions in a channel: their guild permissions with the channel's overwrites applied.
 	* discord.js: `member.permissionsIn(channel)`.
 	*
-	* @param channel The channel, or its ID. Threads use their parent's overwrites.
+	* @remarks
+	* Like {@link GuildMember.fetchPermissions}, the call for a check that must be right on a cache miss: it also
+	* fetches the channel and the roles when they are not cached.
 	*
-	* @deprecated Use {@link GuildMember.permissionsIn}. See {@link GuildMember.fetchPermissions} for the cache-miss
-	* fallback; fetch the channel too (`client.channels.fetch(channelId)`).
+	* @param channel The channel, or its ID. Threads use their parent's overwrites.
 	*/
 	fetchPermissionsIn(channel) {
 		return computePermissionsIn(channel, this);
@@ -9419,6 +9434,10 @@ var GuildMember = class GuildMember extends Structure {
 	* with the channel's overwrites applied, read from the cache.
 	*
 	* @param channel The channel, or the ID of a cached one. Threads use their parent's overwrites.
+	* @remarks
+	* A role missing from the cache is skipped, as in {@link GuildMember.permissions}: use
+	* {@link GuildMember.fetchPermissionsIn} for an answer that is right on a cache miss.
+	*
 	* @throws A `GatewayError`: `ChannelUncached` or `GuildUncached` when they are not cached.
 	*/
 	permissionsIn(channel) {
@@ -9499,6 +9518,11 @@ var GuildMember = class GuildMember extends Structure {
 	* Whether the bot ranks above the member, like discord.js's `GuildMember#manageable`: it is not the guild owner, not
 	* the bot itself, and the bot's highest role is higher than theirs (or the bot owns the guild).
 	*
+	* @remarks
+	* It reads {@link GuildMemberRoleManager.highest}, which skips the roles missing from the cache: a higher role that
+	* is not cached makes the member look lower. Call `await member.roles.fetch()` and `await me.roles.fetch()` before
+	* reading this, or compare {@link GuildMemberRoleManager.fetchHighest} of both.
+	*
 	* @throws A `GatewayError`: `GuildUncached` or `GuildUncachedMe` when the guild or the bot's member is
 	* not cached.
 	*/
@@ -9529,21 +9553,22 @@ var GuildMember = class GuildMember extends Structure {
 	}
 	/**
 	* Whether the bot can kick the member, like discord.js's `GuildMember#kickable`: it outranks them and has
-	* `KickMembers`. It throws like {@link GuildMember.manageable}.
+	* `KickMembers`. It throws, and skips uncached roles, like {@link GuildMember.manageable}.
 	*/
 	get kickable() {
 		return cacheRead(this.managedWithCached("KickMembers"));
 	}
 	/**
 	* Whether the bot can ban the member, like discord.js's `GuildMember#bannable`: it outranks them and has
-	* `BanMembers`. It throws like {@link GuildMember.manageable}.
+	* `BanMembers`. It throws, and skips uncached roles, like {@link GuildMember.manageable}.
 	*/
 	get bannable() {
 		return cacheRead(this.managedWithCached("BanMembers"));
 	}
 	/**
 	* Whether the bot can time the member out, like discord.js's `GuildMember#moderatable`: it outranks them, has
-	* `ModerateMembers`, and they are no administrator. It throws like {@link GuildMember.manageable}.
+	* `ModerateMembers`, and they are no administrator. It throws, and skips uncached roles, like
+	* {@link GuildMember.manageable}.
 	*/
 	get moderatable() {
 		return cacheRead(whenAll([this.managedWithCached("ModerateMembers")], ([managed]) => managed ? whenAll([this.permissions], ([permissions]) => !permissions.has("Administrator")) : false));