In "declare global" blocks, allow access of block-scoped variables in globalThis

[DanKaplanSES]

🔍 Search Terms

globalThis, declare global block, let, const, var, property

✅ Viability Checklist

• 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 isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

This wouldn't be a breaking change in existing JavaScript code. When it comes to TypeScript code, I'm not as sure...

Before my request, here's an excerpt of #30477 for context:

TypeScript Version: 3.4.0-dev.20190316

Search Terms: 3.4 globalThis let const property

Code

// Compile with `tsc -t es2015`
const foo: number = 42;
const bar: null = globalThis.foo; // Type 'number' is not assignable to type 'null';

For reference, the following demonstrates how these bindings behave in browser and node, respectively:

<script>
const foo = 42;
alert(window.foo); // --> "undefined"
</script>

const foo = 42;
console.log(global.foo); // --> "undefined"

Expected behavior: TypeScript models types consistently with what's actually happening in VMs. Specifically, variables bound by let or const are not translated to properties on globalThis.

Actual behavior: TypeScript converts let/const bindings onto properties of globalThis, but these properties do not exist in ES2015+ output (when let and const are retained in the output).

The example and fix makes sense to me and I'm not requesting a change for that. But is there any chance #30510 / #30477 could work the way it used to within declare global blocks? In other words, I'm requesting for all of this code to compile:

export {}

declare global {
  const c: string;
  let l: string;
  var v: string;
}

globalThis.c = "s";  // errors: Property 'c' does not exist on type 'typeof globalThis'.
globalThis.l = "s";  // errors: Property 'l' does not exist on type 'typeof globalThis'.
globalThis.v = "s"; // compiles

📃 Motivating Example

The examples in the #30477 excerpt make sense to me because they're analogous to runtime behavior. e.g., I can intuit const foo: number = 42; shouldn't exist on globalThis.

But declare global { ... } doesn't exist at runtime in at all. It's a part of TypeScript that's erased at transpile. So if this is TypeScript-only, and it's named "declare global," I would assume my consts and lets apply to global scope.

Well it does.

Sometimes.

As a newb, it feels kind of arbitrary. For example, this code compiles like I would expect:

export {}

declare global {
  interface Window {
    foo: number;
  }

  function Y(): void;
}

globalThis.window.foo;
globalThis.Y();

And if I remove globalThis from my first example, it behaves the way I would expect:

export {}

declare global {
  const c: string;
  let l: string;
  var v: string;
}

c = "s";  // Cannot assign to 'c' because it is a constant.
l = "s";  // compiles
v = "s"; // compiles

So, it's conditionally global?

This stack overflow post shows some conversation around this topic..

💻 Use Cases

1. What do you want to use this for? I want it to be easier to learn how to declare global types.
2. What shortcomings exist with current approaches? I think the current approach is nuanced and behaves in unexpected ways.
3. What workarounds are you using in the meantime? I refer back to these links whenever global variable declarations don't work the way I expect

[andrewbranch]

Maybe someone will discover a reason that I’m wrong, but I think this is just a bug.

[Josh-Cena]

déclare global means it's declared in a global scope (i.e. not inside a module, but inside a script, or indirect eval code). You should see declare global blocks as separate script declaration files (you can also create such declarations by not having any import/exports), which is why they are not allowed in ambient declarations because that would be redundant. However, let/const globals DO NOT become properties on globalThis; being able to access them via globalThis is a soundness error. The current behavior perfectly mirrors what happens at runtime. Global function and var declarations do become properties on globalThis at runtime.

[fatcerberus]

Shouldn’t the second case (where the variables are accessed without globalThis qualification) be an error too then, since they are declared in a script context but the access occurs in a module context?

[Josh-Cena]

Module scopes are child scopes of script scopes (which are a.k.a. the global scope).

[fatcerberus]

