Isolated Declarations in TS 5.5: State of the feature

[robpalme]

Acknowledgement

• I acknowledge that issues using this template may be closed without further explanation at the maintainer's discretion.

Comment

Isolated Declarations in TS 5.5: State of the feature

This post is intended to be a status update on Isolated Declarations as of mid-June 2024. There are separate messages for different audiences who may be interested in this feature.

Audience: Users

For folk who wish to enable the --isolatedDeclarations (ID) flag in their project, please go ahead! Just be aware of what you are opting into and what you will get back in return.

ID enforces stricter constraints above and beyond regular TS. It's a bit like --isolatedModules in that way. But that's it. Your TypeScript project will probably show new errors, and you are encouraged to use the new Quick Fixes to hopefully fix all of those errors. We believe the flag and errors are stable. The code fixes are mostly stable though we know of some issues with non-optimal generated annotations.

Please do not expect anything amazing to happen when you enable the flag. Your declaration emit won't change on enablement. Likewise if you later remove the flag, the declaration emit will remain the same. Compilation won't magically go faster. This is because currently there is no TypeScript infrastructure that takes advantage of the possibilities ID offers other than the one exception, which is the ability to use the transpileDeclaration() API.

We expect this situation to change over time as the feature matures and ecosystem tooling is built on top. Think of ID as being a Minimum Viable Product (MVP) for now. That won't last long - we know of concrete interest from tooling to leverage ID.

Potential reasons why you would want to enable this option today anyway:

• Courage: You are excited to try new stuff and want to provide feedback 🙏
• Style: You like the idea of explicitly annotated exports 💅
• API Access: You want to use the new transpileDeclaration() ✨
• External Tooling: You are pairing this feature with some other tool or system that DOES offer some kind of advantage 😎

There's also some work in progress to improve ergonomics that we hope to land in TS 5.6. For example, some way of handling computed properties. Lowering the barrier to adopt ID is something we'll keep looking at.

Audience: Declaration Emitter Tool Authors

For folk who think their time has come to build the fastest-ever declaration emitter, or other creative goals, you are of course free to try.

However, please be aware of an important caveat: You may struggle to precisely replicate TypeScript's declaration emit. It will be possible to exactly match it in many cases, but in others, you will find that TypeScript is using its advanced checker features to synthesize the output in a way that is hard to replicate. And therefore unless you also implement the checker's behavior - which could be a tall order - the output will differ.

Of course, you are always welcome to invent your own declaration emit for these cases. Just be aware that these may not be fully compatible with what TypeScript itself produces today or in the future.

Our plan is to continue the work on a low-complexity Unified Emit and hopefully complete it in TypeScript 5.6. The goal is to ensure that all of TypeScript's declaration emit under ID is trivially replicable without the need for a type-checker. We plan to add test infrastructure to ensure that future evolution of TypeScript's declaration emit does not rely on "forbidden knowledge" from the checker or from anything other than the single file being transformed. The intent is to ensure that as features are added to TypeScript in future, ID emit will always remain trivially replicable by third-party single-file declaration emitters.

We're highly interested in getting feedback from implementers of these tools. Please feel free to get in touch here.

Audience: Build Orchestrator Tool Authors

One of the promises of Isolated Declarations was to permit higher-level build tooling to perform declaration emit and type-checking in parallel across monorepos to deliver performance wins. If you want to build such a tool, please go ahead now!

As of TypeScript 5.5 this type of tooling can be built on top of the new transpileDeclaration API. You do not need to wait for third-party Declaration Emitter Tools to be built.

In the 5.6 nightly and beyond, the internal flag that transpileDeclaration relies on (noCheck) is publicly exposed. This allows parallelism of various emit and checking without necessarily going as far as ID, which could also allow wins without requiring users to renovate their code to allow full file-by-file parallelism.

We look forward to seeing how fast you can go!

[canonic-epicure]

Hi,

Would this improvement potentially lead to a long aniticipated solution for #35822 ?

I found it very discouraging, that TypeScript is currently fragmented into 2 languages. The 1st one is TypeScript itself and 2nd is TypeScript+declaration files. The program, valid in the 1st language, is not valid in the 2nd. It seems this is currently not recognized as a problem by TypeScript team, by its very frustrating for users that try to do anything beyond the simplest things in type system, and then publish that as a library.

[robpalme]

The general answer is no, the work on Isolated Declarations does not change the expressiveness of declaration files. They are unrelated goals. Campaigning for that goal is best done on #35822

However if you only care about #35822 because you don't like the strictness of TS error checking changing when you toggle declaration emit, then sure, enabling isolatedDeclarations (perhaps along with Sheetal's latest fixes that are landing in TS 5.6) should mean that difference goes away. But only because you've enabled an even stricter mode in the first place 🙃