From 0d0e4d1cb61e27d476352294a5624fec2bbf657b Mon Sep 17 00:00:00 2001
From: Jiralite <33201955+Jiralite@users.noreply.github.com>
Date: Fri, 14 Apr 2023 09:58:23 +0100
Subject: [PATCH] feat: Add changes from v13 to v14 (#9384)
---
.../03-additional-info/03-updating-to-v14.mdx | 805 ++++++++++++++++++
1 file changed, 805 insertions(+)
create mode 100644 apps/guide/src/content/03-additional-info/03-updating-to-v14.mdx
diff --git a/apps/guide/src/content/03-additional-info/03-updating-to-v14.mdx b/apps/guide/src/content/03-additional-info/03-updating-to-v14.mdx
new file mode 100644
index 000000000..d1f27196d
--- /dev/null
+++ b/apps/guide/src/content/03-additional-info/03-updating-to-v14.mdx
@@ -0,0 +1,805 @@
+---
+title: Updating to v14
+category: Additional info
+---
+
+# Updating to v14
+
+## Before you start
+
+v14 requires Node 16.9 or higher to use, so make sure you're up to date. To check your Node.js version, use _`node --version`_ in your terminal or command prompt, and if it's not high enough, update it! There are many resources online to help you with this step based on your host system.
+
+### Various packages are now included in v14
+
+If you previously had _`@discordjs/builders`_, _`@discordjs/formatters`_, _`@discordjs/rest`_, or _`discord-api-types`_ manually installed, it's _highly_ recommended that you uninstall the packages to avoid package version conflicts.
+
+
+
+```sh npm
+npm uninstall @discordjs/builders @discordjs/formatters @discordjs/rest discord-api-types
+```
+
+```sh yarn
+yarn remove @discordjs/builders @discordjs/formatters @discordjs/rest discord-api-types
+```
+
+```sh pnpm
+pnpm remove @discordjs/builders @discordjs/formatters @discordjs/rest discord-api-types
+```
+
+
+
+## Breaking Changes
+
+### API version
+
+discord.js v14 makes the switch to Discord API v10!
+
+### Common Breakages
+
+### Enum Values
+
+Any areas that used to accept a _`string`_ or _`number`_ type for an enum parameter will now only accept a _`number`_.
+
+In addition, the old enums exported by discord.js v13 and lower are replaced with new enums from [discord-api-types](https://discord-api-types.dev/api/discord-api-types-v10).
+
+#### New enum differences
+
+Most of the difference between enums from discord.js and discord-api-types can be summarized as so:
+
+1. Enums are singular, i.e., _`ApplicationCommandOptionTypes`_ -> _`ApplicationCommandOptionType`_
+2. Enums that are prefixed with _`Message`_ no longer have the _`Message`_ prefix, i.e., _`MessageButtonStyles`_ -> _`ButtonStyle`_
+3. Enum values are _`PascalCase`_ rather than `SCREAMING_SNAKE_CASE`, i.e., `.CHAT_INPUT` -> `.ChatInput`
+
+
+ You might be inclined to a raw _`number`_ (most commonly referred to as [magic
+ numbers](https://en.wikipedia.org/wiki/Magic_number_(programming))) instead of enum values. This is highly
+ discouraged. Enums provide more readability and are more resistant to changes in the API. Magic numbers can obscure
+ the meaning of your code in many ways. Check out this [blog
+ post](https://blog.webdevsimplified.com/2020-02/magic-numbers) if you want more context on as to why they shouldn't be
+ used.
+
+
+#### Common enum breakages
+
+Areas like _`Client`_ initialization, JSON slash commands and JSON message components will likely need to be modified to accommodate these changes:
+
+##### Common Client Initialization Changes
+
+
+
+```diff
+- import { Client, Intents } = from 'discord.js';
++ import { Client, GatewayIntentBits, Partials } = from 'discord.js';
+
+- const client = new Client({ intents: [Intents.FLAGS.GUILDS], partials: ['CHANNEL'] });
++ const client = new Client({ intents: [GatewayIntentBits.Guilds], partials: [Partials.Channel] });
+```
+
+
+
+##### Common Application Command Data changes
+
+
+
+```diff
++ import { ApplicationCommandType, ApplicationCommandOptionType } = from 'discord.js';
+
+ const command = {
+ name: 'ping',
+- type: 'CHAT_INPUT',
++ type: ApplicationCommandType.ChatInput,
+ options: [{
+ name: 'option',
+ description: 'A sample option',
+- type: 'STRING',
++ type: ApplicationCommandOptionType.String,
+ }],
+ };
+```
+
+
+
+##### Common Button Data changes
+
+
+
+```diff
++ import { ButtonStyle } = from 'discord.js';
+
+ const button = {
+ label: 'test',
+- style: 'PRIMARY',
++ style: ButtonStyle.Primary,
+ customId: '1234'
+ }
+```
+
+
+
+### Removal of method-based type guards
+
+#### Channels
+
+Some channel type guard methods that narrowed to one channel type have been removed. Instead compare the _`type`_ property against a [ChannelType](https://discord-api-types.dev/api/discord-api-types-v10/enum/ChannelType) enum member to narrow channels.
+
+
+
+```diff
+- channel.isText();
++ channel.type === ChannelType.GuildText;
+
+- channel.isVoice();
++ channel.type === ChannelType.GuildVoice;
+
+- channel.isDM();
++ channel.type === ChannelType.DM;
+```
+
+
+
+### Builders
+
+Builders are no longer returned by the API like they were previously. For example, you send the API an but you receive an of the same data. This may affect how your code handles received structures such as components. Refer to [message component changes section](#messagecomponent) for more details.
+
+Added and as top-level exports which disable or enable validation (enabled by default).
+
+### Consolidation of create & edit parameters
+
+Various _`create()`_ and _`edit()`_ methods on managers and objects have had their parameters consolidated. The changes are below:
+
+- now takes _`reason`_ in the _`data`_ parameter
+- now takes _`reason`_ in the _`data`_ parameter
+- now takes _`reason`_ in the _`data`_ parameter
+- now takes _`reason`_ in the _`data`_ parameter
+- now takes _`reason`_ in the _`data`_ parameter
+- now takes _`reason`_ in the _`data`_ parameter
+- now takes _`name`_ in the _`options`_ parameter
+- (and other text-based channels)
+ now takes _`channel`_ and _`name`_ in the _`options`_ parameter
+- now takes _`reason`_ as a part of _`data`_
+- now takes _`reason`_ as a part of _`data`_
+- now takes _`name`_ as a part of _`options`_
+- now takes _`reason`_ as a part of _`data`_
+- now takes _`reason`_ as a part of _`data`_
+- now takes _`reason`_ as a part of _`data`_
+- now takes _`reason`_ as a part of _`options`_
+- now takes _`reason`_ as a part of _`options`_
+- now takes _`attachment`_ and _`name`_ as
+ a part of _`options`_
+- now takes _`file`_, _`name`_, and _`tags`_
+ as a part of _`options`_
+
+### Activity
+
+The following properties have been removed as they are not supported by the API:
+
+- _`Activity#id`_
+- _`Activity#platform`_
+- _`Activity#sessionId`_
+- _`Activity#syncId`_
+
+### Application
+
+_`Application#fetchAssets()`_ has been removed as it is no longer supported by the API.
+
+### BitField
+
+- BitField constituents now have a _`BitField`_ suffix to avoid naming conflicts with the enum names:
+
+```diff
+- new Permissions();
++ new PermissionsBitField();
+
+- new MessageFlags();
++ new MessageFlagsBitField();
+
+- new ThreadMemberFlags();
++ new ThreadMemberFlagsBitField();
+
+- new UserFlags();
++ new UserFlagsBitField();
+
+- new SystemChannelFlags();
++ new SystemChannelFlagsBitField();
+
+- new ApplicationFlags();
++ new ApplicationFlagsBitField();
+
+- new Intents();
++ new IntentsBitField();
+
+- new ActivityFlags();
++ new ActivityFlagsBitField();
+```
+
+- _`#FLAGS`_ has been renamed to _`#Flags`_
+
+### CDN
+
+The methods that return CDN URLs have changed. Here is an example on a `User`:
+
+
+
+```diff
+- const url = user.displayAvatarURL({ dynamic: true, format: "png", size: 1024 });
++ const url = user.displayAvatarURL({ extension: "png", size: 1024 });
+```
+
+
+
+Dynamic URLs use and static URLs use . Since dynamic URLs are returned by default, this option has been renamed to _`forceStatic`_ which forces the return of a static URL. Additionally, _`format`_ has been renamed to _`extension`_.
+
+### CategoryChannel
+
+ is no longer a _`Collection`_ of channels the category
+contains. It is now a . This also means
+_`CategoryChannel#createChannel()`_ has been moved to the .
+
+### Channel
+
+The following type guards have been removed:
+
+- _`Channel#isText()`_
+- _`Channel#isVoice()`_
+- _`Channel#isDirectory()`_
+- _`Channel#isDM()`_
+- _`Channel#isGroupDM()`_
+- _`Channel#isCategory()`_
+- _`Channel#isNews()`_
+
+Refer to [this section](#channels) for more context.
+
+The base channel class is now .
+
+### Client
+
+The _`restWsBridgeTimeout`_ client option has been removed.
+
+### CommandInteractionOptionResolver
+
+ no longer has a parameter
+for _`required`_.[^1]
+
+### Constants
+
+- Many constant objects and key arrays are now top-level exports. For example:
+
+
+
+```diff
+- import { Constants } = from 'discord.js';
+- const { Colors } = Constants;
++ import { Colors } = from 'discord.js';
+```
+
+
+
+- The refactored constants structures have _`PascalCase`_ member names as opposed to _`SCREAMING_SNAKE_CASE`_ member names.
+
+- Many of the exported constants structures have been replaced and renamed:
+
+
+
+```diff
+- Opcodes
++ GatewayOpcodes
+
+- WSEvents
++ GatewayDispatchEvents
+
+- WSCodes
++ GatewayCloseCodes
+
+- InviteScopes
++ OAuth2Scopes
+```
+
+
+
+### Events
+
+The _`message`_ and _`interaction`_ events are now removed. Use and instead.
+
+_`Client#applicationCommandCreate`_, _`Client#applicationCommandDelete`_, and _`Client#applicationCommandUpdate`_ have all been removed.[^2]
+
+The event now emits the users that were added, the users that were removed, and the thread respectively.
+
+### GuildBanManager
+
+Developers should utilise _`deleteMessageSeconds`_ instead of _`days`_ and _`deleteMessageDays`_:
+
+
+
+```diff
+.create('123456789', {
+- days: 3
+- deleteMessageDays: 3
++ deleteMessageSeconds: 3 * 24 * 60 * 60
+});
+```
+
+
+
+_`deleteMessageDays`_ and _`days`_ are both deprecated and will be removed in the future.
+
+### Guild
+
+ and have been removed. Use and instead respectively.
+
+ no longer has a default value of 25,000.
+
+_`Guild#me`_ has been moved to .[^3]
+
+### GuildAuditLogs & GuildAuditLogsEntry
+
+_`GuildAuditLogs.build()`_ has been removed as it has been deemed defunct. There is no alternative.
+
+The following properties & methods have been moved to the class:
+
+- `GuildAuditLogs.Targets`
+- `GuildAuditLogs.actionType()`
+- `GuildAuditLogs.targetType()`
+
+### GuildMember
+
+ is now nullable to account for partial guild members.[^4]
+
+### IntegrationApplication
+
+_`IntegrationApplication#summary`_ has been removed as it is no longer supported by the API.
+
+### Interaction
+
+Whenever an interaction is replied to and one fetches the reply, it could possibly give an [APIMessage](https://discord-api-types.dev/api/discord-api-types-v10/interface/APIMessage) if the guild was not cached. However, interaction replies now always return a discord.js object with _`fetchReply`_ as _`true`_.
+
+The base interaction class is now .
+
+### Invite
+
+ is now a getter and resolves structures from the cache.
+
+### MessageAttachment
+
+- _`MessageAttachment`_ has now been renamed to .
+
+
+
+```diff
+- new MessageAttachment(buffer, 'image.png');
++ new AttachmentBuilder(buffer, { name: 'image.png' });
+```
+
+
+
+### MessageComponent
+
+- MessageComponents have been renamed as well. They no longer have the _`Message`_ prefix, and now have a _`Builder`_ suffix:
+
+
+
+```diff
+- const button = new MessageButton();
++ const button = new ButtonBuilder();
+
+- const selectMenu = new MessageSelectMenu();
++ const selectMenu = new StringSelectMenuBuilder();
+
+- const actionRow = new MessageActionRow();
++ const actionRow = new ActionRowBuilder();
+
+- const textInput = new TextInputComponent();
++ const textInput = new TextInputBuilder();
+```
+
+
+
+- Components received from the API are no longer directly mutable. If you wish to mutate a component from the API, use _`ComponentBuilder#from()`_. For example, if you want to make a button mutable:
+
+
+
+```diff
+- const editedButton = receivedButton.setDisabled(true);
+
++ import { ButtonBuilder } = from 'discord.js';
++ const editedButton = ButtonBuilder.from(receivedButton).setDisabled(true);
+```
+
+
+
+### MessageManager
+
+The second paramter of has been removed. The the second parameter once was is now merged into the first parameter.
+
+
+
+```diff
+- messageManager.fetch('1234567890', { cache: false, force: true });
++ messageManager.fetch({ message: '1234567890', cache: false, force: true });
+```
+
+
+
+### MessageSelectMenu
+
+- _`MessageSelectMenu`_ has been renamed to .
+
+- _`StringSelectMenuBuilder#addOption()`_ has been removed. Use instead.
+
+### MessageEmbed
+
+- _`MessageEmbed`_ has now been renamed to .
+
+- now accepts a sole object.
+
+- now accepts a sole object.
+
+- _`EmbedBuilder#addField()`_ has been removed. Use instead.
+
+
+
+```diff
+- new MessageEmbed().addField('Inline field title', 'Some value here', true);
+
++ new EmbedBuilder().addFields([
++ { name: 'one', value: 'one', inline: true },
++ { name: 'two', value: 'two', inline: true },
++]);
+```
+
+
+
+### Modal
+
+- _`Modal`_ has been renamed .
+
+
+
+```diff
+- const modal = new Modal();
++ const modal = new ModalBuilder();
+```
+
+
+
+### PartialTypes
+
+The _`PartialTypes`_ string array has been removed. Use the enum instead.
+
+In addition to this, there is now a new partial: _`Partials.ThreadMember`_.
+
+### Permissions
+
+The thread permissions _`USE_PUBLIC_THREADS`_ and _`USE_PRIVATE_THREADS`_ have been removed as they are deprecated in the API. Use _`CREATE_PUBLIC_THREADS`_ and _`CREATE_PRIVATE_THREADS`_ respectively.
+
+### PermissionOverwritesManager
+
+Overwrites are now keyed by the _`PascalCase`_ permission key rather than the _`SCREAMING_SNAKE_CASE`_ permission key.
+
+### REST Events
+
+#### apiRequest
+
+This REST event has been removed as discord.js now uses [Undici](https://github.com/nodejs/undici) as the underlying request handler. You must now use a [Diagnostics Channel](https://undici.nodejs.org/#/docs/api/DiagnosticsChannel). Here is a simple example:
+
+
+
+```ts TypeScript
+import diagnosticsChannel from 'node:diagnostics_channel';
+import { type DiagnosticsChannel } from 'undici';
+
+diagnosticsChannel.channel('undici:request:create').subscribe((data) => {
+ const { request } = data as DiagnosticsChannel.RequestCreateMessage;
+ console.log(request.method); // Log the method
+ console.log(request.path); // Log the path
+ console.log(request.headers); // Log the headers
+ console.log(request); // Or just log everything!
+});
+```
+
+```js JavaScript
+import diagnosticsChannel from 'node:diagnostics_channel';
+
+diagnosticsChannel.channel('undici:request:create').subscribe(({ request }) => {
+ const { request } = data;
+ console.log(request.method); // Log the method
+ console.log(request.path); // Log the path
+ console.log(request.headers); // Log the headers
+ console.log(request); // Or just log everything!
+});
+```
+
+
+
+You can find further examples at the [Undici Diagnostics Channel documentation](https://undici.nodejs.org/#/docs/api/DiagnosticsChannel).
+
+#### apiResponse
+
+This REST event has been renamed to _`response`_ and moved to :
+
+
+
+```diff
+- client.on('apiResponse', ...);
++ client.rest.on('response', ...);
+```
+
+
+
+#### invalidRequestWarning
+
+This REST event has been moved to :
+
+
+
+```diff
+- client.on('invalidRequestWarning', ...);
++ client.rest.on('invalidRequestWarning', ...);
+```
+
+
+
+#### rateLimit
+
+This REST event has been renamed to _`rateLimited`_ and moved to :
+
+
+
+```diff
+- client.on('rateLimit', ...);
++ client.rest.on('rateLimited', ...);
+```
+
+
+
+### RoleManager
+
+_`Role.comparePositions()`_ has been removed. Use instead.
+
+### Sticker
+
+ is now a nullable string (_`string | null`_). Previously, it was
+a nullable array of strings (_`string[] | null`_).[^5]
+
+### ThreadChannel
+
+The _`MAX`_ helper used in _`ThreadAutoArchiveDuration`_ has been removed. Discord has since allowed any guild to use any auto archive time which makes this helper redundant.
+
+### ThreadMemberManager
+
+The second parameter of has been removed. The the second parameter once was is now merged into the first parameter. In addition, the boolean helper to specify _`cache`_ has been removed.
+
+Usage is now as follows:
+
+
+
+```diff
+ // The second parameter is merged into the first parameter.
+- threadMemberManager.fetch('1234567890', { cache: false, force: true });
++ threadMemberManager.fetch({ member: '1234567890', cache: false, force: true });
+
+ // The lone boolean has been removed. One must be explicit here.
+- threadMemberManager.fetch(false);
++ threadMemberManager.fetch({ cache: false });
+```
+
+
+
+### Util
+
+_`Util.removeMentions()`_ has been removed. To control mentions, you should use _`allowedMentions`_ on instead.
+
+_`Util.splitMessage()`_ has been removed. This utility method is something the developer themselves should do.
+
+_`Util.resolveAutoArchiveMaxLimit()`_ has been removed. Discord has since allowed any guild to use any auto archive time which makes this method redundant.
+
+Other functions in _`Util`_ have been moved to top-level exports so you can directly import them from discord.js.
+
+
+
+```diff
+- import { Util } from 'discord.js';
+- Util.escapeMarkdown(message);
+
++ import { escapeMarkdown } from 'discord.js';
++ escapeMarkdown(message);
+```
+
+
+
+### .deleted fields have been removed
+
+You can no longer use the _`deleted`_ property to check if a structure was deleted.[^6]
+
+### VoiceChannel
+
+_`VoiceChannel#editable`_ has been removed. You should use instead.
+
+### VoiceRegion
+
+_`VoiceRegion#vip`_ has been removed as it is no longer part of the API.
+
+### Webhook
+
+The second parameter of no longer allows a boolean to be passed. The _`cache`_ option in should be used instead.
+
+## Features
+
+### ApplicationCommand
+
+NFSW commands are supported.
+
+### AutocompleteInteraction
+
+ has been added which is the id of the
+guild the invoked application command is registered to.
+
+### BaseChannel
+
+Added support for .
+
+Store channels have been removed as they are no longer part of the API.
+
+ has been added which is a link to a channel, just like in the
+client.
+
+Additionally, new typeguards have been added:
+
+-
+-
+-
+
+### BaseInteraction
+
+Added to check whether a given interaction can be replied to.
+
+### ClientApplication
+
+Added support for role connection metadata.
+
+### Collection
+
+- Added and .
+- Added which indicates an immutable _`Collection`_.
+
+### Collector
+
+A new event has been added which is emitted whenever an element is not collected by the collector.
+
+Component collector options now use the [ComponentType](https://discord-api-types.dev/api/discord-api-types-v10/enum/ComponentType) enum values:
+
+
+
+```diff
++ import { ComponentType } from 'discord.js';
+
+ const collector = interaction.channel.createMessageComponentCollector({
+ filter,
+- componentType: 'BUTTON',
++ componentType: ComponentType.Button,
+ time: 20000
+ });
+```
+
+
+
+### CommandInteraction
+
+ has been added which is the id of the guild
+the invoked application command is registered to.
+
+### CommandInteractionOptionResolver
+
+ now has a third parameter
+which narrows the channel type.
+
+### Events
+
+Added support for event.
+
+### ForumChannel
+
+Added support for forum channels.
+
+Added support for .
+
+### Guild
+
+Added support for which sets the guild's MFA level.
+
+Added support for . which indicates the maximum number of video channel users.
+
+Added support for . which indicates the maximum number of video channel users for stage channels.
+
+Added support for . which disables the guild's invites.
+
+Added support for the _`after`_ parameter in .
+
+### GuildChannelManager
+
+_`videoQualityMode`_ may be used whilst creating a channel to initially set the camera video quality mode.
+
+### GuildEmojiManager
+
+Added and for managing existing guild emojis.
+
+### GuildForumThreadManager
+
+Added as manager for threads in forum channels.
+
+### GuildMember
+
+Added support for .
+
+### GuildMembersChunk
+
+This object now supports the _`notFound`_ property.
+
+### GuildMemberManager
+
+Added to fetch the client user in the guild.
+
+Added and . These methods allow a single addition or removal of a role respectively to a guild member, even if uncached.
+
+### GuildTextThreadManager
+
+Added as manager for threads in text channels and announcement channels.
+
+### Message
+
+ has been added as an approximate position in a thread.
+
+Added support for role subscription data.
+
+### MessageReaction
+
+Added to make the client user react with the reaction the class belongs to.
+
+### Role
+
+Added support for role subscriptions.
+
+### StageChannel
+
+Stage channels now allow messages to be sent in them, much like voice channels.
+
+### Sticker
+
+Added support for GIF stickers.
+
+### ThreadMemberManager
+
+The new _`withMember`_ options returns the associated guild member with the thread member.
+
+When fetching multiple thread members alongside _`withMember`_, paginated results will be returned. The _`after`_ and _`limit`_ option are supported in this scenario.
+
+### Webhook
+
+Added .
+
+Added the _`threadName`_ property in which allows a webhook to create a post in a forum channel.
+
+[^1]: https://github.com/discordjs/discord.js/pull/7188
+[^2]: https://github.com/discordjs/discord.js/pull/6492
+[^3]: https://github.com/discordjs/discord.js/pull/7669
+[^4]: https://github.com/discordjs/discord.js/issues/6546
+[^5]: https://github.com/discordjs/discord.js/pull/8010
+[^6]: https://github.com/discordjs/discord.js/issues/7091