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-lock.json

@@ -8,7 +8,7 @@
       "version": "13.0.0-dev",
       "license": "Apache-2.0",
       "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",
@@ -982,9 +982,9 @@
       }
     },
     "node_modules/@discordjs/builders": {
-      "version": "0.1.1",
+      "version": "0.2.0",
-      "resolved": "https://registry.npmjs.org/@discordjs/builders/-/builders-0.1.1.tgz",
+      "resolved": "https://registry.npmjs.org/@discordjs/builders/-/builders-0.2.0.tgz",
-      "integrity": "sha512-9eBC22bX2HBsob5ixMwZ6quy/vewU5GHuSJhpmSZ3cDGg8XPnrYdzbwI54U+V9kQBTa7M+aMu1lYVqMEPojj8A==",
+      "integrity": "sha512-TVq7NZBCJrrTRc3CfxOr3IdgY5nrtqVxZ7qDUF1mN6LgxIiOldmFxsSwMrQBzLFVmOwqFyNLKCeblley8UpEuw==",
       "dependencies": {
         "discord-api-types": "^0.18.1",
         "tslib": "^2.3.0"
@@ -12210,9 +12210,9 @@
       }
     },
     "@discordjs/builders": {
-      "version": "0.1.1",
+      "version": "0.2.0",
-      "resolved": "https://registry.npmjs.org/@discordjs/builders/-/builders-0.1.1.tgz",
+      "resolved": "https://registry.npmjs.org/@discordjs/builders/-/builders-0.2.0.tgz",
-      "integrity": "sha512-9eBC22bX2HBsob5ixMwZ6quy/vewU5GHuSJhpmSZ3cDGg8XPnrYdzbwI54U+V9kQBTa7M+aMu1lYVqMEPojj8A==",
+      "integrity": "sha512-TVq7NZBCJrrTRc3CfxOr3IdgY5nrtqVxZ7qDUF1mN6LgxIiOldmFxsSwMrQBzLFVmOwqFyNLKCeblley8UpEuw==",
       "requires": {
         "discord-api-types": "^0.18.1",
         "tslib": "^2.3.0"

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;
+ * Contains various Discord-specific functions for formatting messages.
-exports.codeBlock = codeBlock;
+ */
-exports.inlineCode = inlineCode;
+class Formatters extends null {}
-exports.italic = italic;
+
-exports.quote = quote;
+/**
-exports.strikethrough = strikethrough;
+ * Formats the content into a block quote. This needs to be at the start of the line for Discord to format it.
-exports.time = time;
+ * @method blockQuote
-exports.TimestampStyles = TimestampStyles;
+ * @memberof Formatters
-exports.underscore = underscore;
+ * @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 class Formatters extends null {
-    export {
+    public static blockQuote: typeof blockQuote;
-      blockQuote,
+    public static bold: typeof bold;
-      bold,
+    public static codeBlock: typeof codeBlock;
-      codeBlock,
+    public static hideLinkEmbed: typeof hideLinkEmbed;
-      inlineCode,
+    public static hyperlink: typeof hyperlink;
-      italic,
+    public static inlineCode: typeof inlineCode;
-      quote,
+    public static italic: typeof italic;
-      strikethrough,
+    public static quote: typeof quote;
-      time,
+    public static strikethrough: typeof strikethrough;
-      TimestampStyles,
+    public static time: typeof time;
-      TimestampStylesString,
+    public static TimestampStyles: typeof TimestampStyles;
-      underscore,
+    public static TimestampStylesString: TimestampStylesString;
-    };
+    public static underscore: typeof underscore;
   }
 
   export class VoiceChannel extends BaseGuildVoiceChannel {