3.1.X and @next emitting declaration file with initializer in ambient context

[southpolesteve]

TypeScript Version: [email protected]

Search Terms:
"ambient context", "ambient context initializer", "ambient context public static"

Code

export class Foo {
  public static readonly bar = 0;
  public baz = 0;
}

Expected behavior:

Typescript emits a definition file without initializers:

export declare class Foo {
    static readonly bar: number;
    baz: number;
}

This is the output created by [email protected]

Actual behavior:

Typescript emits a definition file with initializer:

export declare class Foo {
    static readonly bar = 0;
    baz: number;
}

Playground Link:
https://www.typescriptlang.org/play/#src=export%20declare%20class%20Foo%20%7B%0D%0A%20%20%20%20static%20readonly%20bar%20%3D%200%3B%0D%0A%20%20%20%20baz%3A%20number%3B%0D%0A%7D

Related Issues:

[weswigham]

Actually, we explicitly added support for constant value read-only initializers in ambient contexts to bring them in line with const declarations, which already used and supported them.

[southpolesteve]

What's the guidance on adopting such changes? In this case, we unknowingly broke users on typescript<3.1 when we published https://github.com/Azure/azure-cosmos-js compiled using [email protected]. I would not expect a package compiled with 3.1 to break a consumer compiling with 3.0

[weswigham]

Any time we add a new typespace construct (like import types) we've had the potential to emit declaration files which could have broken consumers using older compiler versions. You can usually work around the changes and get a compatible .d.ts by annotating the types yourself, thereby preventing the compiler from generating types/initializers.

[DanielRosenwasser]

You can baseline your .d.ts files to ensure that you don't break users. Tools like https://github.com/Microsoft/web-build-tools/wiki/API-Extractor help with this.

[southpolesteve]

I understand this is working as intended and I do agree with the rationale behind it.

That said, I still think this is a poor experience for library authors. I would guess that many TS library authors are not baselining their .d.ts. So as an author, how do I discover this issue? Ship code that breaks users? That's what I did. If a foot-gun exists, ideally some warning exists before I've already shot myself in the foot 😄 Some ideas:

• Include info about this issue at https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html Is there a better location I'm not seeing?
• Add potentially breaking .d.ts changes to the release notes
• Tooling to test libs from a consumer perspective against multiple versions of typescript. I get this is a big ask and likely out scope for the main TS repo.

Let me know if you have any thoughts on these suggestions. The first point I may take a crack at since it is just a documentation change.

@DanielRosenwasser API Extractor is something I've actively trying to adopt. Ran into a couple issues: microsoft/rushstack#663 and microsoft/rushstack#922 (Currently blocking me from using api-extractor). The team working on it has been helpful and I'm hopeful we can work through the issues.

[RyanCavanaugh]

So as an author, how do I discover this issue?

Use something like https://github.com/Microsoft/dtslint, which already supports testing with older TypeScript versions.

[southpolesteve]

@RyanCavanaugh I've come across that project before, but it specifically says in the readme not to use dtslint if writing the library in typescript. Is that incorrect?

[typescript-bot]

This issue has been marked 'Working as Intended' and has seen no recent activity. It has been automatically closed for house-keeping purposes.