mirror of
https://github.com/discordjs/discord.js.git
synced 2026-03-12 09:33:32 +01:00
refactor(BitField): base class for Permissions, ActivityFlags, Speaking (#2765)
* abstract BitField from Permissions * reduce useless code, improve docs * add a ReadOnly identifier to the return type of Bitfield#freeze() https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-1.html#partial-readonly-record-and-pick * fix the RangeError * update docs, convert Speaking and ActivityFlags to bitfields * fix some docs * Fix Speaking BitField oops * docs for oops * more incorrect docs * Fix incorrectly named property * add new classes to index * fix missing @extends docs * default bitfield resolve to 0, and cleanup defaulting everywhere Also removes GuildMember#missiongPermissions() alias that had incorrect behavior * Breaking: Rename Overwrite allowed and denied to allow and deny To be consistent with the api's naming * fix setSpeaking usage to bitfields instead of booleans * fix speaking bug in playChunk * docs: Updated typings * fix: BitFieldResolvable should use RecursiveArray * bugfix/requested change * typings: Cleanup (#2) * typings: Fix BitField#{toArray,@@iterator} output type * typings: correct PermissionOverwrites property names and nitpicks
This commit is contained in:
bdistin
29
src/util/ActivityFlags.js
Normal file
29
src/util/ActivityFlags.js
Normal file
@@ -0,0 +1,29 @@
|
||||
const BitField = require('./BitField');
|
||||
|
||||
/**
|
||||
* Data structure that makes it easy to interact with an {@link Activity#flags} bitfield.
|
||||
* @extends {BitField}
|
||||
*/
|
||||
class ActivityFlags extends BitField {}
|
||||
|
||||
/**
|
||||
* Numeric activity flags. All available properties:
|
||||
* * `INSTANCE`
|
||||
* * `JOIN`
|
||||
* * `SPECTATE`
|
||||
* * `JOIN_REQUEST`
|
||||
* * `SYNC`
|
||||
* * `PLAY`
|
||||
* @type {Object}
|
||||
* @see {@link https://discordapp.com/developers/docs/topics/gateway#activity-object-activity-flags}
|
||||
*/
|
||||
ActivityFlags.FLAGS = {
|
||||
INSTANCE: 1 << 0,
|
||||
JOIN: 1 << 1,
|
||||
SPECTATE: 1 << 2,
|
||||
JOIN_REQUEST: 1 << 3,
|
||||
SYNC: 1 << 4,
|
||||
PLAY: 1 << 5,
|
||||
};
|
||||
|
||||
module.exports = ActivityFlags;
|
||||
151
src/util/BitField.js
Normal file
151
src/util/BitField.js
Normal file
@@ -0,0 +1,151 @@
|
||||
const { RangeError } = require('../errors');
|
||||
|
||||
/**
|
||||
* 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 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 (bit instanceof Array) 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 (!(bits instanceof Array)) 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 perm in this.constructor.FLAGS) serialized[perm] = this.has(perm, ...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 (bit instanceof Array) return bit.map(p => this.resolve(p)).reduce((prev, p) => prev | p, 0);
|
||||
if (typeof bit === 'string') return this.FLAGS[bit];
|
||||
throw new RangeError('BITFIELD_INVALID');
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Numeric bitfield flags.
|
||||
* <info>Defined in extension classes</info>
|
||||
* @type {Object}
|
||||
* @abstract
|
||||
*/
|
||||
BitField.FLAGS = {};
|
||||
|
||||
module.exports = BitField;
|
||||
@@ -367,15 +367,6 @@ exports.ActivityTypes = [
|
||||
'WATCHING',
|
||||
];
|
||||
|
||||
exports.ActivityFlags = {
|
||||
INSTANCE: 1 << 0,
|
||||
JOIN: 1 << 1,
|
||||
SPECTATE: 1 << 2,
|
||||
JOIN_REQUEST: 1 << 3,
|
||||
SYNC: 1 << 4,
|
||||
PLAY: 1 << 5,
|
||||
};
|
||||
|
||||
exports.ChannelTypes = {
|
||||
TEXT: 0,
|
||||
DM: 1,
|
||||
|
||||
@@ -1,120 +1,12 @@
|
||||
const { RangeError } = require('../errors');
|
||||
const BitField = require('./BitField');
|
||||
|
||||
/**
|
||||
* Data structure that makes it easy to interact with a permission bitfield. All {@link GuildMember}s have a set of
|
||||
* permissions in their guild, and each channel in the guild may also have {@link PermissionOverwrites} for the member
|
||||
* that override their default permissions.
|
||||
* @extends {BitField}
|
||||
*/
|
||||
class Permissions {
|
||||
/**
|
||||
* @param {PermissionResolvable} permissions Permission(s) to read from
|
||||
*/
|
||||
constructor(permissions) {
|
||||
/**
|
||||
* Bitfield of the packed permissions
|
||||
* @type {number}
|
||||
*/
|
||||
this.bitfield = this.constructor.resolve(permissions);
|
||||
}
|
||||
|
||||
/**
|
||||
* Checks whether the bitfield has a permission, or multiple permissions.
|
||||
* @param {PermissionResolvable} permission Permission(s) to check for
|
||||
* @param {boolean} [checkAdmin=true] Whether to allow the administrator permission to override
|
||||
* @returns {boolean}
|
||||
*/
|
||||
has(permission, checkAdmin = true) {
|
||||
if (permission instanceof Array) return permission.every(p => this.has(p, checkAdmin));
|
||||
permission = this.constructor.resolve(permission);
|
||||
if (checkAdmin && (this.bitfield & this.constructor.FLAGS.ADMINISTRATOR) > 0) return true;
|
||||
return (this.bitfield & permission) === permission;
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets all given permissions that are missing from the bitfield.
|
||||
* @param {PermissionResolvable} permissions Permission(s) to check for
|
||||
* @param {boolean} [checkAdmin=true] Whether to allow the administrator permission to override
|
||||
* @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));
|
||||
}
|
||||
|
||||
/**
|
||||
* Freezes these permissions, making them immutable.
|
||||
* @returns {Permissions} These permissions
|
||||
*/
|
||||
freeze() {
|
||||
return Object.freeze(this);
|
||||
}
|
||||
|
||||
/**
|
||||
* Adds permissions to these ones.
|
||||
* @param {...PermissionResolvable} permissions Permissions to add
|
||||
* @returns {Permissions} These permissions or new permissions if the instance is frozen.
|
||||
*/
|
||||
add(...permissions) {
|
||||
let total = 0;
|
||||
for (let p = permissions.length - 1; p >= 0; p--) {
|
||||
const perm = this.constructor.resolve(permissions[p]);
|
||||
total |= perm;
|
||||
}
|
||||
if (Object.isFrozen(this)) return new this.constructor(this.bitfield | total);
|
||||
this.bitfield |= total;
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Removes permissions from these.
|
||||
* @param {...PermissionResolvable} permissions Permissions to remove
|
||||
* @returns {Permissions} These permissions or new permissions if the instance is frozen.
|
||||
*/
|
||||
remove(...permissions) {
|
||||
let total = 0;
|
||||
for (let p = permissions.length - 1; p >= 0; p--) {
|
||||
const perm = this.constructor.resolve(permissions[p]);
|
||||
total |= perm;
|
||||
}
|
||||
if (Object.isFrozen(this)) return new this.constructor(this.bitfield & ~total);
|
||||
this.bitfield &= ~total;
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets an object mapping permission name (like `VIEW_CHANNEL`) to a {@link boolean} indicating whether the
|
||||
* permission is available.
|
||||
* @param {boolean} [checkAdmin=true] Whether to allow the administrator permission to override
|
||||
* @returns {Object}
|
||||
*/
|
||||
serialize(checkAdmin = true) {
|
||||
const serialized = {};
|
||||
for (const perm in this.constructor.FLAGS) serialized[perm] = this.has(perm, checkAdmin);
|
||||
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));
|
||||
}
|
||||
|
||||
toJSON() {
|
||||
return this.bitfield;
|
||||
}
|
||||
|
||||
valueOf() {
|
||||
return this.bitfield;
|
||||
}
|
||||
|
||||
*[Symbol.iterator]() {
|
||||
const keys = this.toArray();
|
||||
while (keys.length) yield keys.shift();
|
||||
}
|
||||
|
||||
class Permissions extends BitField {
|
||||
/**
|
||||
* Data that can be resolved to give a permission number. This can be:
|
||||
* * A string (see {@link Permissions.FLAGS})
|
||||
@@ -125,16 +17,14 @@ class Permissions {
|
||||
*/
|
||||
|
||||
/**
|
||||
* Resolves permissions to their numeric form.
|
||||
* @param {PermissionResolvable} permission - Permission(s) to resolve
|
||||
* @returns {number}
|
||||
* Checks whether the bitfield has a permission, or multiple permissions.
|
||||
* @param {PermissionResolvable} permission Permission(s) to check for
|
||||
* @param {boolean} [checkAdmin=true] Whether to allow the administrator permission to override
|
||||
* @returns {boolean}
|
||||
*/
|
||||
static resolve(permission) {
|
||||
if (typeof permission === 'number' && permission >= 0) return permission;
|
||||
if (permission instanceof Permissions) return permission.bitfield;
|
||||
if (permission instanceof Array) return permission.map(p => this.resolve(p)).reduce((prev, p) => prev | p, 0);
|
||||
if (typeof permission === 'string') return this.FLAGS[permission];
|
||||
throw new RangeError('PERMISSIONS_INVALID');
|
||||
has(permission, checkAdmin = true) {
|
||||
if (checkAdmin && super.has(this.constructor.FLAGS.ADMINISTRATOR)) return true;
|
||||
return super.has(permission);
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
22
src/util/Speaking.js
Normal file
22
src/util/Speaking.js
Normal file
@@ -0,0 +1,22 @@
|
||||
const BitField = require('./BitField');
|
||||
|
||||
/**
|
||||
* Data structure that makes it easy to interact with a {@link VoiceConnection#speaking}
|
||||
* and {@link guildMemberSpeaking} event bitfields.
|
||||
* @extends {BitField}
|
||||
*/
|
||||
class Speaking extends BitField {}
|
||||
|
||||
/**
|
||||
* Numeric speaking flags. All available properties:
|
||||
* * `SPEAKING`
|
||||
* * `SOUNDSHARE`
|
||||
* @type {Object}
|
||||
* @see {@link https://discordapp.com/developers/docs/topics/voice-connections#speaking}
|
||||
*/
|
||||
Speaking.FLAGS = {
|
||||
SPEAKING: 1 << 0,
|
||||
SOUNDSHARE: 1 << 1,
|
||||
};
|
||||
|
||||
module.exports = Speaking;
|
||||
Reference in New Issue
Block a user