feat(GuildManager): adds GuildManager#fetch (#4086)

Co-authored-by: Sugden <28943913+NotSugden@users.noreply.github.com>

src/managers/GuildManager.js

@@ -214,6 +214,28 @@ class GuildManager extends BaseManager {
         }, reject),
     );
   }
+
+  /**
+   * Obtains a guild from Discord, or the guild cache if it's already available.
+   * @param {Snowflake} id ID of the guild
+   * @param {boolean} [cache=true] Whether to cache the new guild object if it isn't already
+   * @param {boolean} [force=false] Whether to skip the cache check and request the API
+   * @returns {Promise<Guild>}
+   * @example
+   * // Fetch a guild by its id
+   * client.guilds.fetch('222078108977594368')
+   *   .then(guild => console.log(guild.name))
+   *   .catch(console.error);
+   */
+  async fetch(id, cache = true, force = false) {
+    if (!force) {
+      const existing = this.cache.get(id);
+      if (existing) return existing;
+    }
+
+    const data = await this.client.api.guilds(id).get({ query: { with_counts: true } });
+    return this.add(data, cache);
+  }
 }
 
 module.exports = GuildManager;

typings/index.d.ts

@@ -1912,6 +1912,7 @@ declare module 'discord.js' {
       name: string,
       options?: { region?: string; icon: BufferResolvable | Base64Resolvable | null },
     ): Promise<Guild>;
+    public fetch(id: Snowflake, cache?: boolean, force?: boolean): Promise<Guild>;
   }
 
   export class GuildMemberManager extends BaseManager<Snowflake, GuildMember, GuildMemberResolvable> {