From d5b0cf9ffb5456efb270fc7ca8a0995feffe08e8 Mon Sep 17 00:00:00 2001
From: John Leuenhagen <john@zlima12.com>
Date: Thu, 18 Jan 2018 03:17:50 -0500
Subject: [PATCH] Permissions improvements (#2126)

* add Permissions.toArray()

* accept Permissions objects to Permissions.missing()

* accept Permissions as parameter to Permissions.has()

* style fixes

* remove redundant line, update JSDoc for Permission.resolve()

* JSDoc, style, and checkAdmin fixes

* add Permissions.resolveToObject()

* accept PermissionResolvable to Permissions.missing()

* remove `resolveToObject`, fix constructor JSDoc

* remove redundant parameter type

* fix `Permissions.missing()`

* fix checkAdmin

* update Permissions.toArray() description

* eliminate ambiguity in Permissions.toArray() description

* add backticks to permission example

* remove irrelevant type in Permission ctor description

* use this.constructor to properly support OOP

* use simplified approach for Permissions.toArray()

* fix return type on Permissions.toArray()

* move `Permissions#toArray` to more suitable position

* bitwise approach to `Permissions#missing`

* allow `Permissions` to be iterated over

* don't checkAdmin on return array

* remove unnecessary conditional

* fix JSDoc indentation

* use simpler & more reliable approach for missing()

* update PermissionResolvable typedef
---
 src/util/Permissions.js | 30 +++++++++++++++++++++++-------
 1 file changed, 23 insertions(+), 7 deletions(-)

diff --git a/src/util/Permissions.js b/src/util/Permissions.js
index 7ccd9009c..e9ef9d1c5 100644
--- a/src/util/Permissions.js
+++ b/src/util/Permissions.js
@@ -7,19 +7,19 @@ const { RangeError } = require('../errors');
  */
 class Permissions {
   /**
-   * @param {number|PermissionResolvable[]} permissions Permissions or bitfield to read from
+   * @param {PermissionResolvable} permissions Permission(s) to read from
    */
   constructor(permissions) {
     /**
      * Bitfield of the packed permissions
      * @type {number}
      */
-    this.bitfield = typeof permissions === 'number' ? permissions : this.constructor.resolve(permissions);
+    this.bitfield = this.constructor.resolve(permissions);
   }
 
   /**
    * Checks whether the bitfield has a permission, or multiple permissions.
-   * @param {PermissionResolvable|PermissionResolvable[]} permission Permission(s) to check for
+   * @param {PermissionResolvable} permission Permission(s) to check for
    * @param {boolean} [checkAdmin=true] Whether to allow the administrator permission to override
    * @returns {boolean}
    */
@@ -32,11 +32,12 @@ class Permissions {
 
   /**
    * Gets all given permissions that are missing from the bitfield.
-   * @param {PermissionResolvable[]} permissions Permissions to check for
+   * @param {PermissionResolvable} permissions Permission(s) to check for
    * @param {boolean} [checkAdmin=true] Whether to allow the administrator permission to override
-   * @returns {PermissionResolvable[]}
+   * @returns {string[]}
    */
   missing(permissions, checkAdmin = true) {
+    if (!(permissions instanceof Array)) permissions = new this.constructor(permissions).toArray(false);
     return permissions.filter(p => !this.has(p, checkAdmin));
   }
 
@@ -92,17 +93,32 @@ class Permissions {
     return serialized;
   }
 
+  /**
+   * Gets an {@link Array} of permission names (such as `VIEW_CHANNEL`) based on the permissions available.
+   * @param {boolean} [checkAdmin=true] Whether to allow the administrator permission to override
+   * @returns {string[]}
+   */
+  toArray(checkAdmin = true) {
+    return Object.keys(this.constructor.FLAGS).filter(perm => this.has(perm, checkAdmin));
+  }
+
+  *[Symbol.iterator]() {
+    const keys = this.toArray();
+    while (keys.length) yield keys.shift();
+  }
+
   /**
    * Data that can be resolved to give a permission number. This can be:
    * * A string (see {@link Permissions.FLAGS})
    * * A permission number
    * * An instance of Permissions
-   * @typedef {string|number|Permissions} PermissionResolvable
+   * * An Array of PermissionResolvable
+   * @typedef {string|number|Permissions|PermissionResolvable[]} PermissionResolvable
    */
 
   /**
    * Resolves permissions to their numeric form.
-   * @param {PermissionResolvable|PermissionResolvable[]} permission - Permission(s) to resolve
+   * @param {PermissionResolvable} permission - Permission(s) to resolve
    * @returns {number}
    */
   static resolve(permission) {