Enable a library to support an older compiler than the one used to build it

Search Terms

TS1086, getter, incompatible, 3.7

Use Case

Consider a library API like this:

export class Book {
  get title(): string { return "Untitled"; }
}

If I compile this library using TypeScript 3.7, the resulting .d.ts file cannot be consumed by a project that uses TypeScript 3.5. The build will fail with this error:

error TS1086: An accessor cannot be declared in an ambient context.

Today, this error is considered “Working as Intended”. For libraries that seek to maximize compatibility, this policy causes us to get stranded on a relatively old compiler release. 🤔

Note that the above source code is not using any new 3.7 language features. The class property getter syntax is the same in TS 3.5. In other words, backwards-compatible source code does NOT produce backwards-compatible .d.ts files.

Proposed change

Let’s introduce a new option in tsconfig.json:

  "dtsCompatibilityVersion": "3.5.0"

This would have two effects:

• If my source code accidentally uses newer 3.7 syntax, the compiler will report an error to warn me.
• The emitter will avoid introducing incompatible constructs in the .d.ts files (e.g. emit readonly title: string instead of get title(): string for the above example)

Where constructs can be transformed to equivalent older constructs (like what downlevel-dts does), that’s nice to have. But it’s NOT required. Reporting an error is perfectly acceptable, as long as backwards-compatible source code can produce backwards-compatible .d.ts files.

How far back do we want to be compatible? The dtsCompatibilityVersion option leaves this decision up to the library author, while enabling them to use the latest compiler engine.

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.

[jukibom]

This is really quite frustrating, especially for Angular 8 (latest stable) applications locked to TypeScript 3.5, any dependencies which dutifully update to the latest (minor) TypeScript version and release a new lib with .d.ts files cause compilation issues and there’s not a great deal the consumer can do about it other than lock down versions and stop updating. Case in point, three.js is no longer compatible with Angular!

[octogonz]

Is downlevel-dts going to be officially supported and maintained? Are all the major toolchains expected to integrate it as a build step from now on? Why is the configuration stored in package.json instead of tsconfig.json? How do we configure it in contexts where there is no package.json? etc.

We can take this approach, but it’s a nontrivial work item. For a resuable toolchain, we’ll have to document it and support it.