discord-sb.js 1.0.0

package/src/util/DataResolver.js

@@ -0,0 +1,146 @@
+'use strict';
+
+const { Buffer } = require('node:buffer');
+const fs = require('node:fs');
+const path = require('node:path');
+const stream = require('node:stream');
+const { fetch } = require('undici');
+const { Error: DiscordError, TypeError } = require('../errors');
+const Invite = require('../structures/Invite');
+
+/**
+ * The DataResolver identifies different objects and tries to resolve a specific piece of information from them.
+ * @private
+ */
+class DataResolver extends null {
+  /**
+   * Data that can be resolved to give an invite code. This can be:
+   * * An invite code
+   * * An invite URL
+   * @typedef {string} InviteResolvable
+   */
+
+  /**
+   * Data that can be resolved to give a template code. This can be:
+   * * A template code
+   * * A template URL
+   * @typedef {string} GuildTemplateResolvable
+   */
+
+  /**
+   * Resolves the string to a code based on the passed regex.
+   * @param {string} data The string to resolve
+   * @param {RegExp} regex The RegExp used to extract the code
+   * @returns {string}
+   */
+  static resolveCode(data, regex) {
+    return new RegExp(regex.source).exec(data)?.[1] ?? data;
+  }
+
+  /**
+   * Resolves InviteResolvable to an invite code.
+   * @param {InviteResolvable} data The invite resolvable to resolve
+   * @returns {string}
+   */
+  static resolveInviteCode(data) {
+    return this.resolveCode(data, Invite.INVITES_PATTERN);
+  }
+
+  /**
+   * Resolves GuildTemplateResolvable to a template code.
+   * @param {GuildTemplateResolvable} data The template resolvable to resolve
+   * @returns {string}
+   */
+  static resolveGuildTemplateCode(data) {
+    const GuildTemplate = require('../structures/GuildTemplate');
+    return this.resolveCode(data, GuildTemplate.GUILD_TEMPLATES_PATTERN);
+  }
+
+  /**
+   * Resolves a Base64Resolvable, a string, or a BufferResolvable to a Base 64 image.
+   * @param {BufferResolvable|Base64Resolvable} image The image to be resolved
+   * @returns {Promise<?string>}
+   */
+  static async resolveImage(image) {
+    if (!image) return null;
+    if (typeof image === 'string' && image.startsWith('data:')) {
+      return image;
+    }
+    const file = await this.resolveFileAsBuffer(image);
+    return DataResolver.resolveBase64(file);
+  }
+
+  /**
+   * Data that resolves to give a Base64 string, typically for image uploading. This can be:
+   * * A Buffer
+   * * A base64 string
+   * @typedef {Buffer|string} Base64Resolvable
+   */
+
+  /**
+   * Resolves a Base64Resolvable to a Base 64 image.
+   * @param {Base64Resolvable} data The base 64 resolvable you want to resolve
+   * @returns {?string}
+   */
+  static resolveBase64(data) {
+    if (Buffer.isBuffer(data)) return `data:image/jpg;base64,${data.toString('base64')}`;
+    return data;
+  }
+
+  /**
+   * Data that can be resolved to give a Buffer. This can be:
+   * * A Buffer
+   * * The path to a local file
+   * * A URL <warn>When provided a URL, discord.js will fetch the URL internally in order to create a Buffer.
+   * This can pose a security risk when the URL has not been sanitized</warn>
+   * @typedef {string|Buffer} BufferResolvable
+   */
+
+  /**
+   * @external Stream
+   * @see {@link https://nodejs.org/api/stream.html}
+   */
+
+  /**
+   * Resolves a BufferResolvable to a Buffer or a Stream.
+   * @param {BufferResolvable|Stream} resource The buffer or stream resolvable to resolve
+   * @returns {Promise<Buffer|Stream>}
+   */
+  static async resolveFile(resource) {
+    if (Buffer.isBuffer(resource) || resource instanceof stream.Readable) return resource;
+    if (typeof resource === 'string') {
+      if (/^https?:\/\//.test(resource)) {
+        const res = await fetch(resource);
+        if (res.ok) return res.body;
+        else throw new DiscordError('FILE_NOT_FOUND', resource);
+      }
+
+      return new Promise((resolve, reject) => {
+        const file = path.resolve(resource);
+        fs.stat(file, (err, stats) => {
+          if (err) return reject(err);
+          if (!stats.isFile()) return reject(new DiscordError('FILE_NOT_FOUND', file));
+          return resolve(fs.createReadStream(file));
+        });
+      });
+    }
+
+    throw new TypeError('REQ_RESOURCE_TYPE');
+  }
+
+  /**
+   * Resolves a BufferResolvable to a Buffer.
+   * @param {BufferResolvable|Stream} resource The buffer or stream resolvable to resolve
+   * @returns {Promise<Buffer>}
+   */
+  static async resolveFileAsBuffer(resource) {
+    const file = await this.resolveFile(resource);
+    if (Buffer.isBuffer(file)) return file;
+
+    const buffers = [];
+    for await (const data of file) buffers.push(data);
+    return Buffer.concat(buffers);
+  }
+}
+
+module.exports = DataResolver;

