Should index.d.ts use readonly field: number or new syntax get field(): number ?

[justingrant]

Over the weekend I learned about a relatively-recent change in how TypeScript models property getters in .d.ts files. The old (pre-TS 3.7) approach was readonly field: number which is indistinguishable from a regular field except it's read-only because there's only a getter. The TS 3.7+ way is to expose the fact that there's a getter function: get field(): number.

microsoft/TypeScript#27644 has more context to explain why this change was made on the TS side. @rbuckton and @littledan and @ljharb were all on that thread so may have more to add.

Apparently, per microsoft/TypeScript#33939 this is a breaking change for TS users running 3.6 or lower who try to import types declared with the new syntax. So I'm not sure which format should be in Temporal types, and if "new format" then I'm not sure when would be best to make the switch. @rbuckton do you have an opinion?

[rbuckton]

Apparently, per microsoft/TypeScript#33939 this is a breaking change for TS users running 3.6 or lower who try to import types declared with the new syntax.

Are you familiar with "typesVersions"? Its a package.json entry TypeScript recognizes to pick a different index.d.ts file bases on the version of TypeScript that is consuming the package. That would allow you to specify get field(): number for newer versions of TS. It does add maintenance complexity, as it requires maintaining two versions of the .d.ts file.

[justingrant]

Yep, I was hoping to avoid typesVersions. Maybe the right approach would be to use a simple transform to start with one variation (e.g. get()) and transform to the other variation. Then we could use typesVersion without the work of maintaining two different files.

[ptomato]

Any new insights on this now that TypeScript 3.7 has been out for a while?

Regardless, I don't think it's a prerequisite for Stage 3, so I'm removing it from that milestone.

[justingrant]

I'm inclined to leave the old syntax (readonly). AFAIK there's not much harm in leaving it that way. If the TS folks want to change it later when they build the types into TS's built-in JS typings that seems fine too. Punt for now.

[ljharb]

Note that once stage 3 is achieved, the previously stated intention is to deprecate the polyfill anyways (if someone wants to make a new one in a non-tc39 org with the same code, that's up to them).

[ptomato]

OK, I'll close this for now.