--erasableSyntaxOnly

[RyanCavanaugh]

Implements #59601

[typescript-bot]

Looks like you're introducing a change to the public API surface area. If this includes breaking changes, please document them on our wiki's API Breaking Changes page.

Also, please make sure @DanielRosenwasser and @RyanCavanaugh are aware of the changes, just as a heads up.

[jakebailey]

Reading #59601 (comment), do we also need to ban import foo = x.y? Or is that erasable?

[RyanCavanaugh]

do we also need to ban import foo = x.y? Or is that erasable?

Modulo VMS restrictions, it always transforms to const foo = x.y, but I would not categorize this as an erasure

[jakebailey]

ts-blank-space and Node both say no to import Foo = Bar.Baz, so that mostly settles it.

[DanielRosenwasser]

JSX?

[RyanCavanaugh]

Open to suggestions 🤷

[jakebailey]

I'd vote no since that would curse anyone trying to use this for "purist" purposes to not being able to use JSX at all; you're already going to get an error from Node, and in other runtimes or with a loader, it might even work just fine....

[RyanCavanaugh]

Yeah, the fact that you already have to put JSX content in a .?sx file means you can't possibly make the mistake of "not realizing enum is special" or whatever.

I thought Daniel wanted the text to say something different, which technically JSX is a non-ES runtime construct, but the phrasing would maybe get super awkward

[jakebailey]

Ohh that interpretation makes a lot more sense, oops

[DanielRosenwasser]

you're already going to get an error from Node

Well you could make the same argument about all of these features right?

the fact that you already have to put JSX content in a .?sx file

Well we permit JSX in JS files 😄

[DanielRosenwasser]

Overall I think it is fine either way, just a slightly weird distinction.

[jakebailey]

The implementation seems right to me; cross checking with other tools, I don't believe we missed anything, but it might be a good idea to add a test that shows that namespaces need to be recursively checked.

[jakebailey]

Worth re-noting for people watching this that ts-blank-space and Node.js' Amaro currently do not handle uninstantiated (type-only) namespaces:

• https://github.com/bloomberg/ts-blank-space/blob/main/docs/unsupported_syntax.md#runtime-impacting-syntax
• https://github.com/swc-project/swc/blob/4ebea77cb86cb11c540eaeab30503ccdbd315690/crates/swc_fast_ts_strip/src/lib.rs#L1171-L1191

[scottmas]

This disables ALL enums, but aren't string only enums 1 to 1 mappable to vanilla JavaScript? At runtime, as far as I can tell, a string enum behaves identical to an object composed of string values. Is this incorrect? And if not, would it be undesirable to allow string enums with this flag turned on? IMO string enums are far more ergonomic than const objects in that they are both a type and an iterable.

Sorry if this is irrelevant and the ship has sailed. Just thought I'd ask.

[ptts]

This disables ALL enums, but aren't string only enums 1 to 1 mappable to vanilla JavaScript? At runtime, as far as I can tell, a string enum behaves identical to an object composed of string values. Is this incorrect? And if not, would it be undesirable to allow string enums with this flag turned on? IMO string enums are far more ergonomic than const objects in that they are both a type and an iterable.

Enums are not "erasable" syntax - they need to be transformed to become valid Javascript.

An enum like this:

// Typescript

enum Direction { 
  Up = "UP", 
  Down = "DOWN"
}

is transformed into

// Javascript

var Direction;
(function (Direction) {
    Direction["Up"] = "UP";
    Direction["Down"] = "DOWN";
})(Direction || (Direction = {}));

The flag introduced here aims at ensuring you get a type error when you write typescript syntax that is incompatible with Node's new type stripping feature (https://nodejs.org/en/learn/typescript/run-natively#running-typescript-code-with-nodejs), which enums are.

(There is a new --experimental-transform-types flag in Node which can handle enums)

[robpalme]

As @ptts says, erasable enums do not exist today.

There is a proposal to add them to TS via new as enum syntax here.

[mohsen1]

@alexbit-codemod We need a codemod for this so everyone can migrate away easily!

[rauschma]

Should this option imply --verbatimModuleSyntax?

[jakebailey]

We discussed this heavily and settled on "no" for now, mainly because it makes our implied options complexity even worse, but also because it means those who are using this flag for reasons that aren't specifically needing the emit then have to disable some other flag (or if we made it required, be stuck).

[demurgos]

I'm coming here from the 5.8 announcement, looking for how to migrate from enums when using erasableSyntaxOnly.

A popular solution that I see is using an as const object (e.g. as documented in the handbook).

// you can also use number literals
const MyEnum = {
  Foo: "Foo",
  Bar: "Bar",
} as const;

This is usually accompanied with export type (e.g. as in the as enum proposal): export type MyEnum = typeof MyEnum[keyof typeof NodeType];

This lets you use MyEnum as a type representing the union of the variant values (here type MyEnum = "Foo" | "Bar") and on the value side you can use MyEnum.Foo or MyEnum.Bar.
There are a few downsides though:

• You lose nominal typing since the type MyEnum is now equivalent to the string literal union, consumer can pass "Foo" directly as a literal (instead of explicitly using MyEnum.Foo).
• You can't refer to the variant type through MyEnum.Foo, this is mainly an issue when using the enum as the tag of a discriminated union
• Unless you use the variant name as the variant value, debugging is less convenient because there's no reverse mapping

I don't really care about the last point, and it's easy to use the variant name anyway (it will most likely be interned by the JS engine, so perf should not be a big concern when comparing using a number VS a short string).

On the other hand, I'd like to have a way to keep nominal typing and lightweight type syntax for variants. Here is what I ended up moving to:

const Foo: unique symbol = Symbol("Foo");
const Bar: unique symbol = Symbol("Bar");

const MyEnum = {
  Foo,
  Bar,
} as const;

type MyEnum = typeof MyEnum[keyof typeof MyEnum];

declare namespace MyEnum {
  type Foo = typeof MyEnum.Foo;
  type Bar = typeof MyEnum.Bar;
}

export {MyEnum};

This uses unique symbol for nominal typing, which requires either a static readonly class property or a simple const. Using a class prevents you from using MyEnum as the union of all variant values, so constants must be used. I then combine it with a type namespace to provide type-level support for MyEnum.Foo.

Obviously, this approach is even more inconvenient at the implementation side, but I find it more convenient on the consumer side. The implementer side complexity is less relevant if using codegen. Symbol is also skipped in JSON.stringify for both keys and values, so if you rely on it then it won't work and you'd need a branded primitive type if you care about nominal typing. I use schema-guided serialization so it's not an issue for me, but it's worth mentioning.

The "record of symbols" approach addresses the complaints in this blog post about support variant annotations such as @deprecated: you can annotate in the namespace, or the symbol values.

I hope this message helps others when evaluating available solutions when migrating away from TS enums.