package/src/util/Formatters.js

@@ -0,0 +1,228 @@
+'use strict';
+
+const {
+  blockQuote,
+  bold,
+  channelMention,
+  codeBlock,
+  formatEmoji,
+  hideLinkEmbed,
+  hyperlink,
+  inlineCode,
+  italic,
+  quote,
+  roleMention,
+  spoiler,
+  strikethrough,
+  time,
+  TimestampStyles,
+  underscore,
+  userMention,
+} = require('@discordjs/builders');
+
+/**
+ * Contains various Discord-specific functions for formatting messages.
+ */
+class Formatters extends null {}
+
+/**
+ * Formats the content into a block quote. This needs to be at the start of the line for Discord to format it.
+ * @method blockQuote
+ * @memberof Formatters
+ * @param {string} content The content to wrap.
+ * @returns {string}
+ */
+Formatters.blockQuote = blockQuote;
+
+/**
+ * Formats the content into bold text.
+ * @method bold
+ * @memberof Formatters
+ * @param {string} content The content to wrap.
+ * @returns {string}
+ */
+Formatters.bold = bold;
+
+/**
+ * Formats a channel id into a channel mention.
+ * @method channelMention
+ * @memberof Formatters
+ * @param {string} channelId The channel id to format.
+ * @returns {string}
+ */
+Formatters.channelMention = channelMention;
+
+/**
+ * Formats an application command name, subcommand group name, subcommand name, and ID
+ * into an application command mention
+ * @method chatInputApplicationCommandMention
+ * @memberof Formatters
+ * @param {string} commandName The name of the application command
+ * @param {string|Snowflake} subcommandGroupOrSubOrId
+ * The subcommand group name, subcommand name, or application command id
+ * @param {?(string|Snowflake)} [subcommandNameOrId] The subcommand name or application command id
+ * @param {?Snowflake} [commandId] The id of the application command
+ * @returns {string}
+ * @static
+ */
+Formatters.chatInputApplicationCommandMention = function chatInputApplicationCommandMention(
+  commandName,
+  subcommandGroupOrSubOrId,
+  subcommandNameOrId,
+  commandId,
+) {
+  if (typeof commandId !== 'undefined') {
+    return `</${commandName} ${subcommandGroupOrSubOrId} ${subcommandNameOrId}:${commandId}>`;
+  }
+
+  if (typeof subcommandNameOrId !== 'undefined') {
+    return `</${commandName} ${subcommandGroupOrSubOrId}:${subcommandNameOrId}>`;
+  }
+
+  return `</${commandName}:${subcommandGroupOrSubOrId}>`;
+};
+
+/**
+ * Wraps the content inside a code block with an optional language.
+ * @method codeBlock
+ * @memberof Formatters
+ * @param {string} contentOrLanguage The language to use, content if a second parameter isn't provided.
+ * @param {string} [content] The content to wrap.
+ * @returns {string}
+ */
+Formatters.codeBlock = codeBlock;
+
+/**
+ * Formats an emoji id into a fully qualified emoji identifier
+ * @method formatEmoji
+ * @memberof Formatters
+ * @param {string} emojiId The emoji id to format.
+ * @param {boolean} [animated] Whether the emoji is animated or not. Defaults to `false`
+ * @returns {string}
+ */
+Formatters.formatEmoji = formatEmoji;
+
+/**
+ * Wraps the URL into `<>`, which stops it from embedding.
+ * @method hideLinkEmbed
+ * @memberof Formatters
+ * @param {string} content The content to wrap.
+ * @returns {string}
+ */
+Formatters.hideLinkEmbed = hideLinkEmbed;
+
+/**
+ * Formats the content and the URL into a masked URL with an optional title.
+ * @method hyperlink
+ * @memberof Formatters
+ * @param {string} content The content to display.
+ * @param {string} url The URL the content links to.
+ * @param {string} [title] The title shown when hovering on the masked link.
+ * @returns {string}
+ */
+Formatters.hyperlink = hyperlink;
+
+/**
+ * Wraps the content inside \`backticks\`, which formats it as inline code.
+ * @method inlineCode
+ * @memberof Formatters
+ * @param {string} content The content to wrap.
+ * @returns {string}
+ */
+Formatters.inlineCode = inlineCode;
+
+/**
+ * Formats the content into italic text.
+ * @method italic
+ * @memberof Formatters
+ * @param {string} content The content to wrap.
+ * @returns {string}
+ */
+Formatters.italic = italic;
+
+/**
+ * Formats the content into a quote. This needs to be at the start of the line for Discord to format it.
+ * @method quote
+ * @memberof Formatters
+ * @param {string} content The content to wrap.
+ * @returns {string}
+ */
+Formatters.quote = quote;
+
+/**
+ * Formats a role id into a role mention.
+ * @method roleMention
+ * @memberof Formatters
+ * @param {string} roleId The role id to format.
+ * @returns {string}
+ */
+Formatters.roleMention = roleMention;
+
+/**
+ * Formats the content into spoiler text.
+ * @method spoiler
+ * @memberof Formatters
+ * @param {string} content The content to spoiler.
+ * @returns {string}
+ */
+Formatters.spoiler = spoiler;
+
+/**
+ * Formats the content into strike-through text.
+ * @method strikethrough
+ * @memberof Formatters
+ * @param {string} content The content to wrap.
+ * @returns {string}
+ */
+Formatters.strikethrough = strikethrough;
+
+/**
+ * Formats a date into a short date-time string.
+ * @method time
+ * @memberof Formatters
+ * @param {number|Date} [date] The date to format.
+ * @param {TimestampStylesString} [style] The style to use.
+ * @returns {string}
+ */
+Formatters.time = time;
+
+/**
+ * A message formatting timestamp style, as defined in
+ * [here](https://discord.com/developers/docs/reference#message-formatting-timestamp-styles).
+ * * `t` Short time format, consisting of hours and minutes, e.g. 16:20.
+ * * `T` Long time format, consisting of hours, minutes, and seconds, e.g. 16:20:30.
+ * * `d` Short date format, consisting of day, month, and year, e.g. 20/04/2021.
+ * * `D` Long date format, consisting of day, month, and year, e.g. 20 April 2021.
+ * * `f` Short date-time format, consisting of short date and short time formats, e.g. 20 April 2021 16:20.
+ * * `F` Long date-time format, consisting of long date and short time formats, e.g. Tuesday, 20 April 2021 16:20.
+ * * `R` Relative time format, consisting of a relative duration format, e.g. 2 months ago.
+ * @typedef {string} TimestampStylesString
+ */
+
+/**
+ * The message formatting timestamp
+ * [styles](https://discord.com/developers/docs/reference#message-formatting-timestamp-styles) supported by Discord.
+ * @memberof Formatters
+ * @type {Object<string, TimestampStylesString>}
+ */
+Formatters.TimestampStyles = TimestampStyles;
+
+/**
+ * Formats the content into underscored text.
+ * @method underscore
+ * @memberof Formatters
+ * @param {string} content The content to wrap.
+ * @returns {string}
+ */
+Formatters.underscore = underscore;
+
+/**
+ * Formats a user id into a user mention.
+ * @method userMention
+ * @memberof Formatters
+ * @param {string} userId The user id to format.
+ * @returns {string}
+ */
+Formatters.userMention = userMention;
+
+module.exports = Formatters;

