feat(GuildChannel): add support for clone options, deprecate old signature (#3792)

src/structures/GuildChannel.js

@@ -5,6 +5,7 @@ const Permissions = require('../util/Permissions');
 const Collection = require('../util/Collection');
 const Constants = require('../util/Constants');
 const Invite = require('./Invite');
+const Util = require('../util/Util');
 
 /**
  * Represents a guild channel (i.e. text channels and voice channels).
@@ -403,26 +404,72 @@ class GuildChannel extends Channel {
     return this.client.rest.methods.createChannelInvite(this, options, reason);
   }
 
+  /* eslint-disable max-len */
+  /**
+   * Options to clone a guild channel.
+   * @typedef {Object} GuildChannelCloneOptions
+   * @property {string} [name=this.name] Name of the new channel
+   * @property {ChannelCreationOverwrites[]|Collection<Snowflake, PermissionOverwrites>} [permissionOverwrites=this.permissionOverwrites]
+   * Permission overwrites of the new channel
+   * @property {string} [type=this.type] Type of the new channel
+   * @property {string} [topic=this.topic] Topic of the new channel (only text)
+   * @property {boolean} [nsfw=this.nsfw] Whether the new channel is nsfw (only text)
+   * @property {number} [bitrate=this.bitrate] Bitrate of the new channel in bits (only voice)
+   * @property {number} [userLimit=this.userLimit] Maximum amount of users allowed in the new channel (only voice)
+   * @property {number} [rateLimitPerUser=ThisType.rateLimitPerUser] Ratelimit per user for the new channel (only text)
+   * @property {ChannelResolvable} [parent=this.parent] Parent of the new channel
+   * @property {string} [reason] Reason for cloning this channel
+   */
+  /* eslint-enable max-len */
+
   /**
    * Clone this channel.
-   * @param {string} [name=this.name] Optional name for the new channel, otherwise it has the name of this channel
+   * @param {string|GuildChannelCloneOptions} [nameOrOptions={}] Name for the new channel.
+   * **(deprecated, use options)**
+   * Alternatively options for cloning the channel
    * @param {boolean} [withPermissions=true] Whether to clone the channel with this channel's permission overwrites
+   * **(deprecated, use options)**
    * @param {boolean} [withTopic=true] Whether to clone the channel with this channel's topic
-   * @param {string} [reason] Reason for cloning this channel
+   * **(deprecated, use options)**
+   * @param {string} [reason] Reason for cloning this channel **(deprecated, user options)**
    * @returns {Promise<GuildChannel>}
    * @example
    * // Clone a channel
-   * channel.clone(undefined, true, false, 'Needed a clone')
+   * channel.clone({ topic: null, reason: 'Needed a clone' })
    *   .then(clone => console.log(`Cloned ${channel.name} to make a channel called ${clone.name}`))
    *   .catch(console.error);
    */
-  clone(name = this.name, withPermissions = true, withTopic = true, reason) {
+  clone(nameOrOptions = {}, withPermissions = true, withTopic = true, reason) {
-    return this.guild.createChannel(name, {
+    // If more than one parameter was specified or the first is a string,
+    // convert them to a compatible options object and issue a warning
+    if (arguments.length > 1 || typeof nameOrOptions === 'string') {
+      process.emitWarning(
+        'GuildChannel#clone: Clone channels using an options object instead of separate parameters.',
+        'Deprecation Warning'
+      );
+
+      nameOrOptions = {
+        name: nameOrOptions,
+        permissionOverwrites: withPermissions ? this.permissionOverwrites : null,
+        topic: withTopic ? this.topic : null,
+        reason: reason || null,
+      };
+    }
+
+    Util.mergeDefault({
+      name: this.name,
+      permissionOverwrites: this.permissionOverwrites,
+      topic: this.topic,
       type: this.type,
-      permissionOverwrites: withPermissions ? this.permissionOverwrites : undefined,
+      nsfw: this.nsfw,
-      topic: withTopic ? this.topic : undefined,
+      parent: this.parent,
-      reason,
+      bitrate: this.bitrate,
-    });
+      userLimit: this.userLimit,
+      rateLimitPerUser: this.rateLimitPerUser,
+      reason: null,
+    }, nameOrOptions);
+
+    return this.guild.createChannel(nameOrOptions.name, nameOrOptions);
   }
 
   /**

typings/index.d.ts

@@ -71,7 +71,7 @@ declare module 'discord.js' {
 		public readonly createdTimestamp: number;
 		public deleted: boolean;
 		public id: Snowflake;
-		public type: 'dm' | 'group' | 'text' | 'voice' | 'category' | 'news' | 'store';
+		public type: 'dm' | 'group' | GuildChannelType;
 		public delete(): Promise<Channel>;
 	}
 
@@ -569,7 +569,7 @@ declare module 'discord.js' {
 		public allowDMs(allow: boolean): Promise<Guild>;
 		public ban(user: UserResolvable, options?: BanOptions | number | string): Promise<GuildMember | User | string>;
 		public createChannel(name: string, options?: ChannelData): Promise<CategoryChannel | TextChannel | VoiceChannel>;
-		public createChannel(name: string, type?: 'category' | 'text' | 'voice' | 'news' | 'store', permissionOverwrites?: PermissionOverwrites[] | ChannelCreationOverwrites[], reason?: string): Promise<CategoryChannel | TextChannel | VoiceChannel>;
+		public createChannel(name: string, type?: GuildChannelType, permissionOverwrites?: PermissionOverwrites[] | ChannelCreationOverwrites[], reason?: string): Promise<CategoryChannel | TextChannel | VoiceChannel>;
 		public createEmoji(attachment: BufferResolvable | Base64Resolvable, name: string, roles?: Collection<Snowflake, Role> | Role[], reason?: string): Promise<Emoji>;
 		public createIntegration(data: IntegrationData, reason?: string): Promise<Guild>;
 		public createRole(data?: RoleData, reason?: string): Promise<Role>;
@@ -662,6 +662,7 @@ declare module 'discord.js' {
 		public permissionOverwrites: Collection<Snowflake, PermissionOverwrites>;
 		public position: number;
 		public readonly permissionsLocked: boolean | null;
+		public clone(options: GuildChannelCloneOptions): Promise<GuildChannel>;
 		public clone(name?: string, withPermissions?: boolean, withTopic?: boolean, reason?: string): Promise<GuildChannel>;
 		public createInvite(options?: InviteOptions, reason?: string): Promise<Invite>;
 		public delete(reason?: string): Promise<GuildChannel>;
@@ -1760,7 +1761,7 @@ declare module 'discord.js' {
 	};
 
 	type ChannelData = {
-		type?: 'category' | 'text' | 'voice' | 'news' | 'store';
+		type?: GuildChannelType;
 		name?: string;
 		position?: number;
 		topic?: string;
@@ -1941,9 +1942,24 @@ declare module 'discord.js' {
 		UNKNOWN?: string;
 	};
 
+	type GuildChannelCloneOptions = {
+		name?: string;
+		permissionOverwrites?: ChannelCreationOverwrites[] | Collection<Snowflake, PermissionOverwrites>;
+		type?: GuildChannelType;
+		topic?: string;
+		nsfw?: boolean;
+		bitrate?: number;
+		userLimit?: number;
+		rateLimitPerUser?: number;
+		parent?: ChannelResolvable;
+		reason?: string;
+	}
+
 	type GuildChannelMessageNotifications = MessageNotifications
 		& 'INHERIT';
 
+	type GuildChannelType = 'category' | 'text' | 'voice' | 'news' | 'store';
+
 	type GuildEditData = {
 		name?: string;
 		region?: string;