Expose global declarations on `window`

[mhegazy]

Window in a web page serves a dual purpose. it implements the Window interface representing the web page main view, but also acts as an alias to the global namespace. All global variables are accessible on the window object at run-time; this applies to builtin JS declarations like Array, Math, JSON, Intl as well as global DOM declarations like HTMLElement, Event, HTMLCollection, etc...

TypeScript today does not model this behavior. For instance window.Math is not defined, so is all the HTMLElement family of declarations.

Most of the patterns window is used to access global declarations are anti-patterns (see a good article about window usage), the main exception is testing for API existence, e.g.: if (window.MutationObserver) { ... }. There is not really a legal way to do this out-of-the-box in TS today.

Our recommendation has been to manually add a declaration for the global object on Window, e.g.:

declare global {
    interface Window {
        MutationObserver?: typeof MutationObserver;
   }
}

This is a. inconvenient and b. not easy to find if you are new to TS. Here is a list of issues we have so far related to this issue:

• Blob property is missing on Window interface #8866 window.Blob
• ImageBitmap interface missing #14402 window.createImageBitmap
• Property Math is missing on Window interface #9325 window.Math
• URL is missing from Window interface #3753 window.URL
• MutationObserver API declarations missing #11305 window.MutationObserver
• window.PointerEvent is undefined #18756 window.PointerEvent
• Event types do not exist in the Window interface #19758 window.MouseEvent
• window.Element is a stable API, but is not included in the interface Window(lib.d.ts:19060). #23886 window.Element
• Add typings for PerformanceObserver #25651 window.PerformanceObserver

It is also worth noting that the same problem occurs with self in web workers and global for node

Possible options here:

1. support a global type (tracked by Access global as a type #14052), and allow Window to extend from it.
2. generate lib.d.ts with all global declarations mirrored on Window.

[yortus]

Can I bring up a third option? I think option 1 is the more flexible way of reducing duplicate declarations. However both options 1 & 2 have limitations:

1. supporting a global type and having Window extend it is pretty good because it is simple, and other environments (eg Global in node.d.ts) can use this too. But it would not solve the duplication problem in custom sandboxed environments, whereas the equally simple option 3 (below) would solve it.

2. generating lib.d.ts with all globals mirrored on Window - but then do other environments miss out? node.d.ts has similar duplication of declared globals with the Global interface, and then there are web workers, custom environments, etc.

A third option would be a declaration that tells the compiler to augment the global environment with all the declarations in a particular interface. Eg declare global extends Window for lib.d.ts, declare global extends Global for node.d.ts, etc.

This is similar to option 1 but in reverse, and allows additional scenarios like sandboxing. An example of this scenario is given in #10050 (comment). Note that if option 1 was used, then there would be no way to write a set of declarations that are just a normal interface in the host code but are are globals in the sandboxed code. They would all still have to be duplicated.

Custom environments may be niche, but it would be nice if the mechanism chosen here would work for them too.

[michahell]

window.Worker, same story...