refactor: Deprecate Formatter class (#8373)

2026-03-20 21:43:33 +01:00 · 2022-07-27 12:05:31 +01:00
parent b6bba9901b
commit 7fd9ed8f13
2 changed files with 257 additions and 54 deletions
--- a/packages/discord.js/src/util/Formatters.js
+++ b/packages/discord.js/src/util/Formatters.js
@@ -1,5 +1,6 @@
 'use strict';

+const { deprecate } = require('node:util');
 const {
  blockQuote,
  bold,
@@ -21,142 +22,117 @@ const {
 } = require('@discordjs/builders');

 /**
- * 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}
-   */
-  static blockQuote = blockQuote;
-
-  /**
-   * Formats the content into bold text.
-   * @method bold
-   * @memberof Formatters
-   * @param {string} content The content to wrap.
-   * @returns {string}
-   */
-  static bold = bold;
-
-  /**
-   * Formats a channel id into a channel mention.
-   * @method channelMention
-   * @memberof Formatters
-   * @param {string} channelId The channel id to format.
-   * @returns {string}
-   */
-  static channelMention = channelMention;
-
-  /**
 * Wraps the content inside a code block 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.
+ * @param {string} contentOrLanguage The language to use or content if a second parameter isn't provided
+ * @param {string} [content] The content to wrap
 * @returns {string}
 */
-  static codeBlock = codeBlock;

-  /**
-   * Formats an emoji id into a fully qualified emoji identifier
-   * @method formatEmoji
-   * @memberof Formatters
-   * @memberof Formatters
-   * @param {string} emojiId The emoji id to format.
-   * @param {boolean} [animated] Whether the emoji is animated or not. Defaults to `false`
-   * @returns {string}
-   */
-  static formatEmoji = formatEmoji;
-
-  /**
-   * Wraps the URL into `<>`, which stops it from embedding.
-   * @method hideLinkEmbed
-   * @memberof Formatters
-   * @param {string} content The content to wrap.
-   * @returns {string}
-   */
-  static 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}
-   */
-  static hyperlink = hyperlink;
-
-  /**
+/**
 * Wraps the content inside \`backticks\`, which formats it as inline code.
 * @method inlineCode
-   * @memberof Formatters
-   * @param {string} content The content to wrap.
+ * @param {string} content The content to wrap
 * @returns {string}
 */
-  static inlineCode = inlineCode;

-  /**
+/**
 * Formats the content into italic text.
 * @method italic
-   * @memberof Formatters
-   * @param {string} content The content to wrap.
+ * @param {string} content The content to wrap
 * @returns {string}
 */
-  static 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.
+/**
+ * Formats the content into bold text.
+ * @method bold
+ * @param {string} content The content to wrap
 * @returns {string}
 */
-  static quote = quote;

-  /**
-   * Formats a role id into a role mention.
-   * @method roleMention
-   * @memberof Formatters
-   * @param {string} roleId The role id to format.
+/**
+ * Formats the content into underscored text.
+ * @method underscore
+ * @param {string} content The content to wrap
 * @returns {string}
 */
-  static roleMention = roleMention;

-  /**
-   * Formats the content into spoiler text.
-   * @method spoiler
-   * @memberof Formatters
-   * @param {string} content The content to spoiler.
-   * @returns {string}
-   */
-  static spoiler = spoiler;
-
-  /**
+/**
 * Formats the content into strike-through text.
 * @method strikethrough
-   * @memberof Formatters
-   * @param {string} content The content to wrap.
+ * @param {string} content The content to wrap
 * @returns {string}
 */
-  static strikethrough = strikethrough;

-  /**
-   * Formats a date into a short date-time string.
-   * @method time
-   * @memberof Formatters
-   * @param {number|Date} [date] The date to format.
-   * @param {TimestampStylesString} [style] The style to use.
+/**
+ * Formats the content into a quote.
+ * <info>This needs to be at the start of the line for Discord to format it.</info>
+ * @method quote
+ * @param {string} content The content to wrap
 * @returns {string}
 */
-  static time = time;

-  /**
+/**
+ * Formats the content into a block quote.
+ * <info>This needs to be at the start of the line for Discord to format it.</info>
+ * @method blockQuote
+ * @param {string} content The content to wrap
+ * @returns {string}
+ */
+
+/**
+ * Wraps the URL into `<>`, which stops it from embedding.
+ * @method hideLinkEmbed
+ * @param {string} content The content to wrap
+ * @returns {string}
+ */
+
+/**
+ * Formats the content and the URL into a masked URL with an optional title.
+ * @method hyperlink
+ * @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}
+ */
+
+/**
+ * Formats the content into spoiler text.
+ * @method spoiler
+ * @param {string} content The content to spoiler
+ * @returns {string}
+ */
+
+/**
+ * Formats a user id into a user mention.
+ * @method userMention
+ * @param {Snowflake} userId The user id to format
+ * @returns {string}
+ */
+
+/**
+ * Formats a channel id into a channel mention.
+ * @method channelMention
+ * @param {Snowflake} channelId The channel id to format
+ * @returns {string}
+ */
+
+/**
+ * Formats a role id into a role mention.
+ * @method roleMention
+ * @param {Snowflake} roleId The role id to format
+ * @returns {string}
+ */
+
+/**
+ * Formats an emoji id into a fully qualified emoji identifier.
+ * @method formatEmoji
+ * @param {Snowflake} emojiId The emoji id to format
+ * @param {boolean} [animated=false] Whether the emoji is animated
+ * @returns {string}
+ */
+
+/**
 * 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.
@@ -169,11 +145,213 @@ class Formatters extends null {
 * @typedef {string} TimestampStylesString
 */

+/**
+ * Formats a date into a short date-time string.
+ * @method time
+ * @param {number|Date} [date] The date to format
+ * @param {TimestampStylesString} [style] The style to use
+ * @returns {string}
+ */
+
+/**
+ * Contains various Discord-specific functions for formatting messages.
+ * @deprecated This class is redundant as all methods of the class can be imported from discord.js directly.
+ */
+class Formatters extends null {
+  /**
+   * Formats the content into a block quote.
+   * <info>This needs to be at the start of the line for Discord to format it.</info>
+   * @method blockQuote
+   * @memberof Formatters
+   * @param {string} content The content to wrap
+   * @returns {string}
+   * @deprecated Import this method directly from discord.js instead.
+   */
+  static blockQuote = deprecate(
+    blockQuote,
+    'Formatters.blockQuote() is deprecated. Import this method directly from discord.js instead.',
+  );
+
+  /**
+   * Formats the content into bold text.
+   * @method bold
+   * @memberof Formatters
+   * @param {string} content The content to wrap
+   * @returns {string}
+   * @deprecated Import this method directly from discord.js instead.
+   */
+  static bold = deprecate(
+    bold,
+    'Formatters.bold() is deprecated. Import this method directly from discord.js instead.',
+  );
+
+  /**
+   * Formats a channel id into a channel mention.
+   * @method channelMention
+   * @memberof Formatters
+   * @param {Snowflake} channelId The channel id to format
+   * @returns {string}
+   * @deprecated Import this method directly from discord.js instead.
+   */
+  static channelMention = deprecate(
+    channelMention,
+    'Formatters.channelMention() is deprecated. Import this method directly from discord.js instead.',
+  );
+
+  /**
+   * Wraps the content inside a code block with an optional language.
+   * @method codeBlock
+   * @memberof Formatters
+   * @param {string} contentOrLanguage The language to use or content if a second parameter isn't provided
+   * @param {string} [content] The content to wrap
+   * @returns {string}
+   * @deprecated Import this method directly from discord.js instead.
+   */
+  static codeBlock = deprecate(
+    codeBlock,
+    'Formatters.codeBlock() is deprecated. Import this method directly from discord.js instead.',
+  );
+
+  /**
+   * Formats an emoji id into a fully qualified emoji identifier.
+   * @method formatEmoji
+   * @memberof Formatters
+   * @param {string} emojiId The emoji id to format
+   * @param {boolean} [animated=false] Whether the emoji is animated
+   * @returns {string}
+   * @deprecated Import this method directly from discord.js instead.
+   */
+  static formatEmoji = deprecate(
+    formatEmoji,
+    'Formatters.formatEmoji() is deprecated. Import this method directly from discord.js instead.',
+  );
+
+  /**
+   * Wraps the URL into `<>`, which stops it from embedding.
+   * @method hideLinkEmbed
+   * @memberof Formatters
+   * @param {string} content The content to wrap
+   * @returns {string}
+   * @deprecated Import this method directly from discord.js instead.
+   */
+  static hideLinkEmbed = deprecate(
+    hideLinkEmbed,
+    'Formatters.hideLinkEmbed() is deprecated. Import this method directly from discord.js instead.',
+  );
+
+  /**
+   * 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}
+   * @deprecated Import this method directly from discord.js instead.
+   */
+  static hyperlink = deprecate(
+    hyperlink,
+    'Formatters.hyperlink() is deprecated. Import this method directly from discord.js instead.',
+  );
+
+  /**
+   * Wraps the content inside \`backticks\`, which formats it as inline code.
+   * @method inlineCode
+   * @memberof Formatters
+   * @param {string} content The content to wrap
+   * @returns {string}
+   * @deprecated Import this method directly from discord.js instead.
+   */
+  static inlineCode = deprecate(
+    inlineCode,
+    'Formatters.inlineCode() is deprecated. Import this method directly from discord.js instead.',
+  );
+
+  /**
+   * Formats the content into italic text.
+   * @method italic
+   * @memberof Formatters
+   * @param {string} content The content to wrap
+   * @returns {string}
+   * @deprecated Import this method directly from discord.js instead.
+   */
+  static italic = deprecate(
+    italic,
+    'Formatters.italic() is deprecated. Import this method directly from discord.js instead.',
+  );
+
+  /**
+   * 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}
+   * @deprecated Import this method directly from discord.js instead.
+   */
+  static quote = deprecate(
+    quote,
+    'Formatters.quote() is deprecated. Import this method directly from discord.js instead.',
+  );
+
+  /**
+   * Formats a role id into a role mention.
+   * @method roleMention
+   * @memberof Formatters
+   * @param {Snowflake} roleId The role id to format
+   * @returns {string}
+   * @deprecated Import this method directly from discord.js instead.
+   */
+  static roleMention = deprecate(
+    roleMention,
+    'Formatters.roleMention() is deprecated. Import this method directly from discord.js instead.',
+  );
+
+  /**
+   * Formats the content into spoiler text.
+   * @method spoiler
+   * @memberof Formatters
+   * @param {string} content The content to spoiler
+   * @returns {string}
+   * @deprecated Import this method directly from discord.js instead.
+   */
+  static spoiler = deprecate(
+    spoiler,
+    'Formatters.spoiler() is deprecated. Import this method directly from discord.js instead.',
+  );
+
+  /**
+   * Formats the content into strike-through text.
+   * @method strikethrough
+   * @memberof Formatters
+   * @param {string} content The content to wrap
+   * @returns {string}
+   * @deprecated Import this method directly from discord.js instead.
+   */
+  static strikethrough = deprecate(
+    strikethrough,
+    'Formatters.strikethrough() is deprecated. Import this method directly from discord.js instead.',
+  );
+
+  /**
+   * Formats a date into a short date-time string.
+   * @method time
+   * @memberof Formatters
+   * @param {number|Date} [date] The date to format
+   * @param {TimestampStylesString} [style] The style to use
+   * @returns {string}
+   * @deprecated Import this method directly from discord.js instead.
+   */
+  static time = deprecate(
+    time,
+    'Formatters.time() is deprecated. Import this method directly from discord.js instead.',
+  );
+
  /**
   * The message formatting timestamp
   * [styles](https://discord.com/developers/docs/reference#message-formatting-timestamp-styles) supported by Discord.
   * @type {Object<string, TimestampStylesString>}
   * @memberof Formatters
+   * @deprecated Import this property directly from discord.js instead.
   */
  static TimestampStyles = TimestampStyles;

@@ -181,19 +359,27 @@ class Formatters extends null {
   * Formats the content into underscored text.
   * @method underscore
   * @memberof Formatters
-   * @param {string} content The content to wrap.
+   * @param {string} content The content to wrap
   * @returns {string}
+   * @deprecated Import this method directly from discord.js instead.
   */
-  static underscore = underscore;
+  static underscore = deprecate(
+    underscore,
+    'Formatters.underscore() is deprecated. Import this method directly from discord.js instead.',
+  );

  /**
   * Formats a user id into a user mention.
   * @method userMention
   * @memberof Formatters
-   * @param {string} userId The user id to format.
+   * @param {Snowflake} userId The user id to format
   * @returns {string}
+   * @deprecated Import this method directly from discord.js instead.
   */
-  static userMention = userMention;
+  static userMention = deprecate(
+    userMention,
+    'Formatters.userMention() is deprecated. Import this method directly from discord.js instead.',
+  );
 }

 module.exports = Formatters;
--- a/packages/discord.js/typings/index.d.ts
+++ b/packages/discord.js/typings/index.d.ts
@@ -2699,24 +2699,41 @@ export function createComponentBuilder<T extends keyof MappedComponentBuilderTyp
 export function createComponentBuilder<C extends ComponentBuilder>(data: C): C;
 export function createComponentBuilder(data: APIMessageComponent | ComponentBuilder): ComponentBuilder;

+/** @deprecated This class is redundant as all methods of the class can be imported from discord.js directly. */
 export class Formatters extends null {
+  /** @deprecated Import this method directly from discord.js instead. */
  public static blockQuote: typeof blockQuote;
+  /** @deprecated Import this method directly from discord.js instead. */
  public static bold: typeof bold;
+  /** @deprecated Import this method directly from discord.js instead. */
  public static channelMention: typeof channelMention;
+  /** @deprecated Import this method directly from discord.js instead. */
  public static codeBlock: typeof codeBlock;
+  /** @deprecated Import this method directly from discord.js instead. */
  public static formatEmoji: typeof formatEmoji;
+  /** @deprecated Import this method directly from discord.js instead. */
  public static hideLinkEmbed: typeof hideLinkEmbed;
+  /** @deprecated Import this method directly from discord.js instead. */
  public static hyperlink: typeof hyperlink;
+  /** @deprecated Import this method directly from discord.js instead. */
  public static inlineCode: typeof inlineCode;
+  /** @deprecated Import this method directly from discord.js instead. */
  public static italic: typeof italic;
+  /** @deprecated Import this method directly from discord.js instead. */
  public static quote: typeof quote;
+  /** @deprecated Import this method directly from discord.js instead. */
  public static roleMention: typeof roleMention;
+  /** @deprecated Import this method directly from discord.js instead. */
  public static spoiler: typeof spoiler;
+  /** @deprecated Import this method directly from discord.js instead. */
  public static strikethrough: typeof strikethrough;
+  /** @deprecated Import this method directly from discord.js instead. */
  public static time: typeof time;
+  /** @deprecated Import this property directly from discord.js instead. */
  public static TimestampStyles: typeof TimestampStyles;
-  public static TimestampStylesString: TimestampStylesString;
+  /** @deprecated Import this method directly from discord.js instead. */
  public static underscore: typeof underscore;
+  /** @deprecated Import this method directly from discord.js instead. */
  public static userMention: typeof userMention;
 }