Provide flag for projects to ban compile-time side-effects in root files

Search Terms

• pure
• side-effects
• elision
• global-modifying

Suggestion

A new tsconfig flag should be added that bans compile-time side-effects in project root files. This idea was originally proposed by @andrewbranch in response to an external pull request. The flag name can be discussed further, but examples might be noTypingSideEffects, noGlobalModifyingModules, noCompileTimeSideEffects, pure etc. The phrase "compile-time side-effects" refers to anything that can affect type-checking dependent source files outside of the standard export syntax.

The TypeScript features that allow source files to modify typing information outside of their file scope include the following:

• ambient modules
• module augmentation
• global augmentation
• global variables
• global functions
• triple-slash directives
• ... and potentially more

With this flag enabled, an error should appear on any usages of the above.

It may be worth allowing the flag (or a separate option) to specify allowlisted files that are expected to have side-effects. Notably, webpack's sideEffects option is a boolean | string[] type for this purpose.

Comparison to bundler tree-shaking

This idea is inspired by bundler tree-shaking, but focuses on side-effects at compile-time rather than runtime. The ideas are similar but different enough to warrant a specific TypeScript flag.

For example, a file that calls console.log on import has a runtime side-effect bundlers may care about but does not have any affect on typing. The allowlisted array of files with side-effects will likely be different between TypeScript and bundlers.

Use Cases

Banning compile-time side-effects allows future speed improvements. Notably, the compiler can now know whether source files and its import tree can be safely elided from a Program if its exported identifiers are unused. This has potentially significant speed and memory improvements depending on the source file graph of a program.

A quick and unfinished implementation that only looks at export { ... } from "..." syntax was created in PR #40966.

Examples

For a program with the following files, TypeScript should output:

a.ts(2,0): 'someGlobalVar' is a global variable, which is banned by the 'noTypingSideEffects' compiler option.

// tsconfig.json
{
  "compilerOption": {
    "noTypingSideEffects": true
  },
  "files": ["index.ts", "a.ts"]
}

// index.ts
import { a } from "./a";

console.log(someGlobalVar);

// a.ts
export const a = 1;
declare var someGlobalVar = 2;

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.

Start by reviewing PR #40966 and the issue's examples of ambient modules, module and global augmentation, global declarations, and triple-slash directives. Define the precise scope of compile-time side-effects and the compiler option's allowlist behavior before identifying the relevant TypeScript compiler entry points and tests. Done means the specified cases produce diagnostics without changing emitted JavaScript.