Documentation: usage of types/interfaces defined in modules on global

Search Terms

• export from module to global
• global namespace
• declare as global
• assign to global
• globalThis

Suggestion

Documentation says that

It can be surprisingly difficult to access or declare values in the global scope, perhaps because we’re writing our code in modules...

(https://devblogs.microsoft.com/typescript/announcing-typescript-3-4/#type-checking-for-globalthis)

It shows an example how typed variable may be declared in the global scope. But it doesn't cover scenario when one needs to declare variable/function/namespace which use a type/interface declared in some module.

I think that the documentation should clearly explain that it's not possible or show an example how to do it (if it's possible).

Use Case

One creates a function with input parameter and/or return type declared in module.
She wants to make this function available on global.

It's an anti-pattern in the same way as augmenting types from external modules, but as discussed here #5292 it exists in real life.

One may have a well organised non-poluting-global modules-based codebase. But at some point by some reason she have to provide an interface for a global consumer. Moving all exposed interfaces and types to global and rewrite the codebase which used to consume them from modules would be ugly and painful.

Example

import { SomeType, SomeInterface } from 'some/module';

function functionForGlobalConsumer(input: SomeType): SomeInterface {
  // some code...
}

globalThis.functionForGlobalConsumer = functionForGlobalConsumer;

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

Start with the TypeScript 3.4 globalThis documentation example linked in the issue and reproduce the shown imported-type scenario. Determine whether the documentation should describe a supported pattern or a limitation, then update the relevant global-scope guidance with a clear example or explanation and verify that it addresses the stated use case.