Add option to ensure 3.7.x declaration files are compatible with 3.x typescript compilers

[GordonSmith]

Search Terms

declaration file

Suggestion

Add compiler option to force generated declaration files to adhere to the 3.x.x specification

Use Cases

Library authors should be able to use v3.7.2 typescript compiler to create declaration files which can be consumed by application authors using older versions (think Angular).

Currently using setter/getters will generate incompatible declaration files for folks using TypeScript < 3.6

Examples

tsc --declarationVersion=3

<EDIT> emit old format unless useDefineForClassFields is set to true </EDIT>

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

[ajafff]

You might be interested in this tool: https://github.com/sandersn/downlevel-dts

[MartinJohns]

to adhere to the 3.x.x specification

What specification?

[GordonSmith]

@MartinJohns probably a fair comment, but lets not derail the "concern":

• 3.7.x emits definition files that cause errors for versions prior to 3.6.x

IMO that type of breaking change should be held back for a 4.x.x release?

What might have been more prudent is to use the old format unless useDefineForClassFields is set to true (since its also going to cause backward compatibility issues)?

[GordonSmith]

@ajafff thanks, I did see that project but right now it doesn't feel like the "correct" solution, I will probably stay on 3.6.x for now and wait to see how this plays out, as I suspect there will be more voices once the effects trickle out further...

[fatcerberus]

IMO that type of breaking change should be held back for a 4.x.x release?

TypeScript doesn't follow SemVer and never has. There are several issues discussing this, for example #14116. Breaking changes are not made in patch releases, but are made in minor versions all the time.

[GordonSmith]

@fatcerberus again probably a fair comment WRT to the API and TypeScript input - but this concern is about the "consumer" of the JS / Declaration files when that consumer is on an older version.

It might simply be that this breaking change wasn't given enough prominence - or that its the first time since the "import bug" in the declaration files that it has affected one of my projects (and in this case I only noticed by chance since one of my unit tests was running on an older TS version.)

A "compatibility" grid might useful?

[RyanCavanaugh]

It's not at all a new problem. We've introduced new type syntax with about half of the TS releases, and with this has always come the possibility that a .d.ts file won't be consumable by a prior release. downlevel-dts is the intended solution for the problem of supplying a .d.ts file compatible with a previous release of TypeScript.

[GordonSmith]

But the "downlevel-dts" project only fixes the setter/getter incompatibility, it doesn't "fix" any of these other breaking changes?

[andrewbranch]

If you only need to check if a file is compatible with an older version of TypeScript (as opposed to transforming it to be backward compatible), it seems like this would be trivial to implement as an external tool by simply npm installing an older version of TS and checking a declaration file with it, in a programmatic way. dtslint does this on DefinitelyTyped for the exact purpose of making sure the type definitions there will support the versions the claim to support. On the other hand, building that functionality into the compiler would require a lot of bookkeeping every time we introduce new type syntax. I think the problem you’re trying to solve is worthwhile, but the compiler is not the right place for it.

[RyanCavanaugh]

Marking this out of scope since we wouldn't add this kind of flag specifically, but the aforementioned downlevel-dts tool is the intended way to solve the use case.