refactor: Deprecate fetching user flags (#10550)

* refactor: deprecate fetching user flags

* docs: fix reference

Co-authored-by: Almeida <github@almeidx.dev>

* refactor: use function

* refactor: name approach

---------

Co-authored-by: Almeida <github@almeidx.dev>

packages/discord.js/src/managers/UserManager.js

@@ -7,6 +7,7 @@ const { GuildMember } = require('../structures/GuildMember');
 const { Message } = require('../structures/Message');
 const ThreadMember = require('../structures/ThreadMember');
 const User = require('../structures/User');
+const { emitDeprecationWarningForUserFetchFlags } = require('../util/Util');
 
 /**
  * Manages API methods for users and stores their cache.
@@ -100,8 +101,11 @@ class UserManager extends CachedManager {
    * @param {UserResolvable} user The UserResolvable to identify
    * @param {BaseFetchOptions} [options] Additional options for this fetch
    * @returns {Promise<UserFlagsBitField>}
+   * @deprecated <warn>This method is deprecated and will be removed in the next major version.
+   * Flags may still be retrieved via {@link UserManager#fetch}.</warn>
    */
   async fetchFlags(user, options) {
+    emitDeprecationWarningForUserFetchFlags(this.constructor.name);
     return (await this.fetch(user, options)).flags;
   }
 

packages/discord.js/src/structures/User.js

@@ -6,6 +6,7 @@ const { DiscordSnowflake } = require('@sapphire/snowflake');
 const Base = require('./Base');
 const TextBasedChannel = require('./interfaces/TextBasedChannel');
 const UserFlagsBitField = require('../util/UserFlagsBitField');
+const { emitDeprecationWarningForUserFetchFlags } = require('../util/Util');
 
 /**
  * Represents a user on Discord.
@@ -346,8 +347,11 @@ class User extends Base {
    * Fetches this user's flags.
    * @param {boolean} [force=false] Whether to skip the cache check and request the API
    * @returns {Promise<UserFlagsBitField>}
+   * @deprecated <warn>This method is deprecated and will be removed in the next major version.
+   * Flags may still be retrieved via {@link User#fetch}.</warn>
    */
   fetchFlags(force = false) {
+    emitDeprecationWarningForUserFetchFlags(this.constructor.name);
     return this.client.users.fetchFlags(this.id, { force });
   }
 

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

@@ -1,6 +1,7 @@
 'use strict';
 
 const { parse } = require('node:path');
+const process = require('node:process');
 const { Collection } = require('@discordjs/collection');
 const { ChannelType, RouteBases, Routes } = require('discord-api-types/v10');
 const { fetch } = require('undici');
@@ -8,6 +9,8 @@ const Colors = require('./Colors');
 const { DiscordjsError, DiscordjsRangeError, DiscordjsTypeError, ErrorCodes } = require('../errors');
 const isObject = d => typeof d === 'object' && d !== null;
 
+let deprecationEmittedForUserFetchFlags = false;
+
 /**
  * Flatten an object. Any properties that are collections will get converted to an array of keys.
  * @param {Object} obj The object to flatten.
@@ -499,6 +502,17 @@ function resolveSKUId(resolvable) {
   return null;
 }
 
+/**
+ * Deprecation function for fetching user flags.
+ * @param {string} name Name of the class
+ * @private
+ */
+function emitDeprecationWarningForUserFetchFlags(name) {
+  if (deprecationEmittedForUserFetchFlags) return;
+  process.emitWarning(`${name}#fetchFlags() is deprecated. Use ${name}#fetch() instead.`);
+  deprecationEmittedForUserFetchFlags = true;
+}
+
 module.exports = {
   flatten,
   fetchRecommendedShardCount,
@@ -518,6 +532,7 @@ module.exports = {
   parseWebhookURL,
   transformResolved,
   resolveSKUId,
+  emitDeprecationWarningForUserFetchFlags,
 };
 
 // Fixes Circular

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

@@ -3461,6 +3461,7 @@ export class User extends Base {
   public displayAvatarURL(options?: ImageURLOptions): string;
   public equals(user: User): boolean;
   public fetch(force?: boolean): Promise<User>;
+  /** @deprecated This method is deprecated and will be removed in the next major version. Flags may still be retrieved via {@link User.fetch} */
   public fetchFlags(force?: boolean): Promise<UserFlagsBitField>;
   public toString(): UserMention;
 }
@@ -4693,6 +4694,7 @@ export class UserManager extends CachedManager<Snowflake, User, UserResolvable>
   public createDM(user: UserResolvable, options?: BaseFetchOptions): Promise<DMChannel>;
   public deleteDM(user: UserResolvable): Promise<DMChannel>;
   public fetch(user: UserResolvable, options?: BaseFetchOptions): Promise<User>;
+  /** @deprecated This method is deprecated and will be removed in the next major version. Flags may still be retrieved via {@link UserManager.fetch} */
   public fetchFlags(user: UserResolvable, options?: BaseFetchOptions): Promise<UserFlagsBitField>;
   public send(user: UserResolvable, options: string | MessagePayload | MessageCreateOptions): Promise<Message>;
 }

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

@@ -212,6 +212,7 @@ import {
   GuildScheduledEventManager,
   SendableChannels,
   PollData,
+  UserManager,
 } from '.';
 import { expectAssignable, expectDeprecated, expectNotAssignable, expectNotType, expectType } from 'tsd';
 import type { ContextMenuCommandBuilder, SlashCommandBuilder } from '@discordjs/builders';
@@ -1753,6 +1754,12 @@ declare const threadMemberManager: ThreadMemberManager;
   threadMemberManager.fetch({ withMember: false, limit: 5, after: '12345678901234567' });
 }
 
+declare const userManager: UserManager;
+{
+  expectDeprecated(userManager.fetchFlags('1234567890'));
+  expectDeprecated(user.fetchFlags());
+}
+
 declare const typing: Typing;
 expectType<User | PartialUser>(typing.user);
 if (typing.user.partial) expectType<null>(typing.user.username);