feat(Formatters): added new URL utilities and docs (#6014)

* feat(Formatters): added new URL utilities and docs

* refactor: use static class to fix docsgen error

* fix(Typings): declare members as public

* docs(Formatters): add method tags

* docs: remove empty line

Co-authored-by: SpaceEEC <spaceeec@yahoo.com>

Co-authored-by: SpaceEEC <spaceeec@yahoo.com>

package.json

@@ -45,7 +45,7 @@
   },
   "homepage": "https://github.com/discordjs/discord.js#readme",
   "dependencies": {
-    "@discordjs/builders": "^0.1.1",
+    "@discordjs/builders": "^0.2.0",
     "@discordjs/collection": "^0.1.6",
     "@discordjs/form-data": "^3.0.1",
     "@sapphire/async-queue": "^1.1.4",

src/util/Formatters.js

@@ -4,6 +4,8 @@ const {
   blockQuote,
   bold,
   codeBlock,
+  hideLinkEmbed,
+  hyperlink,
   inlineCode,
   italic,
   quote,
@@ -13,13 +15,133 @@ const {
   underscore,
 } = require('@discordjs/builders');
 
-exports.blockQuote = blockQuote;
-exports.bold = bold;
-exports.codeBlock = codeBlock;
-exports.inlineCode = inlineCode;
-exports.italic = italic;
-exports.quote = quote;
-exports.strikethrough = strikethrough;
-exports.time = time;
-exports.TimestampStyles = TimestampStyles;
-exports.underscore = underscore;
+/**
+ * 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;
+
+/**
+ * Wraps the content inside a codeblock 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 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 an 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 the content into strikethrough 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 {TimestampStyles} [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;
+
+module.exports = Formatters;

typings/index.d.ts

@@ -176,6 +176,8 @@ declare module 'discord.js' {
     blockQuote,
     bold,
     codeBlock,
+    hideLinkEmbed,
+    hyperlink,
     inlineCode,
     italic,
     quote,
@@ -2104,20 +2106,20 @@ declare module 'discord.js' {
     public static splitMessage(text: string, options?: SplitOptions): string[];
   }
 
-  export namespace Formatters {
-    export {
-      blockQuote,
-      bold,
-      codeBlock,
-      inlineCode,
-      italic,
-      quote,
-      strikethrough,
-      time,
-      TimestampStyles,
-      TimestampStylesString,
-      underscore,
-    };
+  export class Formatters extends null {
+    public static blockQuote: typeof blockQuote;
+    public static bold: typeof bold;
+    public static codeBlock: typeof codeBlock;
+    public static hideLinkEmbed: typeof hideLinkEmbed;
+    public static hyperlink: typeof hyperlink;
+    public static inlineCode: typeof inlineCode;
+    public static italic: typeof italic;
+    public static quote: typeof quote;
+    public static strikethrough: typeof strikethrough;
+    public static time: typeof time;
+    public static TimestampStyles: typeof TimestampStyles;
+    public static TimestampStylesString: TimestampStylesString;
+    public static underscore: typeof underscore;
   }
 
   export class VoiceChannel extends BaseGuildVoiceChannel {