feat(BitField): add BitField base class (#3759)

* feat(BitField): add BitField base class

* fix(Permissions): properly deprecate the getters/setters

Author: SpaceEEC

src/client/Client.js

@@ -418,7 +418,7 @@ class Client extends EventEmitter {
    *   .catch(console.error);
    */
   generateInvite(permissions) {
-    permissions = typeof permissions === 'undefined' ? 0 : Permissions.resolve(permissions);
+    permissions = Permissions.resolve(permissions);
     return this.fetchApplication().then(application =>
       `https://discordapp.com/oauth2/authorize?client_id=${application.id}&permissions=${permissions}&scope=bot`
     );

src/index.js

@@ -9,6 +9,7 @@ module.exports = {
   WebhookClient: require('./client/WebhookClient'),
 
   // Utilities
+  BitField: require('./util/BitField'),
   Collection: require('./util/Collection'),
   Constants: require('./util/Constants'),
   DiscordAPIError: require('./client/rest/DiscordAPIError'),

src/structures/Presence.js

@@ -192,6 +192,10 @@ class Game {
     return new Date(this.createdTimestamp);
   }
 
+  /**
+   * Flags that describe the activity
+   * @type {ActivityFlags[]}
+   */
   get flags() {
     const flags = [];
     for (const [name, flag] of Object.entries(ActivityFlags)) {

src/util/BitField.js

@@ -0,0 +1,160 @@
+/**
+ * Data structure that makes it easy to interact with a bitfield.
+ */
+class BitField {
+  /**
+   * @param {BitFieldResolvable} [bits=0] Bits(s) to read from
+   */
+  constructor(bits) {
+    /**
+     * Bitfield of the packed bits
+     * @type {number}
+     */
+    this.bitfield = this.constructor.resolve(bits);
+  }
+
+  /**
+   * Checks whether the bitfield has a bit, or any of multiple bits.
+   * @param {BitFieldResolvable} bit Bit(s) to check for
+   * @returns {boolean}
+   */
+  any(bit) {
+    return (this.bitfield & this.constructor.resolve(bit)) !== 0;
+  }
+
+  /**
+   * Checks if this bitfield equals another
+   * @param {BitFieldResolvable} bit Bit(s) to check for
+   * @returns {boolean}
+   */
+  equals(bit) {
+    return this.bitfield === this.constructor.resolve(bit);
+  }
+
+  /**
+   * Checks whether the bitfield has a bit, or multiple bits.
+   * @param {BitFieldResolvable} bit Bit(s) to check for
+   * @returns {boolean}
+   */
+  has(bit) {
+    if (Array.isArray(bit)) return bit.every(p => this.has(p));
+    bit = this.constructor.resolve(bit);
+    return (this.bitfield & bit) === bit;
+  }
+
+  /**
+   * Gets all given bits that are missing from the bitfield.
+   * @param {BitFieldResolvable} bits Bits(s) to check for
+   * @param {...*} hasParams Additional parameters for the has method, if any
+   * @returns {string[]}
+   */
+  missing(bits, ...hasParams) {
+    if (!Array.isArray(bits)) bits = new this.constructor(bits).toArray(false);
+    return bits.filter(p => !this.has(p, ...hasParams));
+  }
+
+  /**
+   * Freezes these bits, making them immutable.
+   * @returns {Readonly<BitField>} These bits
+   */
+  freeze() {
+    return Object.freeze(this);
+  }
+
+  /**
+   * Adds bits to these ones.
+   * @param {...BitFieldResolvable} [bits] Bits to add
+   * @returns {BitField} These bits or new BitField if the instance is frozen.
+   */
+  add(...bits) {
+    let total = 0;
+    for (const bit of bits) {
+      total |= this.constructor.resolve(bit);
+    }
+    if (Object.isFrozen(this)) return new this.constructor(this.bitfield | total);
+    this.bitfield |= total;
+    return this;
+  }
+
+  /**
+   * Removes bits from these.
+   * @param {...BitFieldResolvable} [bits] Bits to remove
+   * @returns {BitField} These bits or new BitField if the instance is frozen.
+   */
+  remove(...bits) {
+    let total = 0;
+    for (const bit of bits) {
+      total |= this.constructor.resolve(bit);
+    }
+    if (Object.isFrozen(this)) return new this.constructor(this.bitfield & ~total);
+    this.bitfield &= ~total;
+    return this;
+  }
+
+  /**
+   * Gets an object mapping field names to a {@link boolean} indicating whether the
+   * bit is available.
+   * @param {...*} hasParams Additional parameters for the has method, if any
+   * @returns {Object}
+   */
+  serialize(...hasParams) {
+    const serialized = {};
+    for (const flag of Object.keys(this.constructor.FLAGS)) {
+      serialized[flag] = this.has(this.constructor.FLAGS[flag], ...hasParams);
+    }
+    return serialized;
+  }
+
+  /**
+   * Gets an {@link Array} of bitfield names based on the bits available.
+   * @param {...*} hasParams Additional parameters for the has method, if any
+   * @returns {string[]}
+   */
+  toArray(...hasParams) {
+    return Object.keys(this.constructor.FLAGS).filter(bit => this.has(bit, ...hasParams));
+  }
+
+  toJSON() {
+    return this.bitfield;
+  }
+
+  valueOf() {
+    return this.bitfield;
+  }
+
+  *[Symbol.iterator]() {
+    yield* this.toArray();
+  }
+
+  /**
+   * Data that can be resolved to give a bitfield. This can be:
+   * * A string (see {@link BitField.FLAGS})
+   * * A bit number
+   * * An instance of BitField
+   * * An Array of BitFieldResolvable
+   * @typedef {string|number|BitField|BitFieldResolvable[]} BitFieldResolvable
+   */
+
+  /**
+   * Resolves bitfields to their numeric form.
+   * @param {BitFieldResolvable} [bit=0] - bit(s) to resolve
+   * @returns {number}
+   */
+  static resolve(bit = 0) {
+    if (typeof bit === 'number' && bit >= 0) return bit;
+    if (bit instanceof BitField) return bit.bitfield;
+    if (Array.isArray(bit)) return bit.map(p => this.resolve(p)).reduce((prev, p) => prev | p, 0);
+    if (typeof bit === 'string' && typeof this.FLAGS[bit] !== 'undefined') return this.FLAGS[bit];
+    throw new RangeError('Invalid bitfield flag or number.');
+  }
+}
+
+/**
+ * Numeric bitfield flags.
+ * <info>Defined in extension classes</info>
+ * @type {Object}
+ * @abstract
+ */
+BitField.FLAGS = {};
+
+module.exports = BitField;

src/util/Constants.js

@@ -386,6 +386,17 @@ exports.ActivityTypes = [
   'CUSTOM_STATUS',
 ];
 
+/**
+ * Numeric activity flags. All available properties:
+ * * `INSTANCE`
+ * * `JOIN`
+ * * `SPECTATE`
+ * * `JOIN_REQUEST`
+ * * `SYNC`
+ * * `PLAY`
+ * @typedef {string} ActivityFlag
+ * @see {@link https://discordapp.com/developers/docs/topics/gateway#activity-object-activity-flags}
+ */
 exports.ActivityFlags = {
   INSTANCE: 1 << 0,
   JOIN: 1 << 1,