Type-only imports and exports by andrewbranch · Pull Request #35200 · microsoft/TypeScript (original) (raw)

TL;DR:

To do:

Background

TypeScript elides import declarations from emit where, in the source, an import clause exists but all imports are used only in a type position [playground]. This sometimes creates confusion and frustration for users who write side-effects into their modules, as the side effects won’t be run if other modules import only types from the side-effect-containing module (#9191).

At the same time, users who transpile their code file by file (as in Babel, ts-loader in transpileOnly mode) sometimes have the opposite problem, where a re-export of a type should be elided, but the compiler can’t tell that the re-export is only a type during single-file transpilation (#34750, TypeStrong/ts-loader#751) [playground].

Prior art

In early 2015, Flow introduced type-only imports which would not be emitted to JS. (Their default behavior, in contrast to TypeScript’s, was never to elide imports, so type-only imports for them were intended to help users cut down on bundle size by removing unused imports at runtime.)

Two months later, #2812 proposed a similar syntax and similar emit behavior for TypeScript: the compiler would stop eliding import declarations from emit unless those imports were explicitly marked as type-only. This would give users who needed their imports preserved for side effects exactly what they wanted, and also give single-file transpilation users a syntactic hint to indicate that a re-export was type-only and could be elided: export type { T } from './mod' would re-export the type T, but have no effect on the JavaScript emit.

#2812 was ultimately declined in favor of introducing the --isolatedModules flag, under which re-exporting a type is an error, allowing single-file transpilation users to catch ambiguities at compile time and write them a different way.

Since then

Over the last four years after #2812 was declined, TypeScript users wanting side effects have been consistently confused and/or frustrated. They have workarounds (read #9191 in full for tons of background and discussion), but they’re unappealing to most people.

For single-file transpilation users, though, two recent events have made their lives harder:

  1. In TypeScript 3.7, we sort of took away --isolatedModules users’ best workaround for reexporting a type in Prevent collision of imported type with exported declarations in current module #31231. Previously, you could replace export { JustAType } from './a' with
    import { JustAType } from './a';
    export type JustAType = JustAType;
    But as of TypeScript 3.7, we disallow the name collision of the locally declared JustAType with the imported name JustAType.
  2. If a Webpack user was left with an erroneous export { JustAType } from './a' in their output JavaScript, Webpack 4 would warn, but compilation would succeed. Many users simply ignored this warning (or even filtered it out of Webpack’s output). But in Webpack 5 beta, @sokra has expressed some desire to make these warnings errors.

Proposal

Syntax

Supported forms are:

import type T from './mod'; import type { A, B } from './mod'; import type * as Types from './mod';

export type { T }; export type { T } from './mod';

Possible additions but I think not terribly important:

export type * from './mod'; export type * as Types from './mod'; // pending #4813

We notably do not plan to support at this time:

The forms in the former bullet will be syntax errors; the forms in the latter will be grammar errors. We want to start with productions that can be read unambiguously, and it’s not immediately clear (especially in the absence of Flow’s implementation), what the semantics of import type A, { B } from './mod' should be. Does type apply only to the default import A, or to the whole import clause? We prefer no one need wonder.

Type semantics

Any symbol with a type side may be imported or exported as type-only. If that symbol has no value side (i.e., is only a type), name resolution for that symbol is unaffected. If the symbol does have a value side, name resolution for that symbol will see only the type side. The typical example is a class:

// @Filename: /a.ts export default class A {}

// @Filename: /b.ts import type A from './a'; new A(); // ^ 'A' only refers to a type, but is being used as a value here.

function f(obj: A) {} // ok

If the symbol is a namespace, resolution will see a mirror of that namespace recursively filtered down to just its types and namespaces:

// @Filename: /ns.ts namespace ns { export type Type = string; export class Class {} export const Value = ""; export namespace nested { export class NestedClass {} } } export default ns;

// @Filename: /index.ts import type ns from './ns'; const x = ns.Value; // ^^ Cannot use namespace 'ns' as a value.

let c: ns.nested.NestedClass;

Emit

Updated: When the importsNotUsedAsValue flag is set to 'preserve', type-only import declarations will be elided. Regular imports where all imports are unused or used only for types will not be elided (only the import clause will be elided):

// @importsNotUsedAsValue: preserve

// @Filename: /a.ts import { T } from './mod'; let x: T;

// @Filename: /a.js import "./mod"; let x;

Back-compat flag

There’s a new flag removeUnusedImports. Its name is not perfect because it really means “remove imports that have imported names that never get used in a value position.” Open to suggestions.

Updated: this PR is backward-compatible by default.

Auto-imports behavior

I’m not yet confident what other changes, if any, will the right move, but the main scenarios to consider are:

Successor of #2812
Closes #9191
Closes #34750

Would close if they were still open: