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

[octogonz]

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.

[RyanCavanaugh]

We'd need some very strong evidence that downlevel-dts is insufficient to solve the use case. Already you could run your source code through downlevel-dts and error if there are any deltas that result from running the tool.

[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.

[octogonz]

Hmmm.. Is downlevel-dts only supported via CLI? What if we need to process buffers in memory?

[octogonz]

Is there a way for it to share the toolchain's compiler package as a peer dependency, rather than installing its own compiler version?

[octogonz]

Does downlevel-dts actually use the typesVersions setting? I don't see any references to it in the code.

[octogonz]

Will the .d.ts.map files be correct after this transform?

[GordonSmith]

@RyanCavanaugh this wold be a good use case for #16607 tsc-plugin-downlevel-dts type of thing?

[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]

I realized there's another aspect to this problem:

What happens if the exported API surface imports an incompatible type from an NPM dependency?

downlevel-dts cannot fix that case, unless the dependency's maintainers agree to run downlevel-dts with the same target version. This underscores the need for validation, not just down-leveling.

The simplest and best validation would be a side-by-side install of the oldest supported compiler version, which could run as a post-build step to detect any incompatibilities. But invoking two compiler versions will be costly, for both install times and execution times. Whereas the compiler should be able to perform this validation much more cheaply (considering that today the entire logic of downlevel-dts is only 200 lines of code).

Downleveling and validation are both needed to ensure compatibility, so it would make sense to integrate them into a single feature based on a single dtsCompatibilityVersion setting.

[admosity]

@jukibom You can force typescript 3.7.x on Angular 8. I have a situation where I have to support Angular 7 which does not have this option to do so.

In your angular.json you can set:

  "cli": {
    "warnings": {
      "typescriptMismatch": false
    }
  }

and use typescript 3.7.x.