That doesn't really make sense to me - there's no analog for that kind of nesting (i.e. a module nested in a script scope such that it has access to the script's let/const vars) in native ECMAScript, is there?

[Josh-Cena]

I'm not sure what you mean by "native ECMAScript". ModuleEvaluation and ScriptEvaluation are both top-level operations invoked by the host only, so you need a host to test them out, let it be Node or HTML. You never have access to the script scope in Node, but you can easily do this in HTML:

<script>
const a = 1;
</script>
<script type="module">
console.log(a);
</script>

If it interests you: https://tc39.es/ecma262/multipage/ecmascript-language-scripts-and-modules.html#sec-runtime-semantics-scriptevaluation, https://tc39.es/ecma262/multipage/ecmascript-language-scripts-and-modules.html#sec-source-text-module-record-initialize-environment

BTW, the "nesting" does not happen in a lexical sense. It's merely that each time a script is evaluated, it directly uses the global scope, while when each module is evaluated, it creates a new scope that inherits from the global scope. There's no closures.

[fatcerberus]

Oh, I was reading it as, the const was scoped only to the file it occurred in while var and function goes on globalThis. I never knew it was possible to have a truly global variable that nonetheless wasn't a property of globalThis; that's... kinda confusing.

[Josh-Cena]

Cross-script boundaries are totally weird: a declaration will be visible for any subsequent script, but it is only visible to preceding code within its current script.

<script>
console.log(a); // Cannot find variable
</script>
<script>
console.log(a); // undefined
var a = 2;
</script>
<script>
console.log(a); // 2
</script>

[DanKaplanSES]

@Josh-Cena I'm in the process of writing a response to your first reply, but it may take a few days before I have the time to complete it.

@fatcerberus

<script>
const a = 1;
</script>
<script type="module">
console.log(a); // logs `1`
console.log(globalThis.a); // logs `undefined`
</script>

Oh, I was reading it as, the const was scoped only to the file it occurred in while var and function goes on globalThis.

Same! That's blowing my mind. I thought console.log(a); would log undefined, but it logs 1.

I also expected the following to "blow up," but it logs 5 and undefined, respectively:

<!DOCTYPE html>
<html>
  <head>
    <script>
      const a = 1;
    </script>
    <script type="module">
      const a = 5;
      console.log(a); // logs `5`
      console.log(globalThis.a); // logs `undefined`
    </script>
  </head>
  <body></body>
</html>

I assume this works because of what @Josh-Cena mentioned earlier:

each time a script is evaluated, it directly uses the global scope, while when each module is evaluated, it creates a new scope that inherits from the global scope.

That said, even though this runs (on Firefox, at least), Visual Studio code complains about the second const: Cannot redeclare block-scoped variable 'a'. Is that a VS Code bug?

This code, on the other hand, errors at runtime:

<!DOCTYPE html>
<html>
  <head>
    <script>
      const a = 1;
    </script>
    <script type="module">
      const a = 5;
      const a = 6; // error! Uncaught SyntaxError: redeclaration of const a
      console.log(a);
      console.log(globalThis.a);
    </script>
  </head>
  <body></body>
</html>

I never knew it was possible to have a truly global variable that nonetheless wasn't a property of globalThis; that's... kinda confusing.

I knew this was possible in TypeScript after finding this StackOverflow post, and it certainly surprised me. But until now, I didn't realize that applied to JavaScript too.

[fatcerberus]

Yeah, TS is just JS with compile-time types (plus a few value-add runtime features that got grandfathered in). So const has the same semantics in TS as in JS (or at least is supposed to).

[DanKaplanSES]

@fatcerberus

Yeah, TS is just JS with compile-time types (plus a few value-add runtime features that got grandfathered in). So const has the same semantics in TS as in JS (or at least is supposed to).

Ah, I meant something slightly different. From that SO post:

On the other side, the following is possible, but the result is different:

export {}

declare global {
  let someLetString: string
  const someConstString: string
}

This only adds types for the following handles:

someLetString
someConstString

[As opposed to window.someLetString and/or globalThis.someLetString]

Although the ts compiler complains about window.someLetString and/or globalThis.someLetString not existing, I mistakenly assumed that during JS runtime, they would evaluate to the same value.