Why is X changing to Y in discord.js v14?

[suneettipirneni]

Now that the working list of breaking changes for v14 have been made available, there's been a lot concerns focusing on the why of the breaking changes. Some have suggested that they're unneeded and unnecessary. However like most things it's not that simple. I understand that no one likes to refactor their code for breaking change. I develop a bot, and going through and updating symbols in my code isn't what I would consider "enjoyable". I understand the frustration of this process. Nonetheless none of us are making changes just to make the change-log fluffier, there's always a reason, and some reasons are larger than others.

Why are you no longer accepting strings for enum values, also where did the old enums go?

This can be answered quite plainly: because we don't want to keep handling different cases of input where we don't feel we need to. Enums are structures that constantly change within the discord API, this in turn means discord.js also needs to keep up with those changes.

Did you know that in v13 and lower we were maintaining up three different declarations of enums?

• One for the javascript source in discord.js
• One for the types within enums.d.ts
• One for the types within discord-api-types

Obviously this wasn't the best for maintainability. Ideally we could have one centralized place, a single source of truth if you will. So we decided that the best way forward was to have our source for enum come from 'discord-api-types'.

Ok, but this doesn't answer the question as to why we can't use strings anymore. When it comes to accepting both numbers and strings there's problems that many people may not be aware of.
Here's an issue I discovered several months ago:

In typescript negating against a given enum type wouldn't work as expected:

if (button.style !== 'LINK') {
  console.log(button.customId); // Error: `customId` doesn't exist on type ButtonData | LinkButtonData
}

Wait what? Why doesn't this work? I've properly narrowed the type?
This is a nasty pitfall caused because you forgot to also check if the type wasn't equal to Constants.ButtonStyle.LINK. This pitfall occurred in many places and it led to many issues where users were simply confused as to why their types weren't resolving as expected.

In addition to the outside effects of supporting both strings and enums there were many internal effects. For example it's extremely easy for a contributor to miss the case where they're supposed to check for a string, or the inverse where they're supposed to check for a number. Once again I'd like to reiterate this is a poor setup in terms of code maintenance. There's another aspect that wasn't covered: performance.

Interactions, messages, channels are constantly being serialized from the gateway events in discord.js. This is especially true for large bots that occupy thousands of servers. Discord.js constantly introduced if branches for checking enum types because of they could either be a string or number. Some of our transformers were creating new objects to translate the enums. As you can imagine this has a negative affect on performance. We received an issue ticket about the particular issue, asking if we could make enum transformations optional: #6136.

But you're also making builders slower?

Sorry if this wasn't made clearer earlier, but we'll be introducing Unsafe variants of builders that have the same performance of the previous discord.js builders just without validation.

Unsafe builders have landed.

So what about the builder renames?

Contrary to popular belief, the builder renames have more to do with the elimination of future class proliferation, rather than just making another aesthetic change. Let's take the Message* components for an example:

We have

• MessageActionRow
• MessageSelectMenu
• MessageButton

Alright this is great, I prefixed all my classes with Message because they can't be used anywhere else! Right!...Right? Well no, because discord adds a new feature to the API where components can be used in more than one place. If you're not aware what I'm getting at, I'm talking about modals. With modals you can have action rows within them. Ah ok! I know the solution I'll add a new class: ModalActionRow!. I soon realize that a ModalActionRow nearly identical to a MessageAction row. As a result I've added redundant code to the codebase just because my naming model isn't flexible. Discord has also confirmed that select menus will be available in modals, so even more redundant proliferation of classes.

How would one avoid this situation? The answer is simple: make the naming conventions more agnostic. That's exactly what we did. Instead of having six different classes that support both modals and messages, we can instead have 4 agnostic classes that work or can work in both styles if needed. Basically use the agnostic classes in more areas rather than introduce new classes for each area.

Conclusion

This is all I have so far, and I'll most likely add more as time moves on. If anyone has any questions or concerns about the breaking changes please leave a reply in this discussion and we can discuss it.

