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.

No source files or tests are named. Start by reviewing the declaration-emission behavior that produces TS1086 and comparing the proposal with downlevel-dts; done means a documented compatibility option can reject unsupported syntax and produce consumable declarations for the selected older compiler version.