diff --git a/src/client/Client.js b/src/client/Client.js index 90fae09ff..06b777951 100644 --- a/src/client/Client.js +++ b/src/client/Client.js @@ -14,7 +14,7 @@ const Presence = require('../structures/Presence').Presence; const ShardClientUtil = require('../sharding/ShardClientUtil'); /** - * The starting point for making a Discord Bot. + * The main hub for interacting with the Discord API, and the starting point for any bot. * @extends {EventEmitter} */ class Client extends EventEmitter { @@ -85,31 +85,34 @@ class Client extends EventEmitter { this.voice = !this.browser ? new ClientVoiceManager(this) : null; /** - * The shard helpers for the client (only if the process was spawned as a child, such as from a ShardingManager) + * The shard helpers for the client + * (only if the process was spawned as a child, such as from a {@link ShardingManager}) * @type {?ShardClientUtil} */ this.shard = process.send ? ShardClientUtil.singleton(this) : null; /** - * A collection of the Client's stored users + * All of the {@link User} objects that have been cached at any point, mapped by their IDs * @type {Collection} */ this.users = new Collection(); /** - * A collection of the Client's stored guilds + * All of the guilds the client is currently handling, mapped by their IDs - + * as long as sharding isn't being used, this will be *every* guild the bot is a member of * @type {Collection} */ this.guilds = new Collection(); /** - * A collection of the Client's stored channels + * All of the {@link Channel}s that the client is currently handling, mapped by their IDs - + * as long as sharding isn't being used, this will be *every* channel in *every* guild, and all DM channels * @type {Collection} */ this.channels = new Collection(); /** - * A collection of presences for friends of the logged in user. + * Presences that have been received for the client user's friends, mapped by user IDs * This is only filled when using a user account. * @type {Collection} */ @@ -117,7 +120,8 @@ class Client extends EventEmitter { if (!this.token && 'CLIENT_TOKEN' in process.env) { /** - * The authorization token for the logged in user/bot. + * Authorization token for the logged in user/bot + * This should be kept private at all times. * @type {?string} */ this.token = process.env.CLIENT_TOKEN; @@ -126,19 +130,20 @@ class Client extends EventEmitter { } /** - * The ClientUser representing the logged in Client + * User that the client is logged in as * @type {?ClientUser} */ this.user = null; /** - * The date at which the Client was regarded as being in the `READY` state. + * Time at which the client was last regarded as being in the `READY` state + * (each time the client disconnects and successfully reconnects, this will be overwritten) * @type {?Date} */ this.readyAt = null; /** - * The previous heartbeat pings of the websocket (most recent first, limited to three elements) + * Previous heartbeat pings of the websocket (most recent first, limited to three elements) * @type {number[]} */ this.pings = []; @@ -153,7 +158,7 @@ class Client extends EventEmitter { } /** - * The status for the logged in Client. + * Current status of the client's connection to Discord * @type {?number} * @readonly */ @@ -162,7 +167,7 @@ class Client extends EventEmitter { } /** - * The uptime for the logged in Client. + * How long it has been since the client last entered the `READY` state * @type {?number} * @readonly */ @@ -171,7 +176,7 @@ class Client extends EventEmitter { } /** - * The average heartbeat ping of the websocket + * Average heartbeat ping of the websocket, obtained by averaging the {@link Client#pings} property * @type {number} * @readonly */ @@ -180,7 +185,7 @@ class Client extends EventEmitter { } /** - * Returns a collection, mapping guild ID to voice connections. + * All active voice connections that have been established, mapped by channel ID * @type {Collection} * @readonly */ @@ -190,7 +195,7 @@ class Client extends EventEmitter { } /** - * The emojis that the client can use. Mapped by emoji ID. + * All custom emojis that the client has access to, mapped by their IDs * @type {Collection} * @readonly */ @@ -203,7 +208,7 @@ class Client extends EventEmitter { } /** - * The timestamp that the client was last ready at + * Timestamp of the time the client was last `READY` at * @type {?number} * @readonly */ @@ -221,28 +226,22 @@ class Client extends EventEmitter { } /** - * Logs the client in. If successful, resolves with the account's token. If you're making a bot, it's - * much better to use a bot account rather than a user account. - * Bot accounts have higher rate limits and have access to some features user accounts don't have. User bots - * that are making a lot of API requests can even be banned. - * @param {string} token The token used for the account. - * @returns {Promise} + * Logs the client in, establishing a websocket connection to Discord. + * Both bot and regular user accounts are supported, but it is highly recommended to use a bot account whenever + * possible. User accounts are subject to harsher ratelimits and other restrictions that don't apply to bot accounts. + * Bot accounts also have access to many features that user accounts cannot utilise. User accounts that are found to + * be abusing/overusing the API will be banned, locking you out of Discord entirely. + * @param {string} token Token of the account to log in with + * @returns {Promise} Token of the account used * @example - * // log the client in using a token - * const token = 'my token'; - * client.login(token); - * @example - * // log the client in using email and password - * const email = 'user@email.com'; - * const password = 'supersecret123'; - * client.login(email, password); + * client.login('my token'); */ login(token) { return this.rest.methods.login(token); } /** - * Destroys the client and logs out. + * Logs out, terminates the connection to Discord, and destroys the client * @returns {Promise} */ destroy() { @@ -254,8 +253,8 @@ class Client extends EventEmitter { } /** - * This shouldn't really be necessary to most developers as it is automatically invoked every 30 seconds, however - * if you wish to force a sync of guild data, you can use this. + * Requests a sync of guild data with Discord. + * This can be done automatically every 30 seconds by enabling {@link ClientOptions#sync}. * This is only available when using a user account. * @param {Guild[]|Collection} [guilds=this.guilds] An array or collection of guilds to sync */ @@ -268,10 +267,10 @@ class Client extends EventEmitter { } /** - * Caches a user, or obtains it from the cache if it's already cached. + * Obtains a user from Discord, or the user cache if it's already available. * This is only available when using a bot account. - * @param {string} id The ID of the user to obtain - * @param {boolean} [cache=true] Insert the user into the users cache + * @param {string} id ID of the user + * @param {boolean} [cache=true] Whether to cache the new user object if it isn't already * @returns {Promise} */ fetchUser(id, cache = true) { @@ -280,8 +279,8 @@ class Client extends EventEmitter { } /** - * Fetches an invite object from an invite code. - * @param {InviteResolvable} invite An invite code or URL + * Obtains an invite from Discord. + * @param {InviteResolvable} invite Invite code or URL * @returns {Promise} */ fetchInvite(invite) { @@ -290,7 +289,7 @@ class Client extends EventEmitter { } /** - * Fetch a webhook by ID. + * Obtains a webhook from Discord. * @param {string} id ID of the webhook * @param {string} [token] Token for the webhook * @returns {Promise} @@ -300,7 +299,7 @@ class Client extends EventEmitter { } /** - * Fetch available voice regions + * Obtains the available voice regions from Discord. * @returns {Collection} */ fetchVoiceRegions() { @@ -308,10 +307,10 @@ class Client extends EventEmitter { } /** - * Sweeps all channels' messages and removes the ones older than the max message lifetime. + * Sweeps all text-based channels' messages and removes the ones older than the max message lifetime. * If the message has been edited, the time of the edit is used rather than the time of the original message. * @param {number} [lifetime=this.options.messageCacheLifetime] Messages that are older than this (in seconds) - * will be removed from the caches. The default is based on the client's `messageCacheLifetime` option. + * will be removed from the caches. The default is based on {@link ClientOptions#messageCacheLifetime}. * @returns {number} Amount of messages that were removed from the caches, * or -1 if the message cache lifetime is unlimited */ @@ -344,7 +343,7 @@ class Client extends EventEmitter { } /** - * Gets the bot's OAuth2 application. + * Obtains the OAuth Application of the bot from Discord. * This is only available when using a bot account. * @returns {Promise} */ @@ -354,9 +353,10 @@ class Client extends EventEmitter { } /** - * Generate an invite link for your bot - * @param {PermissionResolvable[]|number} [permissions] An array of permissions to request - * @returns {Promise} The invite link + * Generates a link that can be used to invite the bot to a guild. + * This is only available when using a bot account. + * @param {PermissionResolvable[]|number} [permissions] Permissions to request + * @returns {Promise} * @example * client.generateInvite(['SEND_MESSAGES', 'MANAGE_GUILD', 'MENTION_EVERYONE']) * .then(link => { @@ -421,24 +421,46 @@ class Client extends EventEmitter { this._intervals.delete(interval); } + /** + * Adds a ping to {@link Client#pings}. + * @param {number} startTime Starting time of the ping + * @private + */ _pong(startTime) { this.pings.unshift(Date.now() - startTime); if (this.pings.length > 3) this.pings.length = 3; this.ws.lastHeartbeatAck = true; } + /** + * Adds/updates a friend's presence in {@link Client#presences}. + * @param {string} id ID of the user + * @param {Object} presence Raw presence object from Discord + * @private + */ _setPresence(id, presence) { - if (this.presences.get(id)) { + if (this.presences.has(id)) { this.presences.get(id).update(presence); return; } this.presences.set(id, new Presence(presence)); } + /** + * Calls `eval(script)` with the client as `this`. + * @param {string} script Script to eval + * @returns {*} + * @private + */ _eval(script) { return eval(script); } + /** + * Validates client options + * @param {ClientOptions} [options=this.options] Options to validate + * @private + */ _validateOptions(options = this.options) { if (typeof options.shardCount !== 'number' || isNaN(options.shardCount)) { throw new TypeError('The shardCount option must be a number.'); diff --git a/src/util/Constants.js b/src/util/Constants.js index 130ede43f..df1c7b227 100644 --- a/src/util/Constants.js +++ b/src/util/Constants.js @@ -3,24 +3,25 @@ exports.Package = require('../../package.json'); /** * Options for a Client. * @typedef {Object} ClientOptions - * @property {string} [apiRequestMethod='sequential'] 'sequential' or 'burst'. Sequential executes all requests in - * the order they are triggered, whereas burst runs multiple at a time, and doesn't guarantee a particular order. - * @property {number} [shardId=0] The ID of this shard - * @property {number} [shardCount=0] The number of shards + * @property {string} [apiRequestMethod='sequential'] One of `sequential` or `burst`. The sequential handler executes + * all requests in the order they are triggered, whereas the burst handler runs multiple in parallel, and doesn't + * provide the guarantee of any particular order. + * @property {number} [shardId=0] ID of the shard to run + * @property {number} [shardCount=0] Total number of shards * @property {number} [messageCacheMaxSize=200] Maximum number of messages to cache per channel * (-1 or Infinity for unlimited - don't do this without message sweeping, otherwise memory usage will climb * indefinitely) - * @property {number} [messageCacheLifetime=0] How long until a message should be uncached by the message sweeping - * (in seconds, 0 for forever) + * @property {number} [messageCacheLifetime=0] How long a message should stay in the cache until it is considered + * sweepable (in seconds, 0 for forever) * @property {number} [messageSweepInterval=0] How frequently to remove messages from the cache that are older than * the message cache lifetime (in seconds, 0 for never) * @property {boolean} [fetchAllMembers=false] Whether to cache all guild members and users upon startup, as well as - * upon joining a guild - * @property {boolean} [disableEveryone=false] Default value for MessageOptions.disableEveryone - * @property {boolean} [sync=false] Whether to periodically sync guilds (for userbots) + * upon joining a guild (should be avoided whenever possible) + * @property {boolean} [disableEveryone=false] Default value for {@link MessageOptions#disableEveryone} + * @property {boolean} [sync=false] Whether to periodically sync guilds (for user accounts) * @property {number} [restWsBridgeTimeout=5000] Maximum time permitted between REST responses and their * corresponding websocket events - * @property {number} [restTimeOffset=500] The extra time in millseconds to wait before continuing to make REST + * @property {number} [restTimeOffset=500] Extra time in millseconds to wait before continuing to make REST * requests (higher values will reduce rate-limiting errors on bad connections) * @property {WSEventType[]} [disabledEvents] An array of disabled websocket events. Events in this array will not be * processed, potentially resulting in performance improvements for larger bots. Only disable events you are @@ -43,11 +44,11 @@ exports.DefaultOptions = { restTimeOffset: 500, /** - * Websocket options. These are left as snake_case to match the API. + * Websocket options (these are left as snake_case to match the API) * @typedef {Object} WebsocketOptions * @property {number} [large_threshold=250] Number of members in a guild to be considered large - * @property {boolean} [compress=true] Whether to compress data sent on the connection. - * Defaults to `false` for browsers. + * @property {boolean} [compress=true] Whether to compress data sent on the connection + * (defaults to `false` for browsers) */ ws: { large_threshold: 250, diff --git a/src/util/FetchRecommendedShards.js b/src/util/FetchRecommendedShards.js index 217009077..aa8514f27 100644 --- a/src/util/FetchRecommendedShards.js +++ b/src/util/FetchRecommendedShards.js @@ -7,7 +7,7 @@ const botGateway = require('./Constants').Endpoints.botGateway; * @param {number} [guildsPerShard=1000] Number of guilds per shard * @returns {Promise} the recommended number of shards */ -module.exports = function fetchRecommendedShards(token, guildsPerShard = 1000) { +function fetchRecommendedShards(token, guildsPerShard = 1000) { return new Promise((resolve, reject) => { if (!token) throw new Error('A token must be provided.'); superagent.get(botGateway) @@ -17,4 +17,6 @@ module.exports = function fetchRecommendedShards(token, guildsPerShard = 1000) { resolve(res.body.shards * (1000 / guildsPerShard)); }); }); -}; +} + +module.exports = fetchRecommendedShards;