The future of `--experimental-transform-types`

[marco-ippolito]

I wanted to talk about the future of --experimental-transform-types.
The feature has been stable for a while no outstanding issue.
The problem with this flag is that the syntax supported might change due to typescript deprecations (rip module which btw is already not supported just an example), syntax becomes supported in the js spec (Maybe enums one day 😆) etc...
Here a few options:

• remove the flag completely (I dont know if its even possible given the massive usage)
• Leave the flag experimental forever (I dont like this option)
• Mark the flag as stable but document that the changes in the syntax are not semver major therefore it can break)
• Mark the flag as stable and mark every syntax change as semver major (😫)

WDYT @nodejs/typescript

[ljharb]

massive usage

i'd love to see numbers on this!

I'd expect the only viable options are 2, or 4. 1 will upset people who use it even if the usage was small, and 3 contradicts the meaning of "stable".

[jakebailey]

I would personally say option 2; "use at your own risk".

[marco-ippolito]

massive usage

i'd love to see numbers on this!

I'd expect the only viable options are 2, or 4. 1 will upset people who use it even if the usage was small, and 3 contradicts the meaning of "stable".

Quick search https://github.com/search?q=--experimental-transform-types+NOT+is%3Afork&type=code 1.7K results

[ljharb]

Thanks! Is that considered "massive"? What do other experimental flags look like in those results?

[aduh95]

Thanks! Is that considered "massive"? What do other experimental flags look like in those results?

https://github.com/search?q=--experimental-strip-types+NOT+is:fork&type=code shows 5.9k results, https://github.com/search?q=--experimental-require-module+NOT+is:fork&type=code shows 769 results, https://github.com/search?q=--experimental-sqlite+NOT+is:fork&type=code 560 results, https://github.com/search?q=--experimental-websocket+NOT+is:fork&type=code 126 results.

[robpalme]

Thanks for getting the numbers @aduh95. I am curious about the numeric thresholds Node uses to make these kinds of decisions.

Just in case option 1 seemed too blunt, there is also...

Option 1.5: "Carefully managed removal". Mark it as deprecated so that people know it will be considered for removal in some future major version.

[robpalme]

From OP:

(rip module which btw is already not supported just an example)

Just one narrow correction: the deprecation of the module keyword was not specific to transform-types. It was just a plain carefully-executed TypeScript-wide deprecation. The proof is that if you enable erasableSyntaxOnly in TS 5.9, you can still use module to create type-only ("uninstantiated") namespaces.

A year ago, knowing this deprecation was likely coming in TS 6.0, we took mitigation steps in Amaro/SWC to error on the old syntax. This is why today both strip-types and transform-types are immune to the deprecation.

Would you mind editing to remove this example? Or use strike-through.

[marco-ippolito]

module is a fitting example of deprecated syntax which would require a Node.js semver major if the flag were to be marked as stable. Thats (among other more compelling reasons) why I think its not a good idea to mark it as stable. Type stripping would of course have the same problem, but since transform-types supports more syntax, this issue is more likely

[GauBen]

Hi there, adding my two cents following @marco-ippolito post on bluesky (I guess that was the intent). The current trajectory of the JS ecosystem seems to be in favor of annotation-based typing:

• TS introduced erasableSyntaxOnly
• Node made type stripping stable as of v25.2
• If typing was to be made a standard, 49% of surveyed devs expect it to be annotation-based

Therefore, I would pick option 1 (remove --experimental-transform-types)

Type stripping is currently implemented with this caveat:

To discourage package authors from publishing packages written in TypeScript, Node.js refuses to handle TypeScript files inside folders under a node_modules path.

To go further in the annotation-based typing direction, I would create an --experimental-type-stripping-node-modules to enable type stripping for .ts files in node_modules, enabling build-step-free publication of TypeScript code to npmjs.com, à la Deno/jsr

You may know that all Svelte projects migrated from TS to JS+JSDoc because it made everything simpler, tooling-wise. Being able to publish and run TS dependencies with vanilla Node might tip the scale in favor of (erasable) TS over JS+JSDoc

[jakebailey]

This keeps getting brought up repeatedly, in many different threads (on this repo, node repo). Publishing TS has major downsides, including significant perf hits and incompatibility for TS itself (you really do not want to load everyone else's original TS source), which are solved by running tsc to publish .d.ts files (which, why even publish TS at that point).

JSR is different, because you publish TS, but they build your code for you and distribute .d.ts and .js files. It just moves the build process somewhere else.

[GauBen]

I forgot to consider TS in the equation, but I'd say it's solved by isolatedDeclarations. That may slightly degrade the DX (writing type annotations for all exports is cumbersome), but that could be solved with editor tooling (e.g. create/update export type declarations on save). All in all, it would benefit publishers a little (simpler build steps) and consumers a lot (smaller packages, high fidelity types, easy node_modules patching). What do you think?

[marco-ippolito]

I dont want this to become another conversation about type stripping in node_modules, it's kinda unrelated to the topic

[styfle]

Mark the flag as stable and mark every syntax change as semver major (😫)

This seems like the most logical solution. Why the 😫 face? Is this challenging to do?

[marco-ippolito]

Mark the flag as stable and mark every syntax change as semver major (😫)

This seems like the most logical solution. Why the 😫 face? Is this challenging to do?

Deprecating syntax needs a deprecation cycle that takes 2 semver majors. It also means we have to maintain multiple release lines of amaro. There is definitely some effort behind, that with strip types we dont have. I would rather remove it than maintain it

[styfle]

Personally, I haven't needed transform types since strip types is sufficient for my use cases.

To reiterate, the links shared above:

• --experimental-strip-types 6k
• --experimental-transform-types 1.9k

That means around 31% of users need transform. Maybe less than that given strip types is no longer flagged, but still significant.

Removing it might be painful for those users since the would need to switch back to ts-node, tsx, or similar.

Since we can't easily follow semver, I think the next best thing is to keep it experimental forever.