Suggestion: optional globals

[OliverJAsh]

Search Terms

Suggestion

Extracted from this related issue: #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:

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 ReferenceErrors at runtime.

declare global {
  const foo: number | undefined;
}

// 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.

declare global {
  // example syntax
  const foo?: number;
}

// 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

  typeof window !== undefined ? window.alert('yay') : undefined;

• global and require will only exist during the server runtime

  typeof process !== undefined ? process.env.FOO : undefined;

In code which may or may not be under test using Cypress, the global Cypress will only exist during runtime when the code is under test.

const getEnvVar = key => typeof Cypress !== 'undefined' ? Cypress.env(key) : process.env[key];

Examples

See above.

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.

[OliverJAsh]

Something else to consider: as well as marking individual globals as optional, we might also need a way to specify a group of globals as being optional.

In the example of code that is shared between client/server:

• all globals inside of the dom lib must be optional (i.e. Window)
• all globals inside of the @types/node types must be optional (i.e. NodeJS.Global)

Ideally, the implicit global type would work just like a tagged union:

Global = Window | NodeJS.Global

… and checking for the presence of properties in the union would narrow the implicit global type so that other properties can then be accessed without extra guards:

window; // Compile error 😇 
alert; // Compile error 😇 
addEventListener; // Compile error 😇 

if (type window !== 'undefined') {
  window; // No compile error 😇 

  // We checked for the existence of `window`, so other globals must also exist now
  alert('foo'); // No compile error 😇 
  addEventListener('load', () => {}); // No compile error 😇
}

In the meantime I'm simulating this by defining an alias:

type Env = typeof window | NodeJS.Global;

const hasWindow = typeof window !== 'undefined';

const env: Env = hasWindow ? window : global;

const checkIsEnvWindow = (_thisEnv: Env): _thisEnv is typeof window => hasWindow;

env.alert; // Compile error 😇
env.addEventListener; // Compile error 😇

if (checkIsEnvWindow(env)) {
  env.alert('foo'); // No compile error 😇
  env.addEventListener('load', () => {}); // No compile error 😇
}

The downside of this approach is that it relies on discipline—anyone can still reference/use the types for window and global.

[jeysal]

I think this is a very relevant feature as more people are starting to write universal code. But to actually contribute something to the discussion:

I think this shouldn't be viewed as being about globals, but rather about declaration merging on any module or global in general.
Imagine I write type definitions changing a Node.JS core module, because it has an experimental API, or something patched onto it, but I cannot assume that it is present and also need to support "plain" Node.
Conceptually, I want my whole declare block to be "optional", meaning every property in it must become a union of the property on the original module as if the declaration was not applied, and of the property with the declaration applied.

I don't know a lot about the TS codebase and realize this may be harder to implement than plain optional properties in a declare global block, but from a type system perspective it seems possible, and I believe "optional declare blocks" could be a relatively easy-to-use solution for this.

[mvasin]

In each of the environments (browser / Node), a global is either always present or always absent. In that sense, the word "optional" may not exactly be a perfect fit. I would love to come up with the better DX ergonomics, but to play devil's advocate, shouldn't we suggest to have separate tsconfigs for each environment, and do separate type checks for each environment? That wouldn't require changes on the TS side: one --noEmit run for Node, then with-emit run for browser. It is a bit cumbersome, but at the same time, it is a fair and accurate separation.

[OliverJAsh]

@mvasin What about the editor experience though? VS Code (for example) would need to choose which one of the TS configs to use. You might be able to compose multiple projects into one using project references, but then I'm still not sure the editor experience would be what we want, as outlined in an example above: #36057 (comment). If I'm viewing a code file which is used in Node and in the browser, I should get an error if I try to use window/global, but as soon as I add a guard that error should disappear.

[mvasin]

Good point, editor experience should be straightforward.

[felix9]

Separate tsconfigs are not sufficient to solve this problem. Say I write something like:

export function lowByte(value: number|bigint|BigInt): number {
    if (typeof BigInt !== 'undefined' && (typeof value === 'bigint' || value instanceof BigInt)) {
        return Number(BigInt.asUintN(8, value as bigint));
    } else {
        return (value as number & 0xff);
    }
}

The function is intended to work on all browsers, whether or not they have BigInt.

All the uses of BigInt here are safe, because they're guarded by the test for existence of BigInt.

In order for this to type-check, I need the declaration of BigInt in scope.

However, adding lib.es2020.bigint infects the entire compilation. Any other code can use BigInt without an existence guard, and it will pass typecheck but throw at runtime.

I haven't found any way to prevent BigInt from infecting the entire compilation, other than duplicating the typedef for BigInt locally in the module that uses it. This gets ugly when the optional global has complicated interfaces, such as Promise.