[meister03]

The points are quite understandable.
V13 encouraged the usage of Flags.
Although they have not been used on the Button Builders nor on Application Commands. Instead it was preferred to use STRING, `PRIMARY' . Now it has to be changed.

It would be good, when the upper things are thought before designing sth.

[ImRodry]

In addition to the outside effects of supporting both strings and enums there were many internal effects. For example it's extremely easy for a contributor to miss the case where they're supposed to check for a string, or the inverse where they're supposed to check for a number. Once again I'd like to reiterate this is a poor setup in terms of code maintenance. There's another aspect that wasn't covered: performance.

Interactions, messages, channels are constantly being serialized from the gateway events in discord.js. This is especially true for large bots that occupy thousands of servers. Discord.js constantly introduced if branches for checking enum types because of they could either be a string or number. Some of our transformers were creating new objects to translate the enums. As you can imagine this has a negative affect on performance. We received an issue ticket about the particular issue, asking if we could make enum transformations optional: #6136.

I understand the performance implications this has, but I also think this makes using any structure with a type harder, as we now have to check the docs to see what type 20 means, instead of just having a name from which we can easily deduce what it means. For situations where you want to check for a specific structure type this is not an issue of course, as you can simply do structure.type === StructureTypes.WhateverTypeYouWant, but if you're going through structures and checking their types to see which one you need for your code, this becomes significantly harder. Was this thought of?

Also, I believe the biggest elephant in the room that wasn't addressed here, which is the fact that builders no longer support the camelCase we know and love. I recently refactored my whole bot to use discord.js builders by providing a data object in the constructor instead of executing subsequent functions which I found to be less efficient and logical. This is because, when you create an instance of a builder, you're passing the values you want initially, and you can later change them using the functions, which is a perfectly valid use case. builders didn't initially support camelCase as it was intended to be used with /rest and not discord.js directly (at least what I understood), and thus the data needed to be transformed in an API-friendly way. I believe all builders should support camelCasing (along with snake_case) in the constructor and they should convert those properties later on so that they can be passed to the API in the way that it expects them to be passed.

[suneettipirneni]

I tried to clarify that I was not talking about enum usage in the original message, so let me rephrase. By converting all types into numbers, if we're trying to see what type a structure has, we'd be looking directly at the structure, and not comparing it with anything else, meaning that if we have type: 20 in it, we will have to check the docs, whereas before we could simply read the string and understand what the type was. This is for situations when you are not using an enum, and just looking at the type property of a structure.

Is till don't understand what you're getting at. The type marked on the structures and methods is the enum type not the number. We have all recommended multiple times that people stay away from magic numbers.

I understand it made type checking harder, which is why typeguards were implemented in most cases. What I'm saying is that having a "magic number" is harder for someone not familiar with Discord's types to figure out what it means, which didn't happen before, forcing the developer to go hunt for the enum on the docs.

Magic numbers were possible in v13 nothing was stopping anyone from using them. And I'll reiterate we don't recommend using magic numbers as a replacement for enums. You summarized the issues with using magic numbers pretty well.

Me being the only person bringing this up surely isn't an argument as there aren't nearly enough people using the dev versions to have an idea of the impact of any change so far, so I'm sure this will become a more evident issue once public release comes. I still don't understand why you call this "mixing and matching" as this saves performance by avoiding the totally unnecessary checks builders has (yes I know an option is coming, but still setting all data at once is better than calling functions over and over) and this is the way that the library implements these builders. I don't think you should offer support for passing an object in the constructor and then have that be the only thing that accepts snake_cased properties only. My goal is not to use a plain object, as I still want to take advantage of the functions, but only in the situations where they make sense, and not when declaring the variable for the first time, as that would be a waste of time, specially in bigger bots like you mentioned.

Ok fair, the one-person argument is a bit of a stretch.

I say mix and match, because you're mixing the builder syntax with the json syntax. You also questioned why have the option in the constructor if it only accepts snake_case. In another conversation I had exclusively with you I stated that the main use of the constructor for the builders was so djs could serialize incoming API data, it was never built for around the user providing varying user json inputs. In addition, we would like to avoid builders depending on djs types, as that would cause a circular dependency.

[monbrey]

By converting all types into numbers, if we're trying to see what type a structure has, we'd be looking directly at the structure, and not comparing it with anything else, meaning that if we have type: 20 in it, we will have to check the docs, whereas before we could simply read the string and understand what the type was.

I can't quite imagine a use case where someone has no idea what type a structure is, but also doesn't know what type they want to check it to be. Are you able to provide an example?

Even then, assuming you're doing something like console.log(structure.type); // 20 and seeing the number, console.log(StructureType[structure.type]) will give you a string - pending a discord-api-types release I'm told, doesn't work with the current const enums.

[ImRodry]

I say mix and match, because you're mixing the builder syntax with the json syntax. You also questioned why have the option in the constructor if it only accepts snake_case. In another conversation I had exclusively with you I stated that the main use of the constructor for the builders was so djs could serialize incoming API data, it was never built for around the user providing varying user json inputs. In addition, we would like to avoid builders depending on djs types, as that would cause a circular dependency.

I know the constructor is there to allow for serialization of API data, however you have to take into account that people will use that given the possibility. Despite all the guides doing it in one way, doesn't mean other people, like myself, won't find another way they prefer and use. And it's not like the constructor is private so it is meant to be used and should work just like it did in v13, otherwise you'd be simply breaking for the sake of breaking without any advantage (and I'd even argue there are way more disadvantages to using builders as opposed to discord.js's classes).
As for the DJs types, we don't need to use them, we can declare them in /builders itself and use them there, no need to re-export. Either that or discord.js could export a class that extends builders and adds support for camelCasing, that way we could use discord.js's types freely.

I can't quite imagine a use case where someone has no idea what type a structure is, but also doesn't know what type they want to check it to be. Are you able to provide an example?

When I say structure I'm referring to any structure in general. Of course you know if it's a Message or a Channel, what I'm trying to describe is a scenario where you want to find out the type of Message or type of Channel.

Even then, assuming you're doing something like console.log(structure.type); // 20 and seeing the number, console.log(StructureType[structure.type]) will give you a string - pending a discord-api-types release I'm told, doesn't work with the current const enums.

While that is true now, that's another thing developers have to keep in mind when debugging, when it could be done in discord.js through the use of a getter that converts the type to a string and passes it to the user when accessing it, while also keeping it stored as a number internally. This way you'd only use strings for output, never input.

[monbrey]

While that is true now, that's another thing developers have to keep in mind when debugging, when it could be done in discord.js through the use of a getter that converts the type to a string and passes it to the user when accessing it, while also keeping it stored as a number internally. This way you'd only use strings for output, never input.

Any half-decent developer should know that the type is an enum and convert it or look it up while debugging, however they choose to translate it.

I'm guessing the getter would be something like get type() { return StructureType[this._type]; } or something, which hey, I think conceptually is probably fine, if a little added bloat. I don't think it helps the level of developer who wouldn't already know how to lookup an enum though, since they're probably just going to console.log the whole object. Which of course, wont show any getters.

I feel like this is getting into fairly unrealistic examples or is simply another case of subjective opinions on what "cleaner" code is. As I've said before, if the bot developer's code being shorter is "cleaner" then by that same measure, we must have made discord.js "dirtier". All it does is move the necessary conversion somewhere else.

[kyranet]

Before you go far into that, getters are by default non-enumerable, which causes util.inspect to not display it unless you pass extra options (or change the default options).

Although debuggers will display the getter once the object is expanded, not sure if you can display the value because at least Dev Tools doesn't.

[sebastianjnuwu]

interesting

[oMvhmoud]

agreed.