refactor!: return void on bans/kick/addRole/removeRole methods (#10714)

BREAKING CHANGE: The following methods don't return anything: `GuildMember#ban`, `GuildMember#kick`, `GuildMemberManager#ban`, `GuildMemberManager#unban`, `GuildMemberManager#kick`, `GuildMemberManager#addRole`, `GuildMemberManager#removeRole`, `GuildBanManager#create`, and `GuildBanManager#remove`.

packages/discord.js/src/managers/GuildBanManager.js

@@ -6,7 +6,6 @@ const { Routes } = require('discord-api-types/v10');
 const { CachedManager } = require('./CachedManager.js');
 const { DiscordjsTypeError, DiscordjsError, ErrorCodes } = require('../errors/index.js');
 const { GuildBan } = require('../structures/GuildBan.js');
-const { GuildMember } = require('../structures/GuildMember.js');
 
 /**
  * Manages API methods for guild bans and stores their cache.
@@ -136,15 +135,11 @@ class GuildBanManager extends CachedManager {
   /**
    * Bans a user from the guild.
    * @param {UserResolvable} user The user to ban
-   * @param {BanOptions} [options] Options for the ban
+   * @param {BanOptions} [options={}] Options for the ban
-   * @returns {Promise<GuildMember|User|Snowflake>} Result object will be resolved as specifically as possible.
+   * @returns {Promise<void>}
-   * If the GuildMember cannot be resolved, the User will instead be attempted to be resolved. If that also cannot
-   * be resolved, the user id will be the result.
    * @example
    * // Ban a user by id (or with a user/guild member object)
-   * guild.bans.create('84484653687267328')
+   * await guild.bans.create('84484653687267328');
-   *   .then(banInfo => console.log(`Banned ${banInfo.user?.tag ?? banInfo.tag ?? banInfo}`))
-   *   .catch(console.error);
    */
   async create(user, options = {}) {
     if (typeof options !== 'object') throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'options', 'object', true);
@@ -157,30 +152,21 @@ class GuildBanManager extends CachedManager {
       },
       reason: options.reason,
     });
-    if (user instanceof GuildMember) return user;
-    const _user = this.client.users.cache.get(id);
-    if (_user) {
-      return this.guild.members.resolve(_user) ?? _user;
-    }
-    return id;
   }
 
   /**
    * Unbans a user from the guild.
    * @param {UserResolvable} user The user to unban
    * @param {string} [reason] Reason for unbanning user
-   * @returns {Promise<?User>}
+   * @returns {Promise<void>}
    * @example
    * // Unban a user by id (or with a user/guild member object)
-   * guild.bans.remove('84484653687267328')
+   * await guild.bans.remove('84484653687267328');
-   *   .then(user => console.log(`Unbanned ${user.username} from ${guild.name}`))
-   *   .catch(console.error);
    */
   async remove(user, reason) {
     const id = this.client.users.resolveId(user);
     if (!id) throw new DiscordjsError(ErrorCodes.BanResolveId);
     await this.client.rest.delete(Routes.guildBan(this.guild.id, id), { reason });
-    return this.client.users.resolve(user);
   }
 
   /**

packages/discord.js/src/managers/GuildMemberManager.js

@@ -445,60 +445,49 @@ class GuildMemberManager extends CachedManager {
     return pruned;
   }
 
+  /* eslint-disable consistent-return */
   /**
    * Kicks a user from the guild.
    * <info>The user must be a member of the guild</info>
    * @param {UserResolvable} user The member to kick
    * @param {string} [reason] Reason for kicking
-   * @returns {Promise<GuildMember|User|Snowflake>} Result object will be resolved as specifically as possible.
+   * @returns {Promise<void>}
-   * If the GuildMember cannot be resolved, the User will instead be attempted to be resolved. If that also cannot
-   * be resolved, the user's id will be the result.
    * @example
    * // Kick a user by id (or with a user/guild member object)
-   * guild.members.kick('84484653687267328')
+   * await guild.members.kick('84484653687267328');
-   *   .then(kickInfo => console.log(`Kicked ${kickInfo.user?.tag ?? kickInfo.tag ?? kickInfo}`))
-   *   .catch(console.error);
    */
   async kick(user, reason) {
     const id = this.client.users.resolveId(user);
     if (!id) throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'user', 'UserResolvable');
 
     await this.client.rest.delete(Routes.guildMember(this.guild.id, id), { reason });
-
-    return this.resolve(user) ?? this.client.users.resolve(user) ?? id;
   }
