API: add function to resolve global symbol

Suggestion

🔍 Search Terms

symbol, constructor, well known, global

✅ Viability 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, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

Expose getGlobalSymbol on TypeChecker

📃 Motivating Example

TypeScript applies some special handling to global declarations, e.g. Array, Object, Function, ReadonlyArray,
The recent change to well known Symbols adds yet another special case for the global Symbol value symbol.

Currently there's no reliable way to obtain the symbol of a global declaration.

💻 Use Cases

To find out whether a type is iterable, I need to look for a __@iterable property. Previously that worked well with a hard coded string. Now I need to look up the global Symbol constructor type, get the type of its property iterator and use the escapedName for the lookup on the type in question. The first step is actually the tricky one, because there's no API for it.

There are a few workarounds I can think of:

• the hacky way: checker.getSymbolsInScope('' as any, ts.SymbolFlags.Value).filter(s => s.escapedName === 'Symbol')
• the not so obvious way:
  • find a property whose name starts with __@ since those are symbol names
  • its valueDeclaration must be a NamedDeclaration with a ComputedPropertyName
  • get the type of the computed property name to obtain a reference to the (unique) symbol type
  • getApparentType to obtain a reference to the global Symbol type
  • its symbol should hopefully always refer to the global Symbol constructor

Start with the TypeChecker API and the existing global-declaration special cases described in the issue, including Array, Object, Function, ReadonlyArray, and Symbol. Determine how a public getGlobalSymbol entry point would fit the checker API and add coverage for resolving global declarations. Done means consumers can reliably obtain the global Symbol constructor symbol without the listed workarounds.