What do we call this command-line option?

[RyanCavanaugh]

Consider two TypeScript files:
_a.ts_

module M {
  export var t = 5;
}

_b.ts_

var t = 'foo';
module M {
  var s = t; // <-- what does this mean?
}

If we compile b.ts on its own, the t in var s = t refers to the outer var t, a string. The emit for this line is simply var s = t;.

If we compile b.ts along with a.ts, the t in var s = t refers to M.t, the exported variable of type number. The emit for this line is var s = M.t.

This behavior, and a few other language features (e.g. const enum), prevent TypeScript from being able to correctly operate on a single file without understanding the entire universe of files involved in the program. This has performance implications for features like compile-on-save, especially in larger projects, and blocks scenarios like on-the-fly compilation in module loaders.

We'd really prefer to be able to emit a file without first understanding the entire program it's a part of. The language as-is prevents this. However, by slightly subsetting the language to disallow things that require whole-program binding/typechecking, we can re-enable those scenarios. People can "opt in" their project to this language subset as a trade-off.

Tentatively, we're calling the prongs of this fork "whole program mode" and "single file mode". Naming TBD.

A key part of this is that you need to be able to compile e.g. a.ts and b.ts above in a mode that says "This code will not work in single-file-mode", e.g.:

 > tsc --warnMeIfThisIsNotSafeInSingleFileMode a.ts b.ts
TS1234 (b.ts line 2): Modules may not be re-opened in single-file mode

We need some help naming these things, especially the commandline flag. The current list of ideas on the whiteboard, of which nobody likes anything, consists of the following 😦

• separateCompile
• singleFileEmit
• disableGlobalOptimizations
• safeForTranspile
• safeForSyntacticTranspilation
• separate
• isolated
• safeTransform
• singleFileScope
• crossFileSafe
• crossFileRestrictions

Please help 🚲 🏠!

Ref #2499

[JamesKovacs]

If you're in single-file mode, how do you even know that the module, M, in b.ts is being re-opened?

[RyanCavanaugh]

That's the tricky thing -- this isn't a flag that turns on single-file mode. It's a flag that says "Compile this normally, but error if you do anything that doesn't work in single-file mode"

[yahiko00]

Just in order to be sure, in such a "single-file-mode", does this following file compile?

b.ts

module M {
  export var t = 5;
}

[Steve-Fenton]

Maybe --segregated, although --singleFileMode seems to say what it does. Maybe put them on the whiteboard until you hate them more than your original ideas :)

[RyanCavanaugh]

Just in order to be sure, in such a "single-file-mode", does this following file compile?

If a.ts is part of the compilation, no. If a.ts is not part of the compilation, then yes.

[yahiko00]

So, this is not as "single-file" as it would mean... ^_^
Good luck finding an accurate name!

EDIT: I would suggest something like --localBinding

[JamesKovacs]

So what you're really doing is adding linting flags or increasing the warnings level to disallow certain unsafe constructs. Is tsc.exe the right place to put this functionality as it has nothing to do with compiling and a lot to do with whether other tools can make assumptions about potentially unsafe constructs?

[matijagrcic]

-singularCompile, -individualCompile, -bounded Compile (bounded context pattern)

[yahiko00]

Why not --preventConflict since this is the goal of this option.

[RyanCavanaugh]

Is tsc.exe the right place to put this functionality as it has nothing to do with compiling

The entire point of this flag is to enable the compilation of files without examining their dependencies. 99% of the code to do this checking is in tsc already. A hypothetical external tool to do this checking would start with the tsc.js code and make about five edits. So yes, tsc.exe is absolutely the right place for this.

Why not --preventConflict since this is the goal of this option.

This isn't about conflicts. References outside the declaring file to const enums, for example, are disallowed under this flag because they require inlining, but the compiler doesn't know what value to inline without having that other file available.

[Steve-Fenton]

Maybe --noDependencies or the team suggestion --isolated. Isolated seems to describe the kind of restrictions you may encounter.

[yahiko00]

@RyanCavanaugh Thanks for your explanations. You know specs better :p

@Steve-Fenton --noDependencies should go on the whiteboard

[JamesKovacs]

I'm confused. You want to compile single files without worrying about "the world", but you want to provide warnings about re-opening modules, which you can only do by looking at the world. What am I missing here?

[RyanCavanaugh]

which you can only do by looking at the world. What am I missing here?

This isn't a flag that says "ignore the world". It's a flag that says "Compile this normally, but error if you do anything that doesn't work if you are not allowed to look at the world"