Proposal: Easier Migration with Types in JavaScript Files

This issue is the dual of #22665.

Background

In last week's design meeting, we discussed #22665 and it seemed like we had some positive sentiment around the proposal. Specifically, issues where users hit an expressivity wall or mismatch in .js when migrating to .ts files provide a compelling case.

However, there are certain issues with the proposal:

• It still requires users to make a file extension change from .js to .ts, which usually implies some change in build steps.
• It provides no easy migration path from other type systems with annotation syntax used in .js files (see https://github.com/Microsoft/TypeScript-Babel-Starter/issues/1).
• It introduces the concept of a "diluted/loose" TypeScript experience which can make things more confusing.

Proposal

We can introduce a new mode that enables TypeScript-specific constructs in .js files. This new mode would allow things like type annotations, interfaces, class property annotations, etc. to be declared in .js files. Users would have to explicitly opt-in to this mode for transitionary purposes, with the end goal of migrating to TypeScript.

Supported constructs

The following constructs from TypeScript would be supported:

• Type annotations (: Foo)
• Interfaces (interface Foo { /*...*/ })
• Type alias (type Foo = "hello" | "world")
• as-style type assertions (xyz as SomeType)
• Non-nullable type assertions (x!.bar)
• Definite assignment assertions (let x!: number)
• Enums (enum E { /*...*/ })
• Import aliases and export aliases:
  • `import

Unsupported constructs

The following would not be supported to encourage users to write ECMAScript modules and standard enums that utilize late-binding.

• Namespaces
• const enums

Existing typed .js file semantics

A JavaScript file still has the same specialized semantics including understanding things like CommonJS modules, JSDoc type annotations, ES5-style constructor functions, object literals potentially being open-ended, etc. However, in the presence of an analogous TypeScript construct, the TypeScript construct always wins. For example, the following declares x as type number, and potentially issues an error on the JSDoc.

/**
 * @type {string}
 */
var x: number;

Drawbacks

This proposal avoids the aforementioned issues with #22665, but has some new drawbacks.

For one, it seems like there's little-to-no advantage to moving from a .js file to a .ts file, even though TypeScript is easier to reason about and make assumptions on (whereas much of our JavaScript semantics are more "best-effort").

The other issue, which is likely much bigger, is that this conflates where JavaScript ends and TypeScript begins. While the intent here is to make migration easier, enabling this functionality could be perceived poorly as an attempt to extend the language inappropriately. While we hope users understand this is not the case, we are extremely open to feedback from the community on this issue.

If this flag was called something like --jsMigrationMode, perhaps we could be explicit on the intent and also signal to users that having this flag on is not ideal.

Existing Precedent

Common usage of JSX and Flow in .js files in the Babel ecosystem (as opposed to using the .jsx file extensions) provides a reasonable precedent for supporting TypeScript constructs in .js files.

先阅读该提案支持和不支持的构造，然后查看相关 issue #22665 以及链接的 Babel Starter 讨论。没有列出任何实现文件、测试或编译器入口点，因此首要任务是在定义完成意味着什么之前，确定设计和受影响的范围。