refactor: fetch options consistency (#5824)

src/managers/ChannelManager.js

@@ -73,8 +73,7 @@ class ChannelManager extends BaseManager {
   /**
    * Obtains a channel from Discord, or the channel cache if it's already available.
    * @param {Snowflake} id ID of the channel
-   * @param {boolean} [cache=true] Whether to cache the new channel object if it isn't already
+   * @param {BaseFetchOptions} [options] Additional options for this fetch
-   * @param {boolean} [force=false] Whether to skip the cache check and request the API
    * @returns {Promise<?Channel>}
    * @example
    * // Fetch a channel by its id
@@ -82,7 +81,7 @@ class ChannelManager extends BaseManager {
    *   .then(channel => console.log(channel.name))
    *   .catch(console.error);
    */
-  async fetch(id, cache = true, force = false) {
+  async fetch(id, { cache = true, force = false } = {}) {
     if (!force) {
       const existing = this.cache.get(id);
       if (existing && !existing.partial) return existing;

src/managers/GuildBanManager.js

@@ -49,10 +49,8 @@ class GuildBanManager extends BaseManager {
 
   /**
    * Options used to fetch a single ban from a guild.
-   * @typedef {Object} FetchBanOptions
+   * @typedef {BaseFetchOptions} FetchBanOptions
    * @property {UserResolvable} user The ban to fetch
-   * @property {boolean} [cache=true] Whether or not to cache the fetched ban
-   * @property {boolean} [force=false] Whether to skip the cache check and request the API
    */
 
   /**

src/managers/GuildChannelManager.js

@@ -122,8 +122,7 @@ class GuildChannelManager extends BaseManager {
   /**
    * Obtains one or more guild channels from Discord, or the channel cache if they're already available.
    * @param {Snowflake} [id] ID of the channel
-   * @param {boolean} [cache=true] Whether to cache the new channel objects if it weren't already
+   * @param {BaseFetchOptions} [options] Additional options for this fetch
-   * @param {boolean} [force=false] Whether to skip the cache check and request the API
    * @returns {Promise<?GuildChannel|Collection<Snowflake, GuildChannel>>}
    * @example
    * // Fetch all channels from the guild
@@ -136,7 +135,7 @@ class GuildChannelManager extends BaseManager {
    *   .then(channel => console.log(`The channel name is: ${channel.name}`))
    *   .catch(console.error);
    */
-  async fetch(id, cache = true, force = false) {
+  async fetch(id, { cache = true, force = false } = {}) {
     if (id && !force) {
       const existing = this.cache.get(id);
       if (existing) return existing;

src/managers/GuildEmojiManager.js

@@ -69,8 +69,7 @@ class GuildEmojiManager extends BaseGuildEmojiManager {
   /**
    * Obtains one or more emojis from Discord, or the emoji cache if they're already available.
    * @param {Snowflake} [id] ID of the emoji
-   * @param {boolean} [cache=true] Whether to cache the new emoji objects if it weren't already
+   * @param {BaseFetchOptions} [options] Additional options for this fetch
-   * @param {boolean} [force=false] Whether to skip the cache check and request the API
    * @returns {Promise<GuildEmoji|Collection<Snowflake, GuildEmoji>>}
    * @example
    * // Fetch all emojis from the guild
@@ -83,7 +82,7 @@ class GuildEmojiManager extends BaseGuildEmojiManager {
    *   .then(emoji => console.log(`The emoji name is: ${emoji.name}`))
    *   .catch(console.error);
    */
-  async fetch(id, cache = true, force = false) {
+  async fetch(id, { cache = true, force = false } = {}) {
     if (id) {
       if (!force) {
         const existing = this.cache.get(id);

src/managers/GuildManager.js

@@ -233,10 +233,8 @@ class GuildManager extends BaseManager {
 
   /**
    * Options used to fetch a single guild.
-   * @typedef {Object} FetchGuildOptions
+   * @typedef {BaseFetchOptions} FetchGuildOptions
    * @property {GuildResolvable} guild The guild to fetch
-   * @property {boolean} [cache=true] Whether or not to cache the fetched guild
-   * @property {boolean} [force=false] Whether to skip the cache check and request the API
    */
 
   /**

src/managers/GuildMemberManager.js

@@ -67,10 +67,8 @@ class GuildMemberManager extends BaseManager {
 
   /**
    * Options used to fetch a single member from a guild.
-   * @typedef {Object} FetchMemberOptions
+   * @typedef {BaseFetchOptions} FetchMemberOptions
    * @property {UserResolvable} user The user to fetch
-   * @property {boolean} [cache=true] Whether or not to cache the fetched member
-   * @property {boolean} [force=false] Whether to skip the cache check and request the API
    */
 
   /**

src/managers/MessageManager.js

@@ -46,8 +46,7 @@ class MessageManager extends BaseManager {
    * <info>The returned Collection does not contain reaction users of the messages if they were not cached.
    * Those need to be fetched separately in such a case.</info>
    * @param {Snowflake|ChannelLogsQueryOptions} [message] The ID of the message to fetch, or query parameters.
-   * @param {boolean} [cache=true] Whether to cache the message(s)
+   * @param {BaseFetchOptions} [options] Additional options for this fetch
-   * @param {boolean} [force=false] Whether to skip the cache check and request the API
    * @returns {Promise<Message>|Promise<Collection<Snowflake, Message>>}
    * @example
    * // Get message
@@ -65,7 +64,7 @@ class MessageManager extends BaseManager {
    *   .then(messages => console.log(`${messages.filter(m => m.author.id === '84484653687267328').size} messages`))
    *   .catch(console.error);
    */
-  fetch(message, cache = true, force = false) {
+  fetch(message, { cache = true, force = false } = {}) {
     return typeof message === 'string' ? this._fetchId(message, cache, force) : this._fetchMany(message, cache);
   }
 

src/managers/RoleManager.js

@@ -33,8 +33,7 @@ class RoleManager extends BaseManager {
   /**
    * Obtains a role from Discord, or the role cache if they're already available.
    * @param {Snowflake} [id] ID of the role
-   * @param {boolean} [cache=true] Whether to cache the new role object(s) if they weren't already
+   * @param {BaseFetchOptions} [options] Additional options for this fetch
-   * @param {boolean} [force=false] Whether to skip the cache check and request the API
    * @returns {Promise<?Role|Collection<Snowflake, Role>>}
    * @example
    * // Fetch all roles from the guild
@@ -47,7 +46,7 @@ class RoleManager extends BaseManager {
    *   .then(role => console.log(`The role color is: ${role.color}`))
    *   .catch(console.error);
    */
-  async fetch(id, cache = true, force = false) {
+  async fetch(id, { cache = true, force = false } = {}) {
     if (id && !force) {
       const existing = this.cache.get(id);
       if (existing) return existing;

src/managers/UserManager.js

@@ -54,11 +54,10 @@ class UserManager extends BaseManager {
   /**
    * Obtains a user from Discord, or the user cache if it's already available.
    * @param {Snowflake} id ID of the user
-   * @param {boolean} [cache=true] Whether to cache the new user object if it isn't already
+   * @param {BaseFetchOptions} [options] Additional options for this fetch
-   * @param {boolean} [force=false] Whether to skip the cache check and request the API
    * @returns {Promise<User>}
    */
-  async fetch(id, cache = true, force = false) {
+  async fetch(id, { cache = true, force = false } = {}) {
     if (!force) {
       const existing = this.cache.get(id);
       if (existing && !existing.partial) return existing;

typings/index.d.ts

@@ -2107,7 +2107,7 @@ declare module 'discord.js' {
 
   export class ChannelManager extends BaseManager<Snowflake, Channel, ChannelResolvable> {
     constructor(client: Client, iterable: Iterable<any>);
-    public fetch(id: Snowflake, cache?: boolean, force?: boolean): Promise<Channel | null>;
+    public fetch(id: Snowflake, options?: BaseFetchOptions): Promise<Channel | null>;
   }
 
   export class GuildApplicationCommandManager extends ApplicationCommandManager {
@@ -2145,13 +2145,11 @@ declare module 'discord.js' {
     ): Promise<TextChannel | VoiceChannel | CategoryChannel | NewsChannel | StoreChannel | StageChannel>;
     public fetch(
       id: Snowflake,
-      cache?: boolean,
+      options?: BaseFetchOptions,
-      force?: boolean,
     ): Promise<TextChannel | VoiceChannel | CategoryChannel | NewsChannel | StoreChannel | StageChannel | null>;
     public fetch(
       id?: Snowflake,
-      cache?: boolean,
+      options?: BaseFetchOptions,
-      force?: boolean,
     ): Promise<
       Collection<Snowflake, TextChannel | VoiceChannel | CategoryChannel | NewsChannel | StoreChannel | StageChannel>
     >;
@@ -2165,8 +2163,8 @@ declare module 'discord.js' {
       name: string,
       options?: GuildEmojiCreateOptions,
     ): Promise<GuildEmoji>;
-    public fetch(id: Snowflake, cache?: boolean, force?: boolean): Promise<GuildEmoji>;
+    public fetch(id: Snowflake, options?: BaseFetchOptions): Promise<GuildEmoji>;
-    public fetch(id?: Snowflake, cache?: boolean, force?: boolean): Promise<Collection<Snowflake, GuildEmoji>>;
+    public fetch(id?: Snowflake, options?: BaseFetchOptions): Promise<Collection<Snowflake, GuildEmoji>>;
   }
 
   export class GuildEmojiRoleManager {
@@ -2246,11 +2244,10 @@ declare module 'discord.js' {
     public crosspost(message: MessageResolvable): Promise<Message>;
     public delete(message: MessageResolvable): Promise<void>;
     public edit(message: MessageResolvable, options: APIMessage | MessageEditOptions): Promise<Message>;
-    public fetch(message: Snowflake, cache?: boolean, force?: boolean): Promise<Message>;
+    public fetch(message: Snowflake, options?: BaseFetchOptions): Promise<Message>;
     public fetch(
       options?: ChannelLogsQueryOptions,
-      cache?: boolean,
+      cacheOptions?: BaseFetchOptions,
-      force?: boolean,
     ): Promise<Collection<Snowflake, Message>>;
     public fetchPinned(cache?: boolean): Promise<Collection<Snowflake, Message>>;
     public react(message: MessageResolvable, emoji: EmojiIdentifierResolvable): Promise<void>;
@@ -2283,13 +2280,13 @@ declare module 'discord.js' {
     public readonly premiumSubscriberRole: Role | null;
     public botRoleFor(user: UserResolvable): Role | null;
     public create(options?: RoleData & { reason?: string }): Promise<Role>;
-    public fetch(id: Snowflake, cache?: boolean, force?: boolean): Promise<Role | null>;
+    public fetch(id: Snowflake, options?: BaseFetchOptions): Promise<Role | null>;
-    public fetch(id?: Snowflake, cache?: boolean, force?: boolean): Promise<Collection<Snowflake, Role>>;
+    public fetch(id?: Snowflake, options?: BaseFetchOptions): Promise<Collection<Snowflake, Role>>;
   }
 
   export class UserManager extends BaseManager<Snowflake, User, UserResolvable> {
     constructor(client: Client, iterable?: Iterable<any>);
-    public fetch(id: Snowflake, cache?: boolean, force?: boolean): Promise<User>;
+    public fetch(id: Snowflake, options?: BaseFetchOptions): Promise<User>;
   }
 
   export class VoiceStateManager extends BaseManager<Snowflake, VoiceState, typeof VoiceState> {
@@ -2852,20 +2849,16 @@ declare module 'discord.js' {
     guildID?: Snowflake;
   }
 
-  interface FetchBanOptions {
+  interface FetchBanOptions extends BaseFetchOptions {
     user: UserResolvable;
-    cache?: boolean;
-    force?: boolean;
   }
 
   interface FetchBansOptions {
     cache: boolean;
   }
 
-  interface FetchGuildOptions {
+  interface FetchGuildOptions extends BaseFetchOptions {
     guild: GuildResolvable;
-    cache?: boolean;
-    force?: boolean;
   }
 
   interface FetchGuildsOptions {
@@ -2874,10 +2867,8 @@ declare module 'discord.js' {
     limit?: number;
   }
 
-  interface FetchMemberOptions {
+  interface FetchMemberOptions extends BaseFetchOptions {
     user: UserResolvable;
-    cache?: boolean;
-    force?: boolean;
   }
 
   interface FetchMembersOptions {