Repository: TypeScript
Issue: Suggestion: optional globals
Labels: Suggestion,Awaiting More Feedback

<!-- 🚨 STOP 🚨 𝗦𝗧𝗢𝗣 🚨 𝑺𝑻𝑶𝑷 🚨

Half of all issues filed here are duplicates, answered in the FAQ, or not appropriate for the bug tracker.

Please help us by doing the following steps before logging an issue:
  * Search: https://github.com/Microsoft/TypeScript/search?type=Issues
  * Read the FAQ, especially the "Common Feature Requests" section: https://github.com/Microsoft/TypeScript/wiki/FAQ

-->

## Search Terms

<!-- List of keywords you searched for before creating this issue. Write them down here so that others can find this suggestion more easily -->

## Suggestion

Extracted from this related issue: https://github.com/microsoft/TypeScript/issues/21965

Currently TypeScript has no way to represent a global which may or may not exist at runtime.

For example, given a global called `foo`, we can only define it as:

```ts
declare global {
  const foo: number;
}
```

But what if `foo` does not always exist?

We can't define it as `T | undefined` because this does not reflect the runtime behaviour. `T | undefined` means "this will be declared but its value might be `undefined`", but the global may not be declared at all, in which case any references would result in `ReferenceError`s at runtime.

```ts
declare global {
  const foo: number | undefined;
}
```

```ts
// TypeScript is happy for us to reference this. There's no compile error.
// The type is `number | undefined`.
// At runtime, if the global doesn't exist, we'll get a `ReferenceError` 😒
foo;
```

If there was a way to mark a global as optional, TypeScript would require a proper guard (`typeof foo !== 'undefined'`) before it can be safely accessed. This way, TypeScript is alerting us to the possibilty of a runtime exception.

```ts
declare global {
  // example syntax
  const foo?: number;
}
```

```ts
// Compile error 😇
// Runtime exception 😇
foo;

if (typeof foo !== 'undefined') {
  // No compile error 😇
  // No runtime exception 😇
  // Type is `number`
  foo;
}
```

## Use Cases

Examples of "optional globals" below.

In code that is shared between a client (browser) and server (Node):

- `window` will only exist during the client runtime
  ```js
  typeof window !== undefined ? window.alert('yay') : undefined;
  ```
- `global` and `require` will only exist during the server runtime
    ```js
  typeof process !== undefined ? process.env.FOO : undefined;
  ```

In code which may or may not be under test using [Cypress](https://www.cypress.io/), the global `Cypress` will only exist during runtime when the code is under test.

```js
const getEnvVar = key => typeof Cypress !== 'undefined' ? Cypress.env(key) : process.env[key];
```

## Examples

See above.

## Checklist

My suggestion meets these guidelines:

* [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
* [x] This wouldn't change the runtime behavior of existing JavaScript code
* [x] This could be implemented without emitting different JS based on the types of the expressions
* [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
* [x] This feature would agree with the rest of [TypeScript's Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).