refactor(attachment): don't return attachment builders from API (#7852)

Co-authored-by: Almeida <[email protected]>
Co-authored-by: A. Román <[email protected]>
Co-authored-by: SpaceEEC <[email protected]>

Author: 4 people

packages/discord.js/src/index.js

@@ -123,6 +123,7 @@ exports.InviteStageInstance = require('./structures/InviteStageInstance');
 exports.InviteGuild = require('./structures/InviteGuild');
 exports.Message = require('./structures/Message').Message;
 exports.Attachment = require('./structures/Attachment');
+exports.AttachmentBuilder = require('./structures/AttachmentBuilder');
 exports.ModalBuilder = require('./structures/ModalBuilder');
 exports.MessageCollector = require('./structures/MessageCollector');
 exports.MessageComponentInteraction = require('./structures/MessageComponentInteraction');

packages/discord.js/src/managers/GuildStickerManager.js

@@ -41,7 +41,7 @@ class GuildStickerManager extends CachedManager {
 
   /**
    * Creates a new custom sticker in the guild.
-   * @param {BufferResolvable|Stream|FileOptions|Attachment} file The file for the sticker
+   * @param {BufferResolvable|Stream|JSONEncodable<AttachmentPayload>} file The file for the sticker
    * @param {string} name The name for the sticker
    * @param {string} tags The Discord name of a unicode emoji representing the sticker's expression
    * @param {GuildStickerCreateOptions} [options] Options

packages/discord.js/src/structures/Attachment.js

@@ -3,74 +3,30 @@
 const Util = require('../util/Util');
 
 /**
- * Represents an attachment.
+ * @typedef {Object} AttachmentPayload
+ * @property {?string} name The name of the attachment
+ * @property {Stream|BufferResolvable} attachment The attachment in this payload
+ * @property {?string} description The description of the attachment
+ */
+
+/**
+ * Represents an attachment
  */
 class Attachment {
   /**
-   * @param {BufferResolvable|Stream} attachment The file
-   * @param {string} [name=null] The name of the file, if any
-   * @param {APIAttachment} [data] Extra data
+   * @param {APIAttachment} data Attachment data
+   * @private
    */
-  constructor(attachment, name = null, data) {
-    this.attachment = attachment;
+  constructor({ url, filename, ...data }) {
+    this.attachment = url;
     /**
      * The name of this attachment
-     * @type {?string}
+     * @type {string}
      */
-    this.name = name;
+    this.name = filename;
     if (data) this._patch(data);
   }
 
-  /**
-   * Sets the description of this attachment.
-   * @param {string} description The description of the file
-   * @returns {Attachment} This attachment
-   */
-  setDescription(description) {
-    this.description = description;
-    return this;
-  }
-
-  /**
-   * Sets the file of this attachment.
-   * @param {BufferResolvable|Stream} attachment The file
-   * @param {string} [name=null] The name of the file, if any
-   * @returns {Attachment} This attachment
-   */
-  setFile(attachment, name = null) {
-    this.attachment = attachment;
-    this.name = name;
-    return this;
-  }
-
-  /**
-   * Sets the name of this attachment.
-   * @param {string} name The name of the file
-   * @returns {Attachment} This attachment
-   */
-  setName(name) {
-    this.name = name;
-    return this;
-  }
-
-  /**
-   * Sets whether this attachment is a spoiler
-   * @param {boolean} [spoiler=true] Whether the attachment should be marked as a spoiler
-   * @returns {Attachment} This attachment
-   */
-  setSpoiler(spoiler = true) {
-    if (spoiler === this.spoiler) return this;
-
-    if (!spoiler) {
-      while (this.spoiler) {
-        this.name = this.name.slice('SPOILER_'.length);
-      }
-      return this;
-    }
-    this.name = `SPOILER_${this.name}`;
-    return this;
-  }
-
   _patch(data) {
     /**
      * The attachment's id
@@ -164,8 +120,3 @@ class Attachment {
 }
 
 module.exports = Attachment;
-
-/**
- * @external APIAttachment
- * @see {@link https://discord.com/developers/docs/resources/channel#attachment-object}
- */

packages/discord.js/src/structures/AttachmentBuilder.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const Util = require('../util/Util');
+
+/**
+ * Represents an attachment builder
+ */
+class AttachmentBuilder {
+  /**
+   * @param {BufferResolvable|Stream} attachment The file
+   * @param {APIAttachment} [data] Extra data
+   */
+  constructor(attachment, data = {}) {
+    /**
+     * The file associated with this attachment.
+     * @type {BufferResolvable|Stream}
+     */
+    this.attachment = attachment;
+    /**
+     * The name of this attachment
+     * @type {?string}
+     */
+    this.name = data.name;
+    /**
+     * The description of the attachment
+     * @type {?string}
+     */
+    this.description = data.description;
+  }
+
+  /**
+   * Sets the description of this attachment.
+   * @param {string} description The description of the file
+   * @returns {AttachmentBuilder} This attachment
+   */
+  setDescription(description) {
+    this.description = description;
+    return this;
+  }
+
+  /**
+   * Sets the file of this attachment.
+   * @param {BufferResolvable|Stream} attachment The file
+   * @returns {AttachmentBuilder} This attachment
+   */
+  setFile(attachment) {
+    this.attachment = attachment;
+    return this;
+  }
+
+  /**
+   * Sets the name of this attachment.
+   * @param {string} name The name of the file
+   * @returns {AttachmentBuilder} This attachment
+   */
+  setName(name) {
+    this.name = name;
+    return this;
+  }
+
+  /**
+   * Sets whether this attachment is a spoiler
+   * @param {boolean} [spoiler=true] Whether the attachment should be marked as a spoiler
+   * @returns {AttachmentBuilder} This attachment
+   */
+  setSpoiler(spoiler = true) {
+    if (spoiler === this.spoiler) return this;
+
+    if (!spoiler) {
+      while (this.spoiler) {
+        this.name = this.name.slice('SPOILER_'.length);
+      }
+      return this;
+    }
+    this.name = `SPOILER_${this.name}`;
+    return this;
+  }
+
+  /**
+   * Whether or not this attachment has been marked as a spoiler
+   * @type {boolean}
+   * @readonly
+   */
+  get spoiler() {
+    return Util.basename(this.name).startsWith('SPOILER_');
+  }
+
+  toJSON() {
+    return Util.flatten(this);
+  }
+
+  /**
+   * Makes a new builder instance from a preexisting attachment structure.
+   * @param {JSONEncodable<AttachmentPayload>} other The builder to construct a new instance from
+   * @returns {AttachmentBuilder}
+   */
+  static from(other) {
+    return new AttachmentBuilder(other.attachment, {
+      name: other.name,
+      description: other.description,
+    });
+  }
+}
+
+module.exports = AttachmentBuilder;
+
+/**
+ * @external APIAttachment
+ * @see {@link https://discord.com/developers/docs/resources/channel#attachment-object}
+ */

packages/discord.js/src/structures/CommandInteraction.js

@@ -133,7 +133,7 @@ class CommandInteraction extends Interaction {
     if (attachments) {
       result.attachments = new Collection();
       for (const attachment of Object.values(attachments)) {
-        const patched = new Attachment(attachment.url, attachment.filename, attachment);
+        const patched = new Attachment(attachment);
         result.attachments.set(attachment.id, patched);
       }
     }
@@ -189,7 +189,7 @@ class CommandInteraction extends Interaction {
       if (role) result.role = this.guild?.roles._add(role) ?? role;
 
       const attachment = resolved.attachments?.[option.value];
-      if (attachment) result.attachment = new Attachment(attachment.url, attachment.filename, attachment);
+      if (attachment) result.attachment = new Attachment(attachment);
     }
 
     return result;

packages/discord.js/src/structures/Message.js

@@ -159,7 +159,7 @@ class Message extends Base {
       this.attachments = new Collection();
       if (data.attachments) {
         for (const attachment of data.attachments) {
-          this.attachments.set(attachment.id, new Attachment(attachment.url, attachment.filename, attachment));
+          this.attachments.set(attachment.id, new Attachment(attachment));
         }
       }
     } else {
@@ -644,7 +644,8 @@ class Message extends Base {
    * Only `MessageFlags.SuppressEmbeds` can be edited.
    * @property {Attachment[]} [attachments] An array of attachments to keep,
    * all attachments will be kept if omitted
-   * @property {FileOptions[]|BufferResolvable[]|Attachment[]} [files] Files to add to the message
+   * @property {Array<JSONEncodable<AttachmentPayload>>|BufferResolvable[]|Attachment[]|AttachmentBuilder[]} [files]
+   * Files to add to the message
    * @property {ActionRow[]|ActionRowOptions[]} [components]
    * Action rows containing interactive components for the message (buttons, select menus)
    */

packages/discord.js/src/structures/MessagePayload.js

@@ -224,7 +224,8 @@ class MessagePayload {
 
   /**
    * Resolves a single file into an object sendable to the API.
-   * @param {BufferResolvable|Stream|FileOptions|Attachment} fileLike Something that could be resolved to a file
+   * @param {BufferResolvable|Stream|JSONEncodable<AttachmentPayload>} fileLike Something that could
+   * be resolved to a file
    * @returns {Promise<RawFile>}
    */
   static async resolveFile(fileLike) {

packages/discord.js/src/structures/Webhook.js

@@ -132,7 +132,8 @@ class Webhook {
    * @typedef {Object} WebhookEditMessageOptions
    * @property {Embed[]|APIEmbed[]} [embeds] See {@link WebhookMessageOptions#embeds}
    * @property {string} [content] See {@link BaseMessageOptions#content}
-   * @property {FileOptions[]|BufferResolvable[]|Attachment[]} [files] See {@link BaseMessageOptions#files}
+   * @property {JSONEncodable<AttachmentPayload>|BufferResolvable[]|Attachment[]|AttachmentBuilder[]} [files]
+   * See {@link BaseMessageOptions#files}
    * @property {MessageMentionOptions} [allowedMentions] See {@link BaseMessageOptions#allowedMentions}
    * @property {Attachment[]} [attachments] Attachments to send with the message
    * @property {ActionRow[]|ActionRowOptions[]} [components]

packages/discord.js/src/structures/interfaces/TextBasedChannel.js

@@ -64,7 +64,7 @@ class TextBasedChannel {
    * @property {FileOptions[]|BufferResolvable[]|Attachment[]} [files] Files to send with the message
    * @property {ActionRow[]|ActionRowOptions[]} [components]
    * Action rows containing interactive components for the message (buttons, select menus)
-   * @property {Attachment[]} [attachments] Attachments to send in the message
+   * @property {Array<JSONEncodable<AttachmentPayload>>} [attachments] Attachments to send in the message
    */
 
   /**