feat: add chatInputApplicationCommandMention formatter (#8546)

feat: add `chatInputApplicationCommandMention()` formatter

Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

packages/builders/__tests__/messages/formatters.test.ts

@@ -2,6 +2,7 @@
 import { URL } from 'node:url';
 import { describe, test, expect, vitest } from 'vitest';
 import {
+	chatInputApplicationCommandMention,
 	blockQuote,
 	bold,
 	channelLink,
@@ -137,6 +138,26 @@ describe('Message formatters', () => {
 				expect(roleMention('815434166602170409')).toEqual('<@&815434166602170409>');
 			});
 		});
+
+		describe('chatInputApplicationCommandMention', () => {
+			test('GIVEN commandName and commandId THEN returns "</[commandName]:[commandId]>"', () => {
+				expect(chatInputApplicationCommandMention('airhorn', '815434166602170409')).toEqual(
+					'</airhorn:815434166602170409>',
+				);
+			});
+
+			test('GIVEN commandName, subcommandName, and commandId THEN returns "</[commandName] [subcommandName]:[commandId]>"', () => {
+				expect(chatInputApplicationCommandMention('airhorn', 'sub', '815434166602170409')).toEqual(
+					'</airhorn sub:815434166602170409>',
+				);
+			});
+
+			test('GIVEN commandName, subcommandGroupName, subcommandName, and commandId THEN returns "</[commandName] [subcommandGroupName] [subcommandName]:[commandId]>"', () => {
+				expect(chatInputApplicationCommandMention('airhorn', 'group', 'sub', '815434166602170409')).toEqual(
+					'</airhorn group sub:815434166602170409>',
+				);
+			});
+		});
 	});
 
 	describe('formatEmoji', () => {

packages/builders/src/messages/formatters.ts

@@ -180,6 +180,75 @@ export function roleMention<C extends Snowflake>(roleId: C): `<@&${C}>` {
 	return `<@&${roleId}>`;
 }
 
+/**
+ * Formats an application command name, subcommand group name, subcommand name, and ID into an application command mention
+ *
+ * @param commandName - The application command name to format
+ * @param subcommandGroupName - The subcommand group name to format
+ * @param subcommandName - The subcommand name to format
+ * @param commandId - The application command ID to format
+ */
+export function chatInputApplicationCommandMention<
+	N extends string,
+	G extends string,
+	S extends string,
+	I extends Snowflake,
+>(commandName: N, subcommandGroupName: G, subcommandName: S, commandId: I): `</${N} ${G} ${S}:${I}>`;
+
+/**
+ * Formats an application command name, subcommand name, and ID into an application command mention
+ *
+ * @param commandName - The application command name to format
+ * @param subcommandName - The subcommand name to format
+ * @param commandId - The application command ID to format
+ */
+export function chatInputApplicationCommandMention<N extends string, S extends string, I extends Snowflake>(
+	commandName: N,
+	subcommandName: S,
+	commandId: I,
+): `</${N} ${S}:${I}>`;
+
+/**
+ * Formats an application command name and ID into an application command mention
+ *
+ * @param commandName - The application command name to format
+ * @param commandId - The application command ID to format
+ */
+export function chatInputApplicationCommandMention<N extends string, I extends Snowflake>(
+	commandName: N,
+	commandId: I,
+): `</${N}:${I}>`;
+
+/**
+ * Formats an application command name, subcommand group name, subcommand name, and ID into an application command mention
+ *
+ * @param commandName - The application command name to format
+ * @param subcommandGroupName - The subcommand group name to format
+ * @param subcommandName - The subcommand name to format
+ * @param commandId - The application command ID to format
+ */
+export function chatInputApplicationCommandMention<
+	N extends string,
+	G extends Snowflake | string,
+	S extends Snowflake | string,
+	I extends Snowflake,
+>(
+	commandName: N,
+	subcommandGroupName: G,
+	subcommandName?: S,
+	commandId?: I,
+): `</${N} ${G} ${S}:${I}>` | `</${N} ${G}:${S}>` | `</${N}:${G}>` {
+	if (typeof commandId !== 'undefined') {
+		return `</${commandName} ${subcommandGroupName} ${subcommandName!}:${commandId}>`;
+	}
+
+	if (typeof subcommandName !== 'undefined') {
+		return `</${commandName} ${subcommandGroupName}:${subcommandName}>`;
+	}
+
+	return `</${commandName}:${subcommandGroupName}>`;
+}
+
 /**
  * Formats an emoji ID into a fully qualified emoji identifier
  *

packages/discord.js/src/util/Formatters.js

@@ -21,6 +21,17 @@ const {
   userMention,
 } = require('@discordjs/builders');
 
+/**
+ * Formats an application command name and id into an application command mention.
+ * @method chatInputApplicationCommandMention
+ * @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 {?string} [commandId] The id of the application command
+ * @returns {string}
+ */
+
 /**
  * Wraps the content inside a code block with an optional language.
  * @method codeBlock