Misc .d.ts fixes

[justingrant]

• calendar=>calendarName option for toString
• updated param types for toZonedDateTime conversion methods per Consistent pattern for additive conversion method parameters #889
• changed type of ZDT timeZone field to Temporal.TimeZone for easier workshop coding tomorrow.

[codecov]

Codecov Report

Merging #1144 into main will decrease coverage by 2.71%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main    #1144      +/-   ##
==========================================
- Coverage   93.55%   90.84%   -2.72%     
==========================================
  Files          19       17       -2     
  Lines        7961     8746     +785     
  Branches     1264     1232      -32     
==========================================
+ Hits         7448     7945     +497     
- Misses        506      790     +284     
- Partials        7       11       +4     

Flag	Coverage Δ
test262	?
tests	90.84% <ø> (+1.40%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
polyfill/lib/shim.mjs
polyfill/lib/intrinsicclass.mjs
polyfill/lib/legacydate.mjs
polyfill/lib/slots.mjs
lib/plaintime.mjs	89.73% <0.00%> (ø)
lib/plainyearmonth.mjs	90.37% <0.00%> (ø)
lib/ecmascript.mjs	94.29% <0.00%> (ø)
lib/intl.mjs	99.69% <0.00%> (ø)
lib/temporal.mjs	100.00% <0.00%> (ø)
lib/calendar.mjs	77.59% <0.00%> (ø)
... and 11 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 3aa42c3...d227734. Read the comment docs.

[ptomato]

OK, thanks

[Ms2ger]

* changed type of ZDT `timeZone` field to `Temporal.TimeZone` for easier workshop coding tomorrow.

That doesn't sound correct?

[justingrant]

* changed type of ZDT `timeZone` field to `Temporal.TimeZone` for easier workshop coding tomorrow.

That doesn't sound correct?

There was a long discussion about this at one of the meetings recently. The conclusion, assuming I'm remembering it correctly, was that 99%+ of the time, time zone usage will be built-in time zones, and 90%+ of custom time zones will be subclasses of TimeZone. And users in that remaining no-subclass custom time zone case are likely to be very sophisticated. Given that TS is essentially a type-aware linter, developers who are sophisticated enough to need a non-subclassed custom time zone are also probably sophisticated enough to override our TS declarations.

So even though technically that property could not be a TimeZone, in practice it will be a TimeZone often enough that I am comfortable making our "types lint rules" reflect what almost all developers will ever see.

The main reason why this is important is that if we didn't use the TimeZone type here, then developers would have to apply a type cast to every usage of many TimeZone methods that are optional on the protocol, or they'd get compiler errors. That's a pretty big usability issue.

[ptomato]

I think the old way is more correct and (zdt.timeZone as Temporal.TimeZone) doesn't seem that cumbersome, but I merged it anyway because 1) making the workshop smoother and 2) TypeScript will actually decide this in the end, not us.