refactor(formatters): Add support for object and name param in formatEmoji()

packages/discord.js/src/structures/Emoji.js

@@ -98,7 +98,7 @@ class Emoji extends Base {
    * reaction.message.channel.send(`The emoji used was: ${reaction.emoji}`);
    */
   toString() {
-    return this.id ? formatEmoji(this.id, this.animated) : this.name;
+    return this.id ? formatEmoji({ animated: this.animated, id: this.id, name: this.name }) : this.name;
   }
 
   toJSON() {

packages/formatters/__tests__/formatters.test.ts

@@ -176,6 +176,40 @@ describe('Message formatters', () => {
 		test('GIVEN animated emojiId THEN returns "<a:_:${emojiId}>"', () => {
 			expect<`<a:_:827220205352255549>`>(formatEmoji('827220205352255549', true)).toEqual('<a:_:827220205352255549>');
 		});
+
+		test('GIVEN static id in options object THEN returns "<:_:${id}>"', () => {
+			expect<`<:_:851461487498493952>`>(formatEmoji({ id: '851461487498493952' })).toEqual('<:_:851461487498493952>');
+		});
+
+		test('GIVEN static id in options object WITH animated explicitly false THEN returns "<:_:${id}>"', () => {
+			expect<`<:_:851461487498493952>`>(formatEmoji({ animated: false, id: '851461487498493952' })).toEqual(
+				'<:_:851461487498493952>',
+			);
+		});
+
+		test('GIVEN animated id in options object THEN returns "<a:_:${id}>"', () => {
+			expect<`<a:_:827220205352255549>`>(formatEmoji({ animated: true, id: '827220205352255549' })).toEqual(
+				'<a:_:827220205352255549>',
+			);
+		});
+
+		test('GIVEN static id and name in options object THEN returns "<:${name}:${id}>"', () => {
+			expect<`<:test:851461487498493952>`>(formatEmoji({ id: '851461487498493952', name: 'test' })).toEqual(
+				'<:test:851461487498493952>',
+			);
+		});
+
+		test('GIVEN static id and name WITH animated explicitly false THEN returns "<:${name}:${id}>"', () => {
+			expect<`<:test:851461487498493952>`>(
+				formatEmoji({ animated: false, id: '851461487498493952', name: 'test' }),
+			).toEqual('<:test:851461487498493952>');
+		});
+
+		test('GIVEN animated id and name THEN returns "<a:${name}:${id}>"', () => {
+			expect<`<a:test:827220205352255549>`>(
+				formatEmoji({ id: '827220205352255549', name: 'test', animated: true }),
+			).toEqual('<a:test:827220205352255549>');
+		});
 	});
 
 	describe('channelLink', () => {

packages/formatters/src/formatters.ts

@@ -336,11 +336,75 @@ export function formatEmoji<EmojiId extends Snowflake>(
 	animated?: boolean,
 ): `<:_:${EmojiId}>` | `<a:_:${EmojiId}>`;
 
-export function formatEmoji<EmojiId extends Snowflake>(
-	emojiId: EmojiId,
-	animated = false,
-): `<:_:${EmojiId}>` | `<a:_:${EmojiId}>` {
-	return `<${animated ? 'a' : ''}:_:${emojiId}>`;
+/**
+ * Formats a non-animated emoji id and name into a fully qualified emoji identifier.
+ *
+ * @typeParam EmojiId - This is inferred by the supplied emoji id
+ * @typeParam EmojiName - This is inferred by the supplied name
+ * @param options - The options for formatting an emoji
+ */
+export function formatEmoji<EmojiId extends Snowflake, EmojiName extends string>(
+	options: FormatEmojiOptions<EmojiId, EmojiName> & { animated: true },
+): `<a:${EmojiName}:${EmojiId}>`;
+
+/**
+ * Formats an animated emoji id and name into a fully qualified emoji identifier.
+ *
+ * @typeParam EmojiId - This is inferred by the supplied emoji id
+ * @typeParam EmojiName - This is inferred by the supplied name
+ * @param options - The options for formatting an emoji
+ */
+export function formatEmoji<EmojiId extends Snowflake, EmojiName extends string>(
+	options: FormatEmojiOptions<EmojiId, EmojiName> & { animated?: false },
+): `<:${EmojiName}:${EmojiId}>`;
+
+/**
+ * Formats an emoji id and name into a fully qualified emoji identifier.
+ *
+ * @typeParam EmojiId - This is inferred by the supplied emoji id
+ * @typeParam EmojiName - This is inferred by the supplied emoji name
+ * @param options - The options for formatting an emoji
+ */
+export function formatEmoji<EmojiId extends Snowflake, EmojiName extends string>(
+	options: FormatEmojiOptions<EmojiId, EmojiName>,
+): `<:${EmojiName}:${EmojiId}>` | `<a:${EmojiName}:${EmojiId}>`;
+
+export function formatEmoji<EmojiId extends Snowflake, EmojiName extends string>(
+	emojiIdOrOptions: EmojiId | FormatEmojiOptions<EmojiId, EmojiName>,
+	animated?: boolean,
+): `<:${string}:${EmojiId}>` | `<a:${string}:${EmojiId}>` {
+	const options =
+		typeof emojiIdOrOptions === 'string'
+			? {
+					id: emojiIdOrOptions,
+					animated: animated ?? false,
+				}
+			: emojiIdOrOptions;
+
+	const { id, animated: isAnimated, name: emojiName } = options;
+
+	return `<${isAnimated ? 'a' : ''}:${emojiName ?? '_'}:${id}>`;
+}
+
+/**
+ * The options for formatting an emoji.
+ *
+ * @typeParam EmojiId - This is inferred by the supplied emoji id
+ * @typeParam EmojiName - This is inferred by the supplied emoji name
+ */
+export interface FormatEmojiOptions<EmojiId extends Snowflake, EmojiName extends string> {
+	/**
+	 * Whether the emoji is animated
+	 */
+	animated?: boolean;
+	/**
+	 * The emoji id to format
+	 */
+	id: EmojiId;
+	/**
+	 * The name of the emoji
+	 */
+	name?: EmojiName;
 }
 
 /**