Type erasure changes directive-prologue semantics after type-only declarations

[magic-akari]

🔎 Search Terms

directive prologue, type-only declaration, type alias, type erasure, string expression, use client, use strict, emit, transformer, erasableSyntaxOnly

🕗 Version & Regression Information

• Reproduced with TypeScript 5.9.3 and 6.0.3.
• Reproduced on TypeScript main at 5739027c9a7 (7.1.0-dev).
• This is the behavior in every version I tried. I could not find an existing issue for this specific interaction after searching for the terms above.

⏯ Playground Link

https://www.typescriptlang.org/play/?#code/GYVwdgxgLglg9mABMOcAUBKRBvAUIgxKATwAcBTRAFUQF5EBnKAJxjAHMBufQgIhAaUIAGxjkwUXtwC+QA

💻 Code

function foo() {
    type T = string;
    "use client";
}

🙁 Actual behavior

TypeScript emits a bare string expression after removing the type alias:

function foo() {
    "use client";
}

The source string is preceded by a type-only declaration, but the emitted string is the first statement in the function body. It is therefore reinterpreted as part of the JavaScript Directive Prologue.

This changes the directive status of the string during type erasure. The same issue can affect use strict, which changes JavaScript runtime semantics, and implementation-defined directives such as use client or use server.

🙂 Expected behavior

A type-only declaration should terminate a Directive Prologue. Removing type-only syntax must not promote a following string expression into a directive. The emitted JavaScript should preserve the string as an ordinary expression statement, for example:

function foo() {
    ("use client");
}

Additional information about the issue

The parentheses do not change the value of the expression, but they prevent the statement from being parsed as a directive.

The purpose of this issue is to clarify whether a type-only declaration terminates a Directive Prologue or is transparent to it.

If TypeScript instead intends type-only declarations to be transparent to Directive Prologues, then source analysis should consistently recognize strings after those declarations as directives, and that TypeScript-specific extension should be documented. In either case, source interpretation and emitted JavaScript should agree.

ECMAScript context

ECMAScript defines a Directive Prologue as the longest initial sequence of string-literal expression statements in a function, script, or module body.

That rule establishes that JavaScript directives must be at the beginning and contiguous. A type alias is TypeScript-specific syntax, so the remaining question is how it participates in this sequence: whether it terminates the prologue or is transparent to it.

Ecosystem behavior

I compared parsers that support TypeScript or the equivalent Flow type-alias syntax. Their ASTs consistently classify the string after the type alias as a normal expression statement rather than a directive.

Tool	Source AST / directive classification	Output after removing types
TypeScript	Its strict-mode prologue scan stops at the first non-directive statement, so the type alias prevents the later string from being found	Bare 'use client';
Babel	FunctionBody.directives is empty; the string remains an ExpressionStatement in body	Bare 'use client';
@typescript-eslint/parser 8.68.0	ExpressionStatement.directive === undefined	N/A
Yuku 0.9.1	ExpressionStatement.directive === null	N/A
OXC 0.145.0	ExpressionStatement.directive === null	Parenthesized ('use client');

This suggests a consistent source-level interpretation: the type-only declaration terminates the Directive Prologue.

Babel demonstrates that correct AST classification alone is not sufficient. Its TypeScript transform removes the type alias, and its generator then emits the now-leading string without parentheses, producing the same semantic change as TypeScript.

OXC preserves the AST distinction during output. Its code generator explicitly parenthesizes a leading string expression that is present in the statement list but absent from the directive list. For this input it emits:

function foo() {
    ("use client");
}

---

Either interpretation could be specified for TypeScript syntax, but the parser/binder interpretation and emitted JavaScript should not disagree.

Given the consistent ecosystem AST behavior and TypeScript's own contiguous prologue scan, I think type-only declarations should terminate the Directive Prologue, and type erasure should preserve that boundary by parenthesizing a following string expression when necessary.

[RyanCavanaugh]

Let's reason about this from the hypothetical world where the types as comments proposal is accepted.

A type declaration would then be equivalent to a comment. What does a comment do? It doesn't change the interpretation of a following "use strict"; declaration:

function foo() {
    // type T = string;
    "use strict";
    with({}) { } // <-- illegal, this is a strict mode function
}

[magic-akari]

