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.

未指定源文件或测试。首先检查会产生 TS1086 的声明发出行为，并将该提案与 downlevel-dts 进行比较；当一个有文档说明的兼容性选项能够拒绝不受支持的语法，并为选定的较旧编译器版本生成可使用的声明时，即视为完成。