package/src/util/GuildMemberFlags.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const BitField = require('./BitField');
+
+/**
+ * Data structure that makes it easy to interact with an {@link GuildMember#flags} bitfield.
+ * @extends {BitField}
+ */
+class GuildMemberFlags extends BitField {}
+
+/**
+ * @name GuildMemberFlags
+ * @kind constructor
+ * @memberof GuildMemberFlags
+ * @param {BitFieldResolvable} [bits=0] Bit(s) to read from
+ */
+
+/**
+ * Numeric guild member flags. All available properties:
+ * * `DID_REJOIN`
+ * * `COMPLETED_ONBOARDING`
+ * * `BYPASSES_VERIFICATION`
+ * * `STARTED_ONBOARDING`
+ * @type {Object}
+ * @see {@link https://discord.com/developers/docs/resources/guild#guild-member-object-guild-member-flags}
+ */
+GuildMemberFlags.FLAGS = {
+  DID_REJOIN: 1 << 0,
+  COMPLETED_ONBOARDING: 1 << 1,
+  BYPASSES_VERIFICATION: 1 << 2,
+  STARTED_ONBOARDING: 1 << 3,
+};
+
+/**
+ * Data that can be resolved to give a guild member flag bitfield. This can be:
+ * * A string (see {@link GuildMemberFlags.FLAGS})
+ * * A guild member flag
+ * * An instance of GuildMemberFlags
+ * * An Array of GuildMemberFlagsResolvable
+ * @typedef {string|number|GuildMemberFlags|GuildMemberFlagsResolvable[]} GuildMemberFlagsResolvable
+ */
+
+module.exports = GuildMemberFlags;

