Nomchy/discord.js
1
0
Fork 0
mirror of https://github.com/discordjs/discord.js.git synced 2026-03-10 00:23:30 +01:00
Code Issues Packages Projects Releases Wiki Activity

Increase some documentation detail

Browse Source
This commit is contained in:
Schuyler Cebulskie
2017-02-05 23:00:36 -05:00
parent 26becb570b
commit b859ba7639
3 changed files with 87 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

116
src/client/Client.js
View File

@@ -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<Snowflake, User>}
*/
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<Snowflake, Guild>}
*/
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<Snowflake, Channel>}
*/
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
* <warn>This is only filled when using a user account.</warn>
* @type {Collection<Snowflake, Presence>}
*/
@@ -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
* <warn>This should be kept private at all times.</warn>
* @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<string, VoiceConnection>}
* @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<Snowflake, Emoji>}
* @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. <warn>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.</warn>
* @param {string} token The token used for the account.
* @returns {Promise<string>}
* Logs the client in, establishing a websocket connection to Discord.
* <info>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.</info>
* @param {string} token Token of the account to log in with
* @returns {Promise<string>} 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.
* <info>This can be done automatically every 30 seconds by enabling {@link ClientOptions#sync}.</info>
* <warn>This is only available when using a user account.</warn>
* @param {Guild[]|Collection<Snowflake, Guild>} [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.
* <warn>This is only available when using a bot account.</warn>
* @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<User>}
*/
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<Invite>}
*/
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<Webhook>}
@@ -300,7 +299,7 @@ class Client extends EventEmitter {
}
/**
* Fetch available voice regions
* Obtains the available voice regions from Discord.
* @returns {Collection<string, VoiceRegion>}
*/
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.
* <warn>This is only available when using a bot account.</warn>
* @returns {Promise<ClientOAuth2Application>}
*/
@@ -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<string>} The invite link
* Generates a link that can be used to invite the bot to a guild.
* <warn>This is only available when using a bot account.</warn>
* @param {PermissionResolvable[]|number} [permissions] Permissions to request
* @returns {Promise<string>}
* @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.');

27
src/util/Constants.js
View File

@@ -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,

6
src/util/FetchRecommendedShards.js
View File

@@ -7,7 +7,7 @@ const botGateway = require('./Constants').Endpoints.botGateway;
* @param {number} [guildsPerShard=1000] Number of guilds per shard
* @returns {Promise<number>} 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;