feat: PermissionOverwriteManager

esm/discord.mjs

@@ -39,6 +39,7 @@ export const {
   ReactionManager,
   ReactionUserManager,
   MessageManager,
+  PermisssionOverwriteManager,
   PresenceManager,
   RoleManager,
   UserManager,

src/index.js

@@ -44,6 +44,7 @@ module.exports = {
   ReactionManager: require('./managers/ReactionManager'),
   ReactionUserManager: require('./managers/ReactionUserManager'),
   MessageManager: require('./managers/MessageManager'),
+  PermissionOverwriteManager: require('./managers/PermissionOverwriteManager'),
   PresenceManager: require('./managers/PresenceManager'),
   RoleManager: require('./managers/RoleManager'),
   UserManager: require('./managers/UserManager'),

src/managers/PermissionOverwriteManager.js

@@ -0,0 +1,149 @@
+'use strict';
+
+const BaseManager = require('./BaseManager');
+const { TypeError } = require('../errors');
+const PermissionOverwrites = require('../structures/PermissionOverwrites');
+const Role = require('../structures/Role');
+const Collection = require('../util/Collection');
+const { OverwriteTypes } = require('../util/Constants');
+
+/**
+ * Manages API methods for guild channel permission overwrites and stores their cache.
+ * @extends {BaseManager}
+ */
+class PermissionOverwriteManager extends BaseManager {
+  constructor(channel, iterable) {
+    super(channel.client, iterable, PermissionOverwrites);
+
+    /**
+     * The channel of the permission overwrite this manager belongs to
+     * @type {GuildChannel}
+     */
+    this.channel = channel;
+  }
+
+  /**
+   * The cache of this Manager
+   * @type {Collection<Snowflake, PermissionOverwrites>}
+   * @name PermissionOverwriteManager#cache
+   */
+
+  add(data, cache) {
+    return super.add(data, cache, { extras: [this.channel] });
+  }
+
+  /**
+   * Replaces the permission overwrites in this channel.
+   * @param {OverwriteResolvable[]|Collection<Snowflake, OverwriteResolvable>} overwrites
+   * Permission overwrites the channel gets updated with
+   * @param {string} [reason] Reason for updating the channel overwrites
+   * @returns {Promise<GuildChannel>}
+   * @example
+   * message.channel.permissionOverwrites.set([
+   *   {
+   *      id: message.author.id,
+   *      deny: [Permissions.FLAGS.VIEW_CHANNEL],
+   *   },
+   * ], 'Needed to change permissions');
+   */
+  set(overwrites, reason) {
+    if (!Array.isArray(overwrites) && !(overwrites instanceof Collection)) {
+      throw new TypeError('INVALID_TYPE', 'overwrites', 'Array or Collection of Permission Overwrites', true);
+    }
+    return this.channel.edit({ permissionOverwrites: overwrites, reason });
+  }
+
+  /**
+   * Extra information about the overwrite
+   * @typedef {Object} GuildChannelOverwriteOptions
+   * @property {string} [reason] Reason for creating/editing this overwrite
+   * @property {number} [type] The type of overwrite, either `0` for a role or `1` for a member. Use this to bypass
+   * automatic resolution of type that results in an error for uncached structure
+   */
+
+  /**
+   * Creates or edits permission overwrites for a user or role in this channel.
+   * @param {RoleResolvable|UserResolvable} userOrRole The user or role to update
+   * @param {PermissionOverwriteOptions} options The options for the update
+   * @param {GuildChannelOverwriteOptions} [overwriteOptions] The extra information for the update
+   * @param {PermissionOverwrites} [existing] The existing overwrites to merge with this update
+   * @returns {Promise<GuildChannel>}
+   */
+  async upsert(userOrRole, options, overwriteOptions = {}, existing) {
+    let userOrRoleID = this.channel.guild.roles.resolveID(userOrRole) ?? this.client.users.resolveID(userOrRole);
+    let { type, reason } = overwriteOptions;
+    if (typeof type !== 'number') {
+      userOrRole = this.channel.guild.roles.resolve(userOrRole) ?? this.client.users.resolve(userOrRole);
+      if (!userOrRole) return Promise.reject(new TypeError('INVALID_TYPE', 'parameter', 'User nor a Role'));
+      type = userOrRole instanceof Role ? OverwriteTypes.role : OverwriteTypes.member;
+    }
+
+    const { allow, deny } = existing
+      ? PermissionOverwrites.resolveOverwriteOptions(options)
+      : PermissionOverwrites.resolveOverwriteOptions(options, existing);
+
+    await this.client.api
+      .channels(this.channel.id)
+      .permissions(userOrRoleID)
+      .put({
+        data: { id: userOrRoleID, type, allow, deny },
+        reason,
+      });
+    return this.channel;
+  }
+
+  /**
+   * Creates permission overwrites for a user or role in this channel, or replaces them if already present.
+   * @param {RoleResolvable|UserResolvable} userOrRole The user or role to update
+   * @param {PermissionOverwriteOptions} options The options for the update
+   * @param {GuildChannelOverwriteOptions} [overwriteOptions] The extra information for the update
+   * @returns {Promise<GuildChannel>}
+   * @example
+   * // Create or Replace permission overwrites for a message author
+   * message.channel.permissionOverwrites.create(message.author, {
+   *   SEND_MESSAGES: false
+   * })
+   *   .then(channel => console.log(channel.permissionOverwrites.cache.get(message.author.id)))
+   *   .catch(console.error);
+   */
+  create(userOrRole, options, overwriteOptions) {
+    return this.upsert(userOrRole, options, overwriteOptions);
+  }
+
+  /**
+   * Edits permission overwrites for a user or role in this channel, or creates an entry if not already present.
+   * @param {RoleResolvable|UserResolvable} userOrRole The user or role to update
+   * @param {PermissionOverwriteOptions} options The options for the update
+   * @param {GuildChannelOverwriteOptions} [overwriteOptions] The extra information for the update
+   * @returns {Promise<GuildChannel>}
+   * @example
+   * // Edit or Create permission overwrites for a message author
+   * message.channel.permissionOverwrites.edit(message.author, {
+   *   SEND_MESSAGES: false
+   * })
+   *   .then(channel => console.log(channel.permissionOverwrites.cache.get(message.author.id)))
+   *   .catch(console.error);
+   */
+  edit(userOrRole, options, overwriteOptions) {
+    userOrRole = this.channel.guild.roles.resolveID(userOrRole) ?? this.client.users.resolveID(userOrRole);
+    const existing = this.cache.get(userOrRole);
+    if (existing) return this.upsert(userOrRole, options, overwriteOptions, existing);
+    return this.create(userOrRole, options, overwriteOptions);
+  }
+
+  /**
+   * Deletes permission overwrites for a user or role in this channel
+   * @param {UserResolvable|RoleResolvable} userOrRole The user or role to delete
+   * @param {string} [reason] The reason for deleting the overwrite
+   * @returns {GuildChannel}
+   */
+  async delete(userOrRole, reason) {
+    userOrRole = this.channel.guild.roles.resolve(userOrRole) ?? this.client.users.resolve(userOrRole);
+    if (!userOrRole) throw new TypeError('INVALID_TYPE', 'parameter', 'User nor a Role');
+
+    await this.client.api.channels(this.channel.id).permissions(userOrRole.id).delete({ reason });
+    return this.channel;
+  }
+}
+
+module.exports = PermissionOverwriteManager;

src/structures/GuildChannel.js

@@ -3,11 +3,10 @@
 const Channel = require('./Channel');
 const Invite = require('./Invite');
 const PermissionOverwrites = require('./PermissionOverwrites');
-const Role = require('./Role');
-const { Error, TypeError } = require('../errors');
+const { Error } = require('../errors');
+const PermissionOverwriteManager = require('../managers/PermissionOverwriteManager');
 const Collection = require('../util/Collection');
 const { ChannelTypes } = require('../util/Constants');
-const { OverwriteTypes } = require('../util/Constants');
 const Permissions = require('../util/Permissions');
 const Util = require('../util/Util');
 
@@ -59,13 +58,13 @@ class GuildChannel extends Channel {
     this.parentID = data.parent_id || null;
 
     /**
-     * A map of permission overwrites in this channel for roles and users
-     * @type {Collection<Snowflake, PermissionOverwrites>}
+     * A manager of permission overwrites that belong to this channel
+     * @type {PermissionOverwriteManager}
      */
-    this.permissionOverwrites = new Collection();
+    this.permissionOverwrites = new PermissionOverwriteManager(this);
     if (data.permission_overwrites) {
       for (const overwrite of data.permission_overwrites) {
-        this.permissionOverwrites.set(overwrite.id, new PermissionOverwrites(this, overwrite));
+        this.permissionOverwrites.add(overwrite);
       }
     }
   }
@@ -192,91 +191,6 @@ class GuildChannel extends Channel {
       .freeze();
   }
 
-  /**
-   * Replaces the permission overwrites in this channel.
-   * @param {OverwriteResolvable[]|Collection<Snowflake, OverwriteResolvable>} overwrites
-   * Permission overwrites the channel gets updated with
-   * @param {string} [reason] Reason for updating the channel overwrites
-   * @returns {Promise<GuildChannel>}
-   * @example
-   * channel.overwritePermissions([
-   *   {
-   *      id: message.author.id,
-   *      deny: [Permissions.FLAGS.VIEW_CHANNEL],
-   *   },
-   * ], 'Needed to change permissions');
-   */
-  async overwritePermissions(overwrites, reason) {
-    if (!Array.isArray(overwrites) && !(overwrites instanceof Collection)) {
-      throw new TypeError('INVALID_TYPE', 'overwrites', 'Array or Collection of Permission Overwrites', true);
-    }
-    await this.edit({ permissionOverwrites: overwrites }, reason);
-    return this;
-  }
-
-  /**
-   * Updates permission overwrites for a user or role in this channel, or creates an entry if not already present.
-   * @param {RoleResolvable|UserResolvable} userOrRole The user or role to update
-   * @param {PermissionOverwriteOptions} options The options for the update
-   * @param {string} [reason] Reason for creating/editing this overwrite
-   * @returns {Promise<GuildChannel>}
-   * @example
-   * // Update or Create permission overwrites for a message author
-   * message.channel.updateOverwrite(message.author, {
-   *   SEND_MESSAGES: false
-   * })
-   *   .then(channel => console.log(channel.permissionOverwrites.get(message.author.id)))
-   *   .catch(console.error);
-   */
-  async updateOverwrite(userOrRole, options, reason) {
-    userOrRole = this.guild.roles.resolve(userOrRole) || this.client.users.resolve(userOrRole);
-    if (!userOrRole) return Promise.reject(new TypeError('INVALID_TYPE', 'parameter', 'User nor a Role'));
-
-    const existing = this.permissionOverwrites.get(userOrRole.id);
-    if (existing) {
-      await existing.update(options, reason);
-    } else {
-      await this.createOverwrite(userOrRole, options, reason);
-    }
-    return this;
-  }
-
-  /**
-   * Creates permission overwrites for a user or role in this channel, or replaces them if already present.
-   * @param {RoleResolvable|UserResolvable} userOrRole The user or role to update
-   * @param {PermissionOverwriteOptions} options The options for the update
-   * @param {string} [reason] Reason for creating/editing this overwrite
-   * @returns {Promise<GuildChannel>}
-   * @example
-   * // Create or Replace permission overwrites for a message author
-   * message.channel.createOverwrite(message.author, {
-   *   SEND_MESSAGES: false
-   * })
-   *   .then(channel => console.log(channel.permissionOverwrites.get(message.author.id)))
-   *   .catch(console.error);
-   */
-  createOverwrite(userOrRole, options, reason) {
-    userOrRole = this.guild.roles.resolve(userOrRole) || this.client.users.resolve(userOrRole);
-    if (!userOrRole) return Promise.reject(new TypeError('INVALID_TYPE', 'parameter', 'User nor a Role'));
-
-    const type = userOrRole instanceof Role ? OverwriteTypes.role : OverwriteTypes.member;
-    const { allow, deny } = PermissionOverwrites.resolveOverwriteOptions(options);
-
-    return this.client.api
-      .channels(this.id)
-      .permissions(userOrRole.id)
-      .put({
-        data: {
-          id: userOrRole.id,
-          type,
-          allow,
-          deny,
-        },
-        reason,
-      })
-      .then(() => this);
-  }
-
   /**
    * Locks in the permission overwrites from the parent channel.
    * @returns {Promise<GuildChannel>}

src/structures/PermissionOverwrites.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const Base = require('./Base');
 const Role = require('./Role');
 const { TypeError } = require('../errors');
 const { OverwriteTypes } = require('../util/Constants');
@@ -8,15 +9,17 @@ const Permissions = require('../util/Permissions');
 /**
  * Represents a permission overwrite for a role or member in a guild channel.
  */
-class PermissionOverwrites {
-  constructor(guildChannel, data) {
+class PermissionOverwrites extends Base {
+  constructor(client, data, channel) {
+    super(client);
+
     /**
      * The GuildChannel this overwrite is for
      * @name PermissionOverwrites#channel
      * @type {GuildChannel}
      * @readonly
      */
-    Object.defineProperty(this, 'channel', { value: guildChannel });
+    Object.defineProperty(this, 'channel', { value: channel });
 
     if (data) this._patch(data);
   }
@@ -48,33 +51,20 @@ class PermissionOverwrites {
   }
 
   /**
-   * Updates this permissionOverwrites.
+   * Edits this Permission Overwrite.
    * @param {PermissionOverwriteOptions} options The options for the update
    * @param {string} [reason] Reason for creating/editing this overwrite
    * @returns {Promise<PermissionOverwrites>}
    * @example
    * // Update permission overwrites
-   * permissionOverwrites.update({
+   * permissionOverwrites.edit({
    *   SEND_MESSAGES: false
    * })
    *   .then(channel => console.log(channel.permissionOverwrites.get(message.author.id)))
    *   .catch(console.error);
    */
-  async update(options, reason) {
-    const { allow, deny } = this.constructor.resolveOverwriteOptions(options, this);
-
-    await this.channel.client.api
-      .channels(this.channel.id)
-      .permissions(this.id)
-      .put({
-        data: {
-          id: this.id,
-          type: OverwriteTypes[this.type],
-          allow,
-          deny,
-        },
-        reason,
-      });
+  async edit(options, reason) {
+    await this.channel.permissionOverwrites.edit(this.id, options, reason);
     return this;
   }
 
@@ -84,7 +74,7 @@ class PermissionOverwrites {
    * @returns {Promise<PermissionOverwrites>}
    */
   async delete(reason) {
-    await this.channel.client.api.channels(this.channel.id).permissions(this.id).delete({ reason });
+    await this.channel.permissionOverwrites.delete(this.id, reason);
     return this;
   }