package/src/util/Intents.js

@@ -0,0 +1,74 @@
+'use strict';
+const BitField = require('./BitField');
+
+/**
+ * Data structure that makes it easy to calculate intents.
+ * @extends {BitField}
+ */
+class Intents extends BitField {}
+
+/**
+ * @name Intents
+ * @kind constructor
+ * @memberof Intents
+ * @param {IntentsResolvable} [bits=0] Bit(s) to read from
+ */
+
+/**
+ * Data that can be resolved to give a permission number. This can be:
+ * * A string (see {@link Intents.FLAGS})
+ * * An intents flag
+ * * An instance of Intents
+ * * An array of IntentsResolvable
+ * @typedef {string|number|Intents|IntentsResolvable[]} IntentsResolvable
+ */
+
+/**
+ * Numeric WebSocket intents. All available properties:
+ * * `GUILDS`
+ * * `GUILD_MEMBERS`
+ * * `GUILD_BANS`
+ * * `GUILD_EMOJIS_AND_STICKERS`
+ * * `GUILD_INTEGRATIONS`
+ * * `GUILD_WEBHOOKS`
+ * * `GUILD_INVITES`
+ * * `GUILD_VOICE_STATES`
+ * * `GUILD_PRESENCES`
+ * * `GUILD_MESSAGES`
+ * * `GUILD_MESSAGE_REACTIONS`
+ * * `GUILD_MESSAGE_TYPING`
+ * * `DIRECT_MESSAGES`
+ * * `DIRECT_MESSAGE_REACTIONS`
+ * * `DIRECT_MESSAGE_TYPING`
+ * * `MESSAGE_CONTENT`
+ * * `GUILD_SCHEDULED_EVENTS`
+ * * `AUTO_MODERATION_CONFIGURATION`
+ * * `AUTO_MODERATION_EXECUTION`
+ * @type {Object}
+ * @see {@link https://discord.com/developers/docs/topics/gateway#list-of-intents}
+ */
+Intents.FLAGS = {
+  GUILDS: 1 << 0,
+  GUILD_MEMBERS: 1 << 1,
+  GUILD_BANS: 1 << 2,
+  GUILD_EMOJIS_AND_STICKERS: 1 << 3,
+  GUILD_INTEGRATIONS: 1 << 4,
+  GUILD_WEBHOOKS: 1 << 5,
+  GUILD_INVITES: 1 << 6,
+  GUILD_VOICE_STATES: 1 << 7,
+  GUILD_PRESENCES: 1 << 8,
+  GUILD_MESSAGES: 1 << 9,
+  GUILD_MESSAGE_REACTIONS: 1 << 10,
+  GUILD_MESSAGE_TYPING: 1 << 11,
+  DIRECT_MESSAGES: 1 << 12,
+  DIRECT_MESSAGE_REACTIONS: 1 << 13,
+  DIRECT_MESSAGE_TYPING: 1 << 14,
+  MESSAGE_CONTENT: 1 << 15,
+  GUILD_SCHEDULED_EVENTS: 1 << 16,
+  AUTO_MODERATION_CONFIGURATION: 1 << 20,
+  AUTO_MODERATION_EXECUTION: 1 << 21,
+};
+
+Intents.ALL = Object.values(Intents.FLAGS).reduce((all, p) => all | p, 0);
+
+module.exports = Intents;

