Feature: triple-slash directive to override "target" compiler option

Search Terms

tsconfig override per-file compilerOptions code emit

Suggestion

Add a triple-slash directive to override the target compiler option within specific .ts code files.

Use Cases

With the final death of IE11 coming soon 🎈🎉🎊, my team and (I'm sure) many other teams are finally upgrading TS projects from "target": "ES5" to "ES6" or beyond.

What many of us will discover is that there can be subtle (or not-so-subtle) runtime differences between ES5 and newer syntactic equivalents--like true ES6 class declarations and the ES5 equivalent function+prototype object.

Our team has run into a problem where a library we still need to use calls class constructor functions using apply (not new) in its own implementation of inheritance/mixins - this throws a TypeError at runtime (and no, it would be impossible to fix it without a prohibitive, major breaking change to the library).

For reference, here's the relevant section of the ECMAScript standard: http://www.ecma-international.org/ecma-262/6.0/#sec-ecmascript-function-objects-call-thisargument-argumentslist, specifically 2. If F’s [[FunctionKind]] internal slot is "classConstructor", throw a TypeError exception..

Because of this and other runtime differences that exist between different target values, it would be extremely helpful to allow overriding this setting per-file, for those files where problems are encountered that can't be fixed in any other way. Locating the override within source code makes sense, since codegen options that affect runtime have parallel concern with the source code itself.

Alternatives?

The only alternatives I'm aware of are:

• Continue to use ES5, don't upgrade projects
• Run a multi-step build with different tsconfig.json files, specifically excluding/including the files with issues (not sure if this is really possible in a large project)
• Transpile offending files down to ES5 using babel or similar (or maybe even tsc itself)
• Locate offending files in a separate project (may not be possible, or may require prohibitive refactoring/reworking)

Besides the first option, the alternatives all require separating the information "these files need to be ES5" from the content of those files. A triple-slash TS directive is the best option because it doesn't separate these parallel concerns.

TS Syntax

Using a triple-slash directive makes sense since this is a pattern that is already supported and used extensively. I suggest the following syntax:

/// <compiler-options target="ES5"/>

This would also allow adding support for other compiler options in the future. However, it would only make sense to consider options that only affect code emit.

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 TypeScript's existing triple-slash directive handling and compiler-option processing, then assess how the proposed syntax could apply to individual .ts files. Done means a supported per-file target override with behavior and compatibility verified for the stated ES5-versus-newer emit use case.