Split the ES5 library definitions into their own files

[iainjreid]

TL;DR

Along the same lines as the suggestion put forward in #39255, I'd like to float the idea that the definitions held in lib.es5.d.ts be split up into their own individual files. I'd like to suggest this change to enable granular overrides (thanks to #45771) to the core library definitions, without having to copy the entire ES5 library in the process.

🤔 Problem

I'm working on a project at the moment that would benefit from some aggressive tweaks to the Promise definition(s) in lib.es5.d.ts and lib.es2015.promise.d.ts. For clarity, these changes involve typing the rejection path of all promises, and enforcing .catch in some instances. I'm aware that a change similar to this has been thoroughly discussed and declined for good reasons in the past.

As mentioned above, thanks to #45771 we're now able to override the core library definitions as and when required. However, to heavily augment, or otherwise redefine the very lowest definitions of any type in the core library, one must (in the case of lib.es5.d.ts) redefine the entire ES5 library, opening up a small can of worms in the process (licensing of the types, and tracking changes in the "source" copies of the types, to name a few).

💡 Solution

The simplest solution I can see is to split up lib.es5.d.ts into individual files that can then be later overridden by upstream developers as they see fit. lib.es5.d.ts would become a barrel file referencing the these "new" definitions, thereby avoiding any nasty braking changes.

In terms of approach, I would imagine declaring each primitive (or otherwise major feature of ES5) in its own definition file would make the most sense. This would offer a very high level of customization for the end developer, for an overall low maintenance cost at both ends.

In terms of format, the work has been done already with the more modern lib.es20xx.<feature>.d.ts naming pattern. Following this would result in a structure similar to the below for our good old friend, ES2009:

lib/
├─ lib.es5.d.ts
├─ lib.es2009.object.d.ts
├─ lib.es2009.global.d.ts
├─ lib.es2009.string.d.ts
├─ lib.es2009.number.d.ts
└─ ... ect ...

I'll follow this ticket up with a PR containing an initial implementation of the above 👍

[andrewbranch]

See also #45602

[iainjreid]

After some exploration, I've drafted the changes I originally proposed above in the hope that this might get the ball rolling on this feature suggestion.

Something that did occur to me whilst writing the code in the linked PR (that I think would solve the problem I'm facing in a much more elegant way) would be the ability to not only overwrite the inbuilt libraries, but to also patch them.

Doing so would likely be easiest through the use of git patches exposed to the TS server under the @typescript/[lib] dependencies, which using the same mechanic implemented under #45771 would be applied on top of the default libraries before processing any code.

Obviously I could achieve this goal somewhat loosely by using something like patch-package, but I feel that silently patching a dependants node_modules on install without their knowing is a little shady...

Any suggestions, feedback, or comments would be hugely appreciated!