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.

まず Proposal でサポートされている構文とサポートされていない構文を読み、その後、関連する issue #22665 とリンクされている Babel Starter のディスカッションを確認してください。実装ファイル、テスト、コンパイラのエントリポイントは指定されていないため、最初の作業は、完了の意味を定義する前に設計と影響を受ける領域を明確にすることです。