package/src/util/InviteFlags.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const BitField = require('./BitField');
+
+/**
+ * Data structure that makes it easy to interact with an {@link InviteFlags#flags} bitfield.
+ * @extends {BitField}
+ */
+class InviteFlags extends BitField {}
+
+/**
+ * @name InviteFlags
+ * @kind constructor
+ * @memberof InviteFlags
+ * @param {BitFieldResolvable} [bits=0] Bit(s) to read from
+ */
+
+/**
+ * Numeric the Discord invite flags. All available properties:
+ * * `IS_GUEST_INVITE`
+ * * `IS_VIEWED`
+ * * `IS_ENHANCED`
+ * * `IS_APPLICATION_BYPASS`
+ * @type {Object}
+ * @see {@link https://docs.discord.food/resources/invite#invite-flags}
+ */
+InviteFlags.FLAGS = {
+  IS_GUEST_INVITE: 1 << 0,
+  IS_VIEWED: 1 << 1,
+  IS_ENHANCED: 1 << 2,
+  IS_APPLICATION_BYPASS: 1 << 3,
+};
+
+module.exports = InviteFlags;

package/src/util/LimitedCollection.js

@@ -0,0 +1,131 @@
+'use strict';
+
+const { setInterval } = require('node:timers');
+const { Collection } = require('@discordjs/collection');
+const { _cleanupSymbol } = require('./Constants.js');
+const Sweepers = require('./Sweepers.js');
+const { TypeError } = require('../errors/DJSError.js');
+
+/**
+ * @typedef {Function} SweepFilter
+ * @param {LimitedCollection} collection The collection being swept
+ * @returns {Function|null} Return `null` to skip sweeping, otherwise a function passed to `sweep()`,
+ * See {@link [Collection#sweep](https://discord.js.org/docs/packages/collection/stable/Collection:Class#sweep)}
+ * for the definition of this function.
+ */
+
+/**
+ * Options for defining the behavior of a LimitedCollection
+ * @typedef {Object} LimitedCollectionOptions
+ * @property {?number} [maxSize=Infinity] The maximum size of the Collection
+ * @property {?Function} [keepOverLimit=null] A function, which is passed the value and key of an entry, ran to decide
+ * to keep an entry past the maximum size
+ * @property {?SweepFilter} [sweepFilter=null] DEPRECATED: There is no direct alternative to this,
+ * however most of its purpose is fulfilled by {@link Client#sweepers}
+ * A function ran every `sweepInterval` to determine how to sweep
+ * @property {?number} [sweepInterval=0] DEPRECATED: There is no direct alternative to this,
+ * however most of its purpose is fulfilled by {@link Client#sweepers}
+ * How frequently, in seconds, to sweep the collection.
+ */
+
+/**
+ * A Collection which holds a max amount of entries and sweeps periodically.
+ * @extends {Collection}
+ * @param {LimitedCollectionOptions} [options={}] Options for constructing the Collection.
+ * @param {Iterable} [iterable=null] Optional entries passed to the Map constructor.
+ */
+class LimitedCollection extends Collection {
+  constructor(options = {}, iterable) {
+    if (typeof options !== 'object' || options === null) {
+      throw new TypeError('INVALID_TYPE', 'options', 'object', true);
+    }
+    const { maxSize = Infinity, keepOverLimit = null, sweepInterval = 0, sweepFilter = null } = options;
+
+    if (typeof maxSize !== 'number') {
+      throw new TypeError('INVALID_TYPE', 'maxSize', 'number');
+    }
+    if (keepOverLimit !== null && typeof keepOverLimit !== 'function') {
+      throw new TypeError('INVALID_TYPE', 'keepOverLimit', 'function');
+    }
+    if (typeof sweepInterval !== 'number') {
+      throw new TypeError('INVALID_TYPE', 'sweepInterval', 'number');
+    }
+    if (sweepFilter !== null && typeof sweepFilter !== 'function') {
+      throw new TypeError('INVALID_TYPE', 'sweepFilter', 'function');
+    }
+
+    super(iterable);
+
+    /**
+     * The max size of the Collection.
+     * @type {number}
+     */
+    this.maxSize = maxSize;
+
+    /**
+     * A function called to check if an entry should be kept when the Collection is at max size.
+     * @type {?Function}
+     */
+    this.keepOverLimit = keepOverLimit;
+
+    /**
+     * A function called every sweep interval that returns a function passed to `sweep`.
+     * @deprecated in favor of {@link Client#sweepers}
+     * @type {?SweepFilter}
+     */
+    this.sweepFilter = sweepFilter;
+
+    /**
+     * The id of the interval being used to sweep.
+     * @deprecated in favor of {@link Client#sweepers}
+     * @type {?Timeout}
+     */
+    this.interval =
+      sweepInterval > 0 && sweepInterval !== Infinity && sweepFilter
+        ? setInterval(() => {
+            const sweepFn = this.sweepFilter(this);
+            if (sweepFn === null) return;
+            if (typeof sweepFn !== 'function') throw new TypeError('SWEEP_FILTER_RETURN');
+            this.sweep(sweepFn);
+          }, sweepInterval * 1_000).unref()
+        : null;
+  }
+
+  set(key, value) {
+    if (this.maxSize === 0) return this;
+    if (this.size >= this.maxSize && !this.has(key)) {
+      for (const [k, v] of this.entries()) {
+        const keep = this.keepOverLimit?.(v, k, this) ?? false;
+        if (!keep) {
+          this.delete(k);
+          break;
+        }
+      }
+    }
+    return super.set(key, value);
+  }
+
+  /**
+   * Create a sweepFilter function that uses a lifetime to determine sweepability.
+   * @param {LifetimeFilterOptions} [options={}] The options used to generate the filter function
+   * @deprecated Use {@link Sweepers.filterByLifetime} instead
+   * @returns {SweepFilter}
+   */
+  static filterByLifetime({
+    lifetime = 14400,
+    getComparisonTimestamp = e => e?.createdTimestamp,
+    excludeFromSweep = () => false,
+  } = {}) {
+    return Sweepers.filterByLifetime({ lifetime, getComparisonTimestamp, excludeFromSweep });
+  }
+
+  [_cleanupSymbol]() {
+    return this.interval ? () => clearInterval(this.interval) : null;
+  }
+
+  static get [Symbol.species]() {
+    return Collection;
+  }
+}
+
+module.exports = LimitedCollection;