feat: bring embed builder field manipulation in line with underlying array functionality (#3761)

* feat: splice multiple fields

* remove MessageEmbed#spliceField
* add MessageEmbed#spliceFields
* to behave more like Array#splice
* and allow multiple fields to be replaced/inserted
* update typings accordingly

* refactor: rename check to normalize

* check suggests boolean return type

* feat: allow spread args or array as field input

* rewrite: replace addField in favor of addFields

* typings: account for changes

* chore: bump min node to 11.0.0

* for Array#flat

* fix: bump min-node in package engines field

* remove addBlankField

README.md

@@ -38,7 +38,7 @@ discord.js is a powerful [Node.js](https://nodejs.org) module that allows you to
 - 100% coverage of the Discord API
 
 ## Installation
-**Node.js 10.2.0 or newer is required.**  
+**Node.js 11.0.0 or newer is required.**  
 Ignore any warnings about unmet peer dependencies, as they're all optional.
 
 Without voice support: `npm install discordjs/discord.js`  

docs/general/faq.md

@@ -3,7 +3,7 @@ These questions are some of the most frequently asked.
 
 
 ## No matter what, I get `SyntaxError: Block-scoped declarations (let, const, function, class) not yet supported outside strict mode`‽
-Update to Node.js 10.0.0 or newer.
+Update to Node.js 11.0.0 or newer.
 
 ## How do I get voice working?
 - Install FFMPEG.

docs/general/welcome.md

@@ -33,7 +33,7 @@ discord.js is a powerful [Node.js](https://nodejs.org) module that allows you to
 - 100% coverage of the Discord API
 
 ## Installation
-**Node.js 10.0.0 or newer is required.**  
+**Node.js 11.0.0 or newer is required.**  
 Ignore any warnings about unmet peer dependencies, as they're all optional.
 
 Without voice support: `npm install discordjs/discord.js`  

package.json

@@ -87,7 +87,7 @@
     "webpack-cli": "^3.2.3"
   },
   "engines": {
-    "node": ">=10.2.0"
+    "node": ">=11.0.0"
   },
   "browser": {
     "@discordjs/opus": false,

src/structures/MessageEmbed.js

@@ -188,41 +188,24 @@ class MessageEmbed {
   }
 
   /**
-   * Adds a field to the embed (max 25).
-   * @param {StringResolvable} name The name of the field
-   * @param {StringResolvable} value The value of the field
-   * @param {boolean} [inline=false] Set the field to display inline
+   * Adds a fields to the embed (max 25).
+   * @param {...EmbedField|EmbedField[]} fields The fields to add
    * @returns {MessageEmbed}
    */
-  addField(name, value, inline) {
-    this.fields.push(this.constructor.checkField(name, value, inline));
+  addFields(...fields) {
+    this.fields.push(...this.constructor.normalizeFields(fields));
     return this;
   }
 
-  /**
-   * Convenience function for `<MessageEmbed>.addField('\u200B', '\u200B', inline)`.
-   * @param {boolean} [inline=false] Set the field to display inline
-   * @returns {MessageEmbed}
-   */
-  addBlankField(inline) {
-    return this.addField('\u200B', '\u200B', inline);
-  }
-
   /**
    * Removes, replaces, and inserts fields in the embed (max 25).
    * @param {number} index The index to start at
    * @param {number} deleteCount The number of fields to remove
-   * @param {StringResolvable} [name] The name of the field
-   * @param {StringResolvable} [value] The value of the field
-   * @param {boolean} [inline=false] Set the field to display inline
+   * @param {...EmbedField|EmbedField[]} [fields] The replacing field objects
    * @returns {MessageEmbed}
    */
-  spliceField(index, deleteCount, name, value, inline) {
-    if (name && value) {
-      this.fields.splice(index, deleteCount, this.constructor.checkField(name, value, inline));
-    } else {
-      this.fields.splice(index, deleteCount);
-    }
+  spliceFields(index, deleteCount, ...fields) {
+    this.fields.splice(index, deleteCount, ...this.constructor.normalizeFields(...fields));
     return this;
   }
 
@@ -373,13 +356,22 @@ class MessageEmbed {
    * @param {boolean} [inline=false] Set the field to display inline
    * @returns {EmbedField}
    */
-  static checkField(name, value, inline = false) {
+  static normalizeField(name, value, inline = false) {
     name = Util.resolveString(name);
     if (!name) throw new RangeError('EMBED_FIELD_NAME');
     value = Util.resolveString(value);
     if (!value) throw new RangeError('EMBED_FIELD_VALUE');
     return { name, value, inline };
   }
+
+  /**
+   * Check for valid field input and resolves strings
+   * @param  {...EmbedField|EmbedField[]} fields Fields to normalize
+   * @returns {EmbedField[]}
+   */
+  static normalizeFields(...fields) {
+    return fields.flat(2).map(({ name, value, inline }) => this.normalizeField(name, value, inline));
+  }
 }
 
 module.exports = MessageEmbed;

typings/index.d.ts

@@ -1070,8 +1070,7 @@ declare module 'discord.js' {
 		public type: string;
 		public url: string;
 		public readonly video: { url?: string; proxyURL?: string; height?: number; width?: number } | null;
-		public addBlankField(inline?: boolean): this;
-		public addField(name: StringResolvable, value: StringResolvable, inline?: boolean): this;
+		public addFields(...fields: EmbedField[] | EmbedField[][]): this;
 		public attachFiles(file: (MessageAttachment | FileOptions | string)[]): this;
 		public setAuthor(name: StringResolvable, iconURL?: string, url?: string): this;
 		public setColor(color: ColorResolvable): this;
@@ -1082,10 +1081,11 @@ declare module 'discord.js' {
 		public setTimestamp(timestamp?: Date | number): this;
 		public setTitle(title: StringResolvable): this;
 		public setURL(url: string): this;
-		public spliceField(index: number, deleteCount: number, name?: StringResolvable, value?: StringResolvable, inline?: boolean): this;
+		public spliceFields(index: number, deleteCount: number, ...fields: EmbedField[] | EmbedField[][]): this;
 		public toJSON(): object;
 
-		public static checkField(name: StringResolvable, value: StringResolvable, inline?: boolean): Required<EmbedField>;
+		public static normalizeField(name: StringResolvable, value: StringResolvable, inline?: boolean): Required<EmbedField>;
+		public static normalizeFields(...fields: EmbedField[] | EmbedField[][]): Required<EmbedField>[];
 	}
 
 	export class MessageMentions {