chore: add deprecations

Author: Jiralite

packages/discord.js/src/managers/RoleManager.js

@@ -12,6 +12,8 @@ const PermissionsBitField = require('../util/PermissionsBitField');
 const { setPosition, resolveColor } = require('../util/Util');
 
 let cacheWarningEmitted = false;
+let deprecationEmittedForCreate = false;
+let deprecationEmittedForEdit = false;
 
 /**
  * Manages API methods for roles and stores their cache.
@@ -128,6 +130,7 @@ class RoleManager extends CachedManager {
    * @typedef {Object} RoleCreateOptions
    * @property {string} [name] The name of the new role
    * @property {ColorResolvable} [color] The data to create the role with
+   * <warn>This property is deprecated. Use `colors` instead.</warn>
    * @property {RoleColorsResolvable} [colors] The colors to create the role with
    * @property {boolean} [hoist] Whether or not the new role should be hoisted
    * @property {PermissionResolvable} [permissions] The permissions for the new role
@@ -176,23 +179,35 @@ class RoleManager extends CachedManager {
    *   .catch(console.error);
    */
   async create(options = {}) {
-    let { permissions, color, icon } = options;
-    const { name, hoist, position, mentionable, reason, unicodeEmoji } = options;
+    let { permissions, icon } = options;
+    const { name, color, hoist, position, mentionable, reason, unicodeEmoji } = options;
     if (permissions !== undefined) permissions = new PermissionsBitField(permissions);
     if (icon) {
       const guildEmojiURL = this.guild.emojis.resolve(icon)?.imageURL();
       icon = guildEmojiURL ? await resolveImage(guildEmojiURL) : await resolveImage(icon);
       if (typeof icon !== 'string') icon = undefined;
     }
 
-    color &&= resolveColor(color);
-
-    const colors = options.colors && {
+    let colors = options.colors && {
       primary_color: resolveColor(options.colors.primaryColor),
       secondary_color: options.colors.secondaryColor && resolveColor(options.colors.secondaryColor),
       tertiary_color: options.colors.tertiaryColor && resolveColor(options.colors.tertiaryColor),
     };
 
+    if (color !== undefined) {
+      if (!deprecationEmittedForCreate) {
+        process.emitWarning(`Passing "color" to RoleManager#create() is deprecated. Use "colors" instead.`);
+      }
+
+      deprecationEmittedForCreate = true;
+
+      colors = {
+        primary_color: resolveColor(color),
+        secondary_color: null,
+        tertiary_color: null,
+      };
+    }
+
     const data = await this.client.rest.post(Routes.guildRoles(this.guild.id), {
       body: {
         name,
@@ -245,15 +260,28 @@ class RoleManager extends CachedManager {
       if (typeof icon !== 'string') icon = undefined;
     }
 
-    const colors = options.colors && {
+    let colors = options.colors && {
       primary_color: resolveColor(options.colors.primaryColor),
       secondary_color: options.colors.secondaryColor && resolveColor(options.colors.secondaryColor),
       tertiary_color: options.colors.tertiaryColor && resolveColor(options.colors.tertiaryColor),
     };
 
+    if (options.color !== undefined) {
+      if (!deprecationEmittedForEdit) {
+        process.emitWarning(`Passing "color" to RoleManager#edit() is deprecated. Use "colors" instead.`);
+      }
+
+      deprecationEmittedForEdit = true;
+
+      colors = {
+        primary_color: resolveColor(options.color),
+        secondary_color: null,
+        tertiary_color: null,
+      };
+    }
+
     const body = {
       name: options.name,
-      color: options.color === undefined ? undefined : resolveColor(options.color),
       colors,
       hoist: options.hoist,
       permissions: options.permissions === undefined ? undefined : new PermissionsBitField(options.permissions),

packages/discord.js/src/structures/Role.js

@@ -56,6 +56,7 @@ class Role extends Base {
        * The base 10 color of the role
        *
        * @type {number}
+       * @deprecated Use {@link Role#colors} instead.
        */
       this.color = data.color;
     }
@@ -256,6 +257,7 @@ class Role extends Base {
    * @typedef {Object} RoleData
    * @property {string} [name] The name of the role
    * @property {ColorResolvable} [color] The color of the role, either a hex string or a base 10 number
+   * <warn>This property is deprecated. Use `colors` instead.</warn>
    * @property {RoleColorsResolvable} [colors] The colors of the role
    * @property {boolean} [hoist] Whether or not the role should be hoisted
    * @property {number} [position] The position of the role
@@ -316,11 +318,7 @@ class Role extends Base {
    * @param {ColorResolvable} color The color of the role
    * @param {string} [reason] Reason for changing the role's color
    * @returns {Promise<Role>}
-   * @example
-   * // Set the color of a role
-   * role.setColor('#FF0000')
-   *   .then(updated => console.log(`Set color of role to ${updated.color}`))
-   *   .catch(console.error);
+   * @deprecated Use {@link Role#setColors} instead.
    */
   async setColor(color, reason) {
     return this.edit({ color, reason });

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

@@ -3123,6 +3123,7 @@ export class Role extends Base {
     channel: NonThreadGuildBasedChannel | Snowflake,
     checkAdmin?: boolean,
   ): Readonly<PermissionsBitField>;
+  /** @deprecated Use  {@link Role.setColors} instead. */
   public setColor(color: ColorResolvable, reason?: string): Promise<Role>;
   public setColors(colors: RoleColorsResolvable, reason?: string): Promise<Role>;
   public setHoist(hoist?: boolean, reason?: string): Promise<Role>;
@@ -7391,6 +7392,7 @@ export interface ResolvedOverwriteOptions {
 
 export interface RoleData {
   name?: string;
+  /** @deprecated Use {@link RoleData.colors} instead. */
   color?: ColorResolvable;
   colors?: RoleColorsResolvable;
   hoist?: boolean;