"declare global" affects all compiled modules even when the source file is in "module" mode

[Nipheris]

TypeScript Version: 2.8.0-dev.20180314

Search Terms: global declarations, ambient context.

Code

a.ts

declare global {
    interface Window {
        someGlobalVar: number;
    }
}
window.someGlobalVar = 10;
// to turn on "module"-mode for this file
export const unusedExport = 100500;

entry.ts

import './a';
console.log(window.someGlobalVar); // 10 as expected

entry2.ts

console.log(window.someGlobalVar); // `undefined`, but type is `number`

tsconfig.json

{
  "compilerOptions": { "strict": true },
  "files": ["entry.ts", "entry2.ts"]
}

Expected behavior:

Error in entry2.ts about undeclared member.

Actual behavior:

No errors.

If we comment out the import './a'; in entry.ts, compilation fails with the following errors in BOTH modules (as expected):

entry.ts(2,20): error TS2339: Property 'someGlobalVar' does not exist on type 'Window'.
entry2.ts(1,20): error TS2339: Property 'someGlobalVar' does not exist on type 'Window'.

But if we import a.ts in the first entry file, both errors disappear, so, using the import in the first entry module produces side effects on the second one. This is a bit surprising that declare global produces such side effects even when source file is in "module" mode. It leads to the mismatch between declared types and the other side effects like window.someGlobalVar = 10.

A global variable is accessible in every scope. You don't have to import global variables. If you want a variable to only be available when you import a module, use export instead of declare global.

The reason at least one import of the module is required is that if the module isn't included in compilation at all, the global never gets declared. But once the global is declared it can be accessed from anywhere.

[timocov]

If you want a variable to only be available when you import a module, use export instead of declare global.

@Andy-MS but what if you want to extend some interface/class/namespace (from global scope or from some other module)? For example like in rxjs.

Seems that declare module works very similar to declare global.

@timocov That example is a module augmentation. It modifies a different module than the current one, so you're right that it's global in effect, i.e. you don't have to import the augmenter to see the effect in the augmented module.

[timocov]

i.e. you don't have to import the augmenter to see the effect in the augmented module.

In the example of "Module Augmentation" augmenter is imported explicitly:

// consumer.ts
import { Observable } from "./observable";
import "./map";

and I believe this is correct if we want do not have ReferenceError in run-time. But currently seems that TypeScript does not check that you import it before use in current module and it may be a reason of run-time errors.

[Nipheris]

@Andy-MS Consider this import clause: import "./map". The language handbook and MDN says that we should use such import to ensure that side effects of the module are applied. Obviously, we can not rely on this if we do not import the module (because the module system does not guarantee that this module is already loaded and executed).

But the type system behavior is different. Compiler assumes that if the module was ever built (and the "declare global" or "declare module" statement in this module is parsed and applied during build), then the side effects are applied too, without any alignment with the module loading in runtime.

So, we end up relying on side effects in all the modules even if we do not explicitly import the module producing that side effects.

@Nipheris That's unfortunate, but the compiler doesn't always analyze the order things are executed in anyway:

f();
function f() {
    console.log(x);
}
const x = 0;

This code will type-check but fail at runtime (assuming you target --esnext; in es5 we emit a var which is undefined if not initialized). In general, we check for the existence of a value but not for the time when it's actually set. We're smarter about local variables (can't write console.log(y); const y = 0;), but that's about as far as it goes.

[typescript-bot]

Automatically closing this issue for housekeeping purposes. The issue labels indicate that it is unactionable at the moment or has already been addressed.