search

microsoft / tsdoc

A doc comment standard for TypeScript
https://tsdoc.org/
MIT License
4.7k stars 130 forks source link

[tsdoc] remove "const" keyword before enum to use with typescript isolatedModules #306

Closed samisayegh closed 2 years ago

samisayegh commented 2 years ago

Summary

When a typescript project is using isolatedModules, referencing exported const enums is not allowed.

Details

Please refer to this PR.

octogonz commented 2 years ago

@samisayegh sorry this PR got overlooked.

I seem to recall that we have a way to enable isolatedModules without breaking consumers that DON'T use isolatedModules. Let me ask around.

Gerrit0 commented 2 years ago

I think you are confusing isolatedModules with esModuleInterop (particularly, allowSyntheticDefaultImports, which is turned on by that option)

octogonz commented 2 years ago

Yes, I mistakenly thought this was a breaking change. But actually converting const enum to enum removes the inlining optimization entirely, which enables isolatedModules=true, without breaking isolatedModules=true source code, AND ALSO without breaking existing .js files transpiled with isolatedModules=true.

@dmichon-msft reminded me that there is a preserveConstEnums: true setting which avoids breaking .js consumers with isolatedModules=true, but the const enum still appears in the .d.ts files and thus will be a compiler error for TypeScript consumers.

I think the correct long term solution is a new TypeScript keyword as proposed in https://github.com/microsoft/TypeScript/issues/37774#issuecomment-902988750. This seems like the only reasonable way for a .d.ts file to request for enums to be inlined while guaranteeing that it's safe not to inline them.

In any case, avoiding const enum is the simple short term solution for libraries that want to interoperate with isolatedModules=true, so we'll accept this PR.