refactor: Deprecate reason parameter on adding and removing thread members (#10551)

* refactor: deprecate `reason` on thread member add and remove

* chore: address TSLint errors

* refactor: use function

packages/discord.js/src/managers/ThreadMemberManager.js

@@ -1,11 +1,15 @@
 'use strict';
 
+const process = require('node:process');
 const { Collection } = require('@discordjs/collection');
 const { makeURLSearchParams } = require('@discordjs/rest');
 const { Routes } = require('discord-api-types/v10');
 const CachedManager = require('./CachedManager');
 const { DiscordjsTypeError, ErrorCodes } = require('../errors');
 const ThreadMember = require('../structures/ThreadMember');
+const { emitDeprecationWarningForRemoveThreadMember } = require('../util/Util');
+
+let deprecationEmittedForAdd = false;
 
 /**
  * Manages API methods for GuildMembers and stores their cache.
@@ -92,9 +96,20 @@ class ThreadMemberManager extends CachedManager {
    * Adds a member to the thread.
    * @param {UserResolvable|'@me'} member The member to add
    * @param {string} [reason] The reason for adding this member
+   * <warn>This parameter is **deprecated**. Reasons cannot be used.</warn>
    * @returns {Promise<Snowflake>}
    */
   async add(member, reason) {
+    if (reason !== undefined && !deprecationEmittedForAdd) {
+      process.emitWarning(
+        // eslint-disable-next-line max-len
+        'The reason parameter of ThreadMemberManager#add() is deprecated as Discord does not parse them. It will be removed in the next major version.',
+        'DeprecationWarning',
+      );
+
+      deprecationEmittedForAdd = true;
+    }
+
     const id = member === '@me' ? member : this.client.users.resolveId(member);
     if (!id) throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'member', 'UserResolvable');
     await this.client.rest.put(Routes.threadMembers(this.thread.id, id), { reason });
@@ -105,9 +120,14 @@ class ThreadMemberManager extends CachedManager {
    * Remove a user from the thread.
    * @param {UserResolvable|'@me'} member The member to remove
    * @param {string} [reason] The reason for removing this member from the thread
+   * <warn>This parameter is **deprecated**. Reasons cannot be used.</warn>
    * @returns {Promise<Snowflake>}
    */
   async remove(member, reason) {
+    if (reason !== undefined) {
+      emitDeprecationWarningForRemoveThreadMember(this.constructor.name);
+    }
+
     const id = member === '@me' ? member : this.client.users.resolveId(member);
     if (!id) throw new DiscordjsTypeError(ErrorCodes.InvalidType, 'member', 'UserResolvable');
     await this.client.rest.delete(Routes.threadMembers(this.thread.id, id), { reason });

packages/discord.js/src/structures/ThreadMember.js

@@ -2,6 +2,7 @@
 
 const Base = require('./Base');
 const ThreadMemberFlagsBitField = require('../util/ThreadMemberFlagsBitField');
+const { emitDeprecationWarningForRemoveThreadMember } = require('../util/Util');
 
 /**
  * Represents a Member for a Thread.
@@ -102,9 +103,14 @@ class ThreadMember extends Base {
   /**
    * Removes this member from the thread.
    * @param {string} [reason] Reason for removing the member
+   * <warn>This parameter is **deprecated**. Reasons cannot be used.</warn>
    * @returns {Promise<ThreadMember>}
    */
   async remove(reason) {
+    if (reason !== undefined) {
+      emitDeprecationWarningForRemoveThreadMember(this.constructor.name);
+    }
+
     await this.thread.members.remove(this.id, reason);
     return this;
   }

packages/discord.js/src/util/Util.js

@@ -10,6 +10,7 @@ const { DiscordjsError, DiscordjsRangeError, DiscordjsTypeError, ErrorCodes } =
 const isObject = d => typeof d === 'object' && d !== null;
 
 let deprecationEmittedForUserFetchFlags = false;
+let deprecationEmittedForRemoveThreadMember = false;
 
 /**
  * Flatten an object. Any properties that are collections will get converted to an array of keys.
@@ -513,6 +514,21 @@ function emitDeprecationWarningForUserFetchFlags(name) {
   deprecationEmittedForUserFetchFlags = true;
 }
 
+/**
+ * Deprecation function for the reason parameter of removing thread members.
+ * @param {string} name Name of the class
+ * @private
+ */
+function emitDeprecationWarningForRemoveThreadMember(name) {
+  if (deprecationEmittedForRemoveThreadMember) return;
+
+  process.emitWarning(
+    `The reason parameter of ${name}#remove() is deprecated as Discord does not parse them. It will be removed in the next major version.`,
+  );
+
+  deprecationEmittedForRemoveThreadMember = true;
+}
+
 module.exports = {
   flatten,
   fetchRecommendedShardCount,
@@ -533,6 +549,7 @@ module.exports = {
   transformResolved,
   resolveSKUId,
   emitDeprecationWarningForUserFetchFlags,
+  emitDeprecationWarningForRemoveThreadMember,
 };
 
 // Fixes Circular

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

@@ -3397,7 +3397,11 @@ export class ThreadMember<HasMemberData extends boolean = boolean> extends Base
   public thread: AnyThreadChannel;
   public get user(): User | null;
   public get partial(): false;
+  /* tslint:disable:unified-signatures */
+  public remove(): Promise<ThreadMember>;
+  /** @deprecated The `reason` parameter is deprecated as Discord does not parse them. */
   public remove(reason?: string): Promise<ThreadMember>;
+  /* tslint:enable:unified-signatures */
 }
 
 export type ThreadMemberFlagsString = keyof typeof ThreadMemberFlags;
@@ -4671,7 +4675,12 @@ export class ThreadMemberManager extends CachedManager<Snowflake, ThreadMember,
   private constructor(thread: ThreadChannel, iterable?: Iterable<RawThreadMemberData>);
   public thread: AnyThreadChannel;
   public get me(): ThreadMember | null;
+
+  /* tslint:disable:unified-signatures */
+  public add(member: UserResolvable | '@me'): Promise<Snowflake>;
+  /** @deprecated The `reason` parameter is deprecated as Discord does not parse them. */
   public add(member: UserResolvable | '@me', reason?: string): Promise<Snowflake>;
+  /* tslint:enable:unified-signatures */
 
   public fetch(
     options: ThreadMember<true> | ((FetchThreadMemberOptions & { withMember: true }) | { member: ThreadMember<true> }),
@@ -4685,7 +4694,12 @@ export class ThreadMemberManager extends CachedManager<Snowflake, ThreadMember,
 
   public fetch(options?: FetchThreadMembersWithoutGuildMemberDataOptions): Promise<Collection<Snowflake, ThreadMember>>;
   public fetchMe(options?: BaseFetchOptions): Promise<ThreadMember>;
+
+  /* tslint:disable:unified-signatures */
+  public remove(member: UserResolvable | '@me'): Promise<Snowflake>;
+  /** @deprecated The `reason` parameter is deprecated as Discord does not parse them. */
   public remove(member: UserResolvable | '@me', reason?: string): Promise<Snowflake>;
+  /* tslint:enable:unified-signatures */
 }
 
 export class UserManager extends CachedManager<Snowflake, User, UserResolvable> {

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

@@ -214,7 +214,14 @@ import {
   PollData,
   UserManager,
 } from '.';
-import { expectAssignable, expectDeprecated, expectNotAssignable, expectNotType, expectType } from 'tsd';
+import {
+  expectAssignable,
+  expectDeprecated,
+  expectNotAssignable,
+  expectNotDeprecated,
+  expectNotType,
+  expectType,
+} from 'tsd';
 import type { ContextMenuCommandBuilder, SlashCommandBuilder } from '@discordjs/builders';
 import { ReadonlyCollection } from '@discordjs/collection';
 
@@ -1752,6 +1759,13 @@ declare const threadMemberManager: ThreadMemberManager;
   threadMemberManager.fetch({ cache: true, force: false });
   // @ts-expect-error `withMember` needs to be `true` to receive paginated results.
   threadMemberManager.fetch({ withMember: false, limit: 5, after: '12345678901234567' });
+
+  expectNotDeprecated(threadMemberManager.add('1234678'));
+  expectDeprecated(threadMemberManager.add('1234678', 'reason'));
+  expectNotDeprecated(threadMemberManager.remove('1234678'));
+  expectDeprecated(threadMemberManager.remove('1234678', 'reason'));
+  expectNotDeprecated(threadMemberWithGuildMember.remove());
+  expectDeprecated(threadMemberWithGuildMember.remove('reason'));
 }
 
 declare const userManager: UserManager;