This actually came up while I was working on type stripping, which is why I’ve been using the transformer’s behavior as a reference and trying to align the semantics with it.

At the moment, the type-stripping transform produces:

function foo() {
    ;
    "use strict";
    with ({}) {}
}

Once we settle on the correct semantics and align the parser and transformer, this output should follow naturally. This is similar to how I handle other ASI-sensitive cases.

One caveat is that treating erasable syntax as fully transparent and allowing the directive prologue to continue would be considerably harder to implement. Many parsers identify directives during parsing, so this would require moving some AST-level detection and traversal logic into the parser.

[RyanCavanaugh]

At the moment, the type-stripping transform produces:

What is "the" type-stripping transform?

[magic-akari]

At the moment, the type-stripping transform produces:

What is "the" type-stripping transform?

I meant the behavior of SWC’s type-strip implementation, which I’m currently fixing.

[magic-akari]

• Babel Playground: Click “Input AST” in the right-hand panel and inspect the directives field under body. When you uncomment the type declaration, directives becomes empty.
• typescript-eslint AST Viewer: It exhibits similar behavior. Commenting out or uncommenting the type declaration changes the directive field.
• OXC AST Viewer: It exhibits the same behavior.

[magic-akari]

I found stronger evidence in TypeScript itself, and it directly conflicts with the current type-erasure output.

TypeScript does not currently treat a type declaration like a comment when determining directive-prologue semantics. parseBlock includes parsed declarations in the block’s statement list, and type T = string becomes a TypeAliasDeclaration. A comment, by contrast, is trivia and does not appear in that list.

TypeScript’s directive-prologue lookup follows the same distinction. FindUseStrictPrologue examines statements from the beginning and stops at the first statement that is not a string-literal expression statement. Consequently, a type alias terminates the directive prologue under TypeScript’s current source interpretation, whereas a comment does not.

This distinction has an observable effect in TypeScript’s own grammar checks:

function foo(a = 1) {
    type T = string;
    "use strict";
}

TypeScript accepts this without diagnostics 1346/1347. Its check for a "use strict" directive in a function with a non-simple parameter list uses that same contiguous-prologue lookup, which stops at the type alias.

Type erasure currently changes the result to:

function foo(a = 1) {
    "use strict";
}

That output is invalid JavaScript:

SyntaxError: Illegal 'use strict' directive in function with non-simple parameter list

Replacing the type alias with a comment, or moving "use strict" before the type alias, causes TypeScript to report diagnostics 1346/1347. The comment example therefore does not have the same semantics as the type declaration in TypeScript today.

The surrounding ecosystem follows the same interpretation. Babel, typescript-eslint, Yuku, and OXC classify a string following a type declaration as an ordinary expression statement rather than a directive.

Formatters also actively preserve this distinction. For example, Prettier parenthesizes the string expression:

Prettier v3.9.6

Playground link

Input:

function foo(a = 1) {
    type T = string;
    "use strict";
}

Output:

function foo(a = 1) {
  type T = string;
  ("use strict");
}

Biome applies the same parenthesization. This behavior preserves the established meaning of the string as an ordinary expression rather than allowing it to become a directive merely because surrounding syntax is removed or rewritten.

Given TypeScript’s existing source semantics and the behavior of parsers and formatters across the ecosystem, I think a type-only declaration should continue to terminate the directive prologue. Treating it as transparent would not merely explain the current emit; it would change TypeScript’s existing grammar diagnostics and disagree with how current tooling interprets this source.

Type erasure should therefore preserve the original prologue boundary. It could parenthesize a newly exposed leading string expression, or it could leave an empty statement (;) at the position of the erased type-only declaration. Either approach keeps the emitted JavaScript consistent with the semantics TypeScript assigned to the source.

The current behavior does not: TypeScript can accept the source while emitting JavaScript that is syntactically invalid. Preserving the established directive-prologue boundary resolves that inconsistency and aligns TypeScript’s output with the existing ecosystem interpretation.

[RyanCavanaugh]

Automatically parenthesizing these directives would be user-hostile behavior -- there's no way you wrote "use strict"; and said to yourself "Luckily, TypeScript will ensure this does nothing on my behalf, because of the prior type alias". We should make the parser/binder correctly skip the type aliases, not try to match other parsers' bugs. Feel free to log issues in that vein as you find them.