+  /* eslint-enable consistent-return */
 
   /**
-   * Bans a user from the guild.
+   * Bans a user from the guild. Internally calls the {@link GuildBanManager#create} method.
    * @param {UserResolvable} user The user to ban
    * @param {BanOptions} [options] Options for the ban
-   * @returns {Promise<GuildMember|User|Snowflake>} Result object will be resolved as specifically as possible.
+   * @returns {Promise<void>}
-   * If the GuildMember cannot be resolved, the User will instead be attempted to be resolved. If that also cannot
-   * be resolved, the user id will be the result.
-   * Internally calls the GuildBanManager#create method.
    * @example
    * // Ban a user by id (or with a user/guild member object)
-   * guild.members.ban('84484653687267328')
+   * await guild.members.ban('84484653687267328');
-   *   .then(banInfo => console.log(`Banned ${banInfo.user?.tag ?? banInfo.tag ?? banInfo}`))
-   *   .catch(console.error);
    */
-  ban(user, options) {
+  async ban(user, options) {
-    return this.guild.bans.create(user, options);
+    await this.guild.bans.create(user, options);
   }
 
   /**
    * Unbans a user from the guild. Internally calls the {@link GuildBanManager#remove} method.
    * @param {UserResolvable} user The user to unban
    * @param {string} [reason] Reason for unbanning user
-   * @returns {Promise<?User>} The user that was unbanned
+   * @returns {Promise<void>}
    * @example
    * // Unban a user by id (or with a user/guild member object)
-   * guild.members.unban('84484653687267328')
+   * await guild.members.unban('84484653687267328');
-   *   .then(user => console.log(`Unbanned ${user.username} from ${guild.name}`))
-   *   .catch(console.error);
    */
-  unban(user, reason) {
+  async unban(user, reason) {
-    return this.guild.bans.remove(user, reason);
+    await this.guild.bans.remove(user, reason);
   }
 
   /**
@@ -531,29 +520,25 @@ class GuildMemberManager extends CachedManager {
   /**
    * Adds a role to a member.
    * @param {AddOrRemoveGuildMemberRoleOptions} options Options for adding the role
-   * @returns {Promise<GuildMember|User|Snowflake>}
+   * @returns {Promise<void>}
    */
   async addRole(options) {
     const { user, role, reason } = options;
     const userId = this.resolveId(user);
     const roleId = this.guild.roles.resolveId(role);
     await this.client.rest.put(Routes.guildMemberRole(this.guild.id, userId, roleId), { reason });
-
-    return this.resolve(user) ?? this.client.users.resolve(user) ?? userId;
   }
 
   /**
    * Removes a role from a member.
    * @param {AddOrRemoveGuildMemberRoleOptions} options Options for removing the role
-   * @returns {Promise<GuildMember|User|Snowflake>}
+   * @returns {Promise<void>}
    */
   async removeRole(options) {
     const { user, role, reason } = options;
     const userId = this.resolveId(user);
     const roleId = this.guild.roles.resolveId(role);
     await this.client.rest.delete(Routes.guildMemberRole(this.guild.id, userId, roleId), { reason });
-
-    return this.resolve(user) ?? this.client.users.resolve(user) ?? userId;
   }
 }
 

packages/discord.js/src/structures/GuildMember.js

@@ -412,24 +412,22 @@ class GuildMember extends Base {
   /**
    * Kicks this member from the guild.
    * @param {string} [reason] Reason for kicking user
-   * @returns {Promise<GuildMember>}
+   * @returns {Promise<void>}
    */
-  kick(reason) {
+  async kick(reason) {
-    return this.guild.members.kick(this, reason);
+    await this.guild.members.kick(this, reason);
   }
 
   /**
    * Bans this guild member.
    * @param {BanOptions} [options] Options for the ban
-   * @returns {Promise<GuildMember>}
+   * @returns {Promise<void>}
    * @example
    * // Ban a guild member, deleting a week's worth of messages
-   * guildMember.ban({ deleteMessageSeconds: 60 * 60 * 24 * 7, reason: 'They deserved it' })
+   * await guildMember.ban({ deleteMessageSeconds: 60 * 60 * 24 * 7, reason: 'They deserved it' });
-   *   .then(console.log)
-   *   .catch(console.error);
    */
-  ban(options) {
+  async ban(options) {
-    return this.guild.bans.create(this, options);
+    await this.guild.bans.create(this, options);
   }
 
   /**

packages/discord.js/test/random.js

@@ -139,12 +139,13 @@ client.on(Events.MessageCreate, message => {
     }
 
     if (message.content.startsWith('kick')) {
+      const user = message.mentions.users.first();
       message.guild.members
-        .resolve(message.mentions.users.first())
+        .resolve(user)
         .kick()
-        .then(member => {
+        .then(() => {
-          console.log(member);
+          console.log(user.id);
-          message.channel.send(`Kicked!${member.user.username}`);
+          message.channel.send(`Kicked ${user.username}!`);
         })
         .catch(console.error);
     }

packages/discord.js/typings/index.d.ts

@@ -1631,7 +1631,7 @@ export class GuildMember extends Base {
   public get voice(): VoiceState;
   public avatarURL(options?: ImageURLOptions): string | null;
   public bannerURL(options?: ImageURLOptions): string | null;
-  public ban(options?: BanOptions): Promise<GuildMember>;
+  public ban(options?: BanOptions): Promise<void>;
   public disableCommunicationUntil(timeout: DateResolvable | null, reason?: string): Promise<GuildMember>;
   public timeout(timeout: number | null, reason?: string): Promise<GuildMember>;
   public fetch(force?: boolean): Promise<GuildMember>;
@@ -1644,7 +1644,7 @@ export class GuildMember extends Base {
     communicationDisabledUntilTimestamp: number;
     readonly communicationDisabledUntil: Date;
   };
-  public kick(reason?: string): Promise<GuildMember>;
+  public kick(reason?: string): Promise<void>;
   public permissionsIn(channel: GuildChannelResolvable): Readonly<PermissionsBitField>;
   public setFlags(flags: GuildMemberFlagsResolvable, reason?: string): Promise<GuildMember>;
   public setNickname(nickname: string | null, reason?: string): Promise<GuildMember>;
@@ -4191,7 +4191,7 @@ export class GuildMemberManager extends CachedManager<Snowflake, GuildMember, Gu
     options: AddGuildMemberOptions & { fetchWhenExisting: false },
   ): Promise<GuildMember | null>;
   public add(user: UserResolvable, options: AddGuildMemberOptions): Promise<GuildMember>;
-  public ban(user: UserResolvable, options?: BanOptions): Promise<GuildMember | User | Snowflake>;
+  public ban(user: UserResolvable, options?: BanOptions): Promise<void>;
   public bulkBan(
     users: ReadonlyCollection<Snowflake, UserResolvable> | readonly UserResolvable[],
     options?: BanOptions,
@@ -4202,23 +4202,23 @@ export class GuildMemberManager extends CachedManager<Snowflake, GuildMember, Gu
   ): Promise<GuildMember>;
   public fetch(options?: FetchMembersOptions): Promise<Collection<Snowflake, GuildMember>>;
   public fetchMe(options?: BaseFetchOptions): Promise<GuildMember>;
-  public kick(user: UserResolvable, reason?: string): Promise<GuildMember | User | Snowflake>;
+  public kick(user: UserResolvable, reason?: string): Promise<void>;
   public list(options?: GuildListMembersOptions): Promise<Collection<Snowflake, GuildMember>>;
   public prune(options: GuildPruneMembersOptions & { dry?: false; count: false }): Promise<null>;
   public prune(options?: GuildPruneMembersOptions): Promise<number>;
   public search(options: GuildSearchMembersOptions): Promise<Collection<Snowflake, GuildMember>>;
-  public unban(user: UserResolvable, reason?: string): Promise<User | null>;
+  public unban(user: UserResolvable, reason?: string): Promise<void>;
-  public addRole(options: AddOrRemoveGuildMemberRoleOptions): Promise<GuildMember | User | Snowflake>;
+  public addRole(options: AddOrRemoveGuildMemberRoleOptions): Promise<void>;
-  public removeRole(options: AddOrRemoveGuildMemberRoleOptions): Promise<GuildMember | User | Snowflake>;
+  public removeRole(options: AddOrRemoveGuildMemberRoleOptions): Promise<void>;
 }
 
 export class GuildBanManager extends CachedManager<Snowflake, GuildBan, GuildBanResolvable> {
   private constructor(guild: Guild, iterable?: Iterable<RawGuildBanData>);
   public guild: Guild;
-  public create(user: UserResolvable, options?: BanOptions): Promise<GuildMember | User | Snowflake>;
+  public create(user: UserResolvable, options?: BanOptions): Promise<void>;
   public fetch(options: UserResolvable | FetchBanOptions): Promise<GuildBan>;
   public fetch(options?: FetchBansOptions): Promise<Collection<Snowflake, GuildBan>>;
-  public remove(user: UserResolvable, reason?: string): Promise<User | null>;
+  public remove(user: UserResolvable, reason?: string): Promise<void>;
   public bulkCreate(
     users: ReadonlyCollection<Snowflake, UserResolvable> | readonly UserResolvable[],
     options?: BanOptions,