feat(Rest): optional ratelimit errors (#5659)

Co-authored-by: SpaceEEC <spaceeec@yahoo.com>

src/util/Constants.js

@@ -3,6 +3,24 @@
 const Package = (exports.Package = require('../../package.json'));
 const { Error, RangeError } = require('../errors');
 
+/**
+ * Rate limit data
+ * @typedef {Object} RateLimitData
+ * @property {number} timeout Time until this rate limit ends, in ms
+ * @property {number} limit The maximum amount of requests of this endpoint
+ * @property {string} method The http method of this request
+ * @property {string} path The path of the request relative to the HTTP endpoint
+ * @property {string} route The route of the request relative to the HTTP endpoint
+ * @property {boolean} global Whether this is a global rate limit
+ */
+
+/**
+ * Whether this rate limit should throw an Error
+ * @typedef {Function} RateLimitQueueFilter
+ * @param {RateLimitData} rateLimitData The data of this rate limit
+ * @returns {boolean|Promise<boolean>}
+ */
+
 /**
  * Options for a client.
  * @typedef {Object} ClientOptions
@@ -34,6 +52,10 @@ const { Error, RangeError } = require('../errors');
  * (or 0 for never)
  * @property {number} [restGlobalRateLimit=0] How many requests to allow sending per second (0 for unlimited, 50 for
  * the standard global limit used by Discord)
+ * @property {string[]|RateLimitQueueFilter} [rejectOnRateLimit] Decides how rate limits and pre-emptive throttles
+ * should be handled. If this option is an array containing the prefix of the request route (e.g. /channels to match any
+ * route starting with /channels, such as /channels/222197033908436994/messages) or a function returning true, a
+ * {@link RateLimitError} will be thrown. Otherwise the request will be queued for later
  * @property {number} [retryLimit=1] How many times to retry on 5XX errors (Infinity for indefinite amount of retries)
  * @property {PresenceData} [presence={}] Presence data to use upon login
  * @property {IntentsResolvable} intents Intents to enable for this connection