Homogenise null and undefined typings within djs APIs

[noftaly]

Which application or package is this feature request for?

discord.js

Feature

Often when using discord.js APIs together, types are incompatible because of undefined/null discrepancies. This is very irritating and hurts DX because you would expect that using discord.js APIs together would "just work" and would not require you to resort to hacks.
Examples

1. Embed Builder:

new EmbedBuilder()
  .setAuthor({
    name: myText,
    iconURL:     member.user.avatarURL(),
//  ^^^^^^^                  ^^^^^^^^^^^
//  string | undefined       string | null
  })

2. Last Message ID

 await message.channel.messages.fetch({
   before: message.channel.lastMessageId
// ^^^^^^                  ^^^^^^^^^^^^^
// string | undefined      string | null
 })

Probably many other ones. Those were just examples, the main problem is that for class properties | null is mainly used, but for option objects prop?: type is mainly used, which makes it undefined | type.

This is a problem because it results in a Typescript compiler error.

Ideal solution or implementation

The easiest option would be to have all Options objects with optional properties to also accept nulls, which afaict wouldn't be breaking (?) because you don't explicitly check for undefined values.

I haven't looked in other places, but at least accepting nulls in option objects would probably remove 95% of the problems (or of the common problems) faced by djs users.

Alternative solutions or implementations

You could also just ignore this problem as it is easily fixable by asserting not-null (!) to make Typescript happy, or by adding ?? undefined which would also fix the problem by making Typescript happy with a solution that makes it through runtime and not just compile time.

Other context

Debates over the use of null / undefined:

• Against the use of null: Intent to stop using `null` in my JS code sindresorhus/meta#7
• Against the use of undefined: https://eslint.org/docs/latest/rules/no-undefined

Utilities from Sapphire to handle both undefined/null together (aka Nullish) : isNullish and Nullish type alias

[didinele]

👎 Most of those type choices are deliberate, especially when it comes to patching data. undefined/missing implies no changes are meant for the property, while null can have special functionality.

I suppose there are cases and structures where this isn't necessarily a problem, but I feel like all things considered, it'd be a downgrade to change it in specific areas and cause an inconsistency all together.

[noftaly]

I know that and completely agree, but i don't think that (generally speaking from the patterns i could see) returning null from getters/methods and accepting undefined in option objects/inputs is a viable option. I definitely hurts user experience and end-code readability in many ways. The solution for that isn't perfect but I do believe it is a small price to pay for DX.

The single source of truth with the deliberate choices you are talking about could still be the docs or dapi-types, but the user-facing API could be polished by abstracting the null/undefined differences away.

[didinele]

It's unclear to me how much we can improve this without compromising functionality regardless, but returning undefined where possible is on the table and something we've been thinking of.