From 7fd9ed8f13d17ce7e98e34f7454d9047054d8467 Mon Sep 17 00:00:00 2001 From: Jiralite <33201955+Jiralite@users.noreply.github.com> Date: Wed, 27 Jul 2022 12:05:31 +0100 Subject: [PATCH] refactor: Deprecate `Formatter` class (#8373) --- packages/discord.js/src/util/Formatters.js | 292 +++++++++++++++++---- packages/discord.js/typings/index.d.ts | 19 +- 2 files changed, 257 insertions(+), 54 deletions(-) diff --git a/packages/discord.js/src/util/Formatters.js b/packages/discord.js/src/util/Formatters.js index 7e6999593..7a188286e 100644 --- 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, @@ -20,160 +21,337 @@ const { userMention, } = require('@discordjs/builders'); +/** + * Wraps the content inside a code block with an optional language. + * @method codeBlock + * @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} + */ + +/** + * Wraps the content inside \`backticks\`, which formats it as inline code. + * @method inlineCode + * @param {string} content The content to wrap + * @returns {string} + */ + +/** + * Formats the content into italic text. + * @method italic + * @param {string} content The content to wrap + * @returns {string} + */ + +/** + * Formats the content into bold text. + * @method bold + * @param {string} content The content to wrap + * @returns {string} + */ + +/** + * Formats the content into underscored text. + * @method underscore + * @param {string} content The content to wrap + * @returns {string} + */ + +/** + * Formats the content into strike-through text. + * @method strikethrough + * @param {string} content The content to wrap + * @returns {string} + */ + +/** + * Formats the content into a quote. + * This needs to be at the start of the line for Discord to format it. + * @method quote + * @param {string} content The content to wrap + * @returns {string} + */ + +/** + * Formats the content into a block quote. + * This needs to be at the start of the line for Discord to format it. + * @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. + * * `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 + */ + +/** + * 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. This needs to be at the start of the line for Discord to format it. + * 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. + * @param {string} content The content to wrap * @returns {string} + * @deprecated Import this method directly from discord.js instead. */ - static blockQuote = blockQuote; + 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. + * @param {string} content The content to wrap * @returns {string} + * @deprecated Import this method directly from discord.js instead. */ - static bold = bold; + 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 {string} channelId The channel id to format. + * @param {Snowflake} channelId The channel id to format * @returns {string} + * @deprecated Import this method directly from discord.js instead. */ - static channelMention = channelMention; + 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, 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} + * @deprecated Import this method directly from discord.js instead. */ - static codeBlock = codeBlock; + 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 + * 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` + * @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 = formatEmoji; + 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. + * @param {string} content The content to wrap * @returns {string} + * @deprecated Import this method directly from discord.js instead. */ - static hideLinkEmbed = hideLinkEmbed; + 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. + * @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 = hyperlink; + 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. + * @param {string} content The content to wrap * @returns {string} + * @deprecated Import this method directly from discord.js instead. */ - static inlineCode = inlineCode; + 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. + * @param {string} content The content to wrap * @returns {string} + * @deprecated Import this method directly from discord.js instead. */ - static italic = italic; + 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. + * @param {string} content The content to wrap * @returns {string} + * @deprecated Import this method directly from discord.js instead. */ - static quote = quote; + 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 {string} roleId The role id to format. + * @param {Snowflake} roleId The role id to format * @returns {string} + * @deprecated Import this method directly from discord.js instead. */ - static roleMention = roleMention; + 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. + * @param {string} content The content to spoiler * @returns {string} + * @deprecated Import this method directly from discord.js instead. */ - static spoiler = spoiler; + 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. + * @param {string} content The content to wrap * @returns {string} + * @deprecated Import this method directly from discord.js instead. */ - static strikethrough = strikethrough; + 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. + * @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 = 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 - */ + 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} * @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; diff --git a/packages/discord.js/typings/index.d.ts b/packages/discord.js/typings/index.d.ts index 747f66ac6..b12a61a73 100644 --- a/packages/discord.js/typings/index.d.ts +++ b/packages/discord.js/typings/index.d.ts @@ -2699,24 +2699,41 @@ export function createComponentBuilder(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; }