Remove time zone and calendar protocols and classes

[ptomato]

Conclusion in the champions meeting of 2024-04-18. We've been asked to reduce the surface area and complexity of the proposal. The callable hooks in the time zone and calendar protocols are the part that implementations have been most uncomfortable with. They also seem to be where we get the biggest reduction in complexity for the least loss of use cases. The TimeZone and Calendar classes themselves make less sense to keep if the protocols are gone. So our conclusion is to remove them.

Motivations for removing

• Requiring observable calls in a particular sequence makes it difficult for implementations to optimize, unless they maintain separate code paths for built-in vs. user-supplied calendars/time zones.
• Large increase in complexity of proposal for relatively little gain.
• This functionality made more sense back when you could monkeypatch Calendar.from() and TimeZone.from() to ‘register’ a custom ID. That ability was removed when the proposal went to stage 3 because the committee will not agree to global state.
• Without a calendar protocol, there doesn’t seem to be much point in having a Temporal.Calendar object. All the functionality is still easily available through PlainDate methods and properties, (except for Calendar.p.fields() and Calendar.p.mergeFields() which are weird methods that only exist to make it possible to build custom calendars with extra fields.)
• Without a time zone protocol, the usefulness of a Temporal.TimeZone object is heavily reduced, although it doesn’t become completely redundant like Temporal.Calendar.

Use cases that disappear, and their replacements

Work around incomplete/outdated support in CLDR calendars and TZDB

For example:

• Adjustment days in Hijri calendars
• https://github.com/khawarizmus/hijri-week-calendar
• Make sure program runs against known version of time zone database regardless of whether environment is ahead or behind

Replacement: Previously, you could implement a custom calendar or time zone by creating an object that implemented the protocol, and monkeypatching some of Temporal so that it would deserialize dates with your custom calendar/time zone's ID into a Temporal object with the correct protocol object. You would now have to monkeypatch more of Temporal. As part of moving this issue forward, we'll create a proof of concept for doing this, to make sure that it remains possible.

Converting directly between Instant and PlainDateTime

Replacement: Go through ZonedDateTime, instead of through TimeZone. e.g.

// Before
timeZone.getPlainDateTimeFor(instant)
timeZone.getInstantFor(plainDateTime, { disambiguation })

// After
instant.toZonedDateTimeISO(timeZoneID).toPlainDateTime()
plainDateTime.toZonedDateTime(timeZoneID, { disambiguation }).toInstant()

Determine if two time zone IDs are aliases

Replacement: Use ZonedDateTime.p.equals() with the same instant. (This is more inconvenient, but it's a pretty uncommon operation. If this really needs to be more ergonomic, a dedicated static method can be added in a follow up.)

// Before
Temporal.TimeZone.from('Asia/Kolkata').equals(Temporal.TimeZone.from('Asia/Calcutta'))

// After
zonedDateTime.withTimeZone('Asia/Kolkata').equals(zonedDateTime.withTimeZone('Asia/Calcutta'))

Look up previous/next UTC offset transition in a time zone

Replacement: We'll add two methods to ZonedDateTime that replace the two methods on TimeZone.

// Before
timeZone.getNextTransition(fromInstant)
timeZone.getPreviousTransition(fromInstant)

// After
const fromZonedDateTime = fromInstant.toZonedDateTimeISO(timeZoneID);
fromZonedDateTime.nextTransition()
fromZonedDateTime.previousTransition()

Custom disambiguation behaviour

A niche use case is implementing PlainDateTime-to-Instant conversions with disambiguation behaviours other than the built-in earlier, later, compatible modes. By request, we have a cookbook recipe for this.
Replacement: You can still do it with two conversions, for example:

// Before
arrayOfInstants = timeZone.getPossibleInstantsFor(plainDateTime)

// After
arrayOfInstants = [
  plainDateTime.toZonedDateTime(timeZoneID, { disambiguation: 'earlier' }),
  plainDateTime.toZonedDateTime(timeZoneID, { disambiguation: 'later' }),
]

Scope of issue

• Remove Temporal.Calendar
• Remove Temporal.TimeZone
• User-defined methods are not looked up nor called during calculations
• Calendar-taking APIs no longer accept objects, only string IDs, and ISO 8601 strings out of which a string ID is determined
• Time-zone-taking APIs no longer accept objects, only string IDs, and ISO 8601 strings out of which a string ID is determined
• [[Calendar]] internal slot of PlainDate, PlainDateTime, PlainYearMonth, PlainMonthDay, ZonedDateTime only stores string ID
• [[TimeZone]] internal slot of ZonedDateTime only stores string ID
• Remove getCalendar() methods from PlainDate, PlainDateTime, PlainYearMonth, PlainMonthDay, ZonedDateTime prototypes
• Remove ZonedDateTime.p.getTimeZone()
• calendar property of object returned by PlainDate, PlainDateTime, PlainYearMonth, PlainMonthDay, ZonedDateTime's getISOFields() methods can only be a string
• timeZone property of object returned by ZonedDateTime.p.getISOFields() can only be a string
• Add ZonedDateTime.p.nextTransition() and ZonedDateTime.p.previousTransition()
• Update TypeScript types to match the changes above.
• Create proof of concept for how you would polyfill a custom calendar or time zone going forward

[leftmostcat]

Datetimes with custom time zones are a pretty major part of working with iCalendar (RFC 5545; https://datatracker.ietf.org/doc/html/rfc5545), since the spec has no provision for reference to a common time zone database. It would be very helpful to get a picture of what this might look like with the revised scope of this proposal.

[khawarizmus]

This is a very heavy change considering that we are this far into the proposal.

Do i understand that there is a guarantee that use cases like this https://week-dates.netlify.app/calendars/iso-extended.html or this https://week-dates.netlify.app/calendars/hijri-week-calendars.html will still be possible with some additional implementation details?

Also for the proof of concept. I would be happy to collaborate and make it work in https://week-dates.netlify.app for both aforementioned use cases

[ptomato]

Datetimes with custom time zones are a pretty major part of working with iCalendar (RFC 5545; https://datatracker.ietf.org/doc/html/rfc5545), since the spec has no provision for reference to a common time zone database. It would be very helpful to get a picture of what this might look like with the revised scope of this proposal.

@leftmostcat Our resident RFC 5545 expert @justingrant may be able to give you a better answer about VTIMEZONEs. For TZID, It looks like it's recommended but not required to use identifiers from TZDB so my guess is that for most usages the builtin time zones would be sufficient; hopefully the usages where they weren't, would be covered by the proof of concept I intend to create.

This is a very heavy change considering that we are this far into the proposal.

Do i understand that there is a guarantee that use cases like this https://week-dates.netlify.app/calendars/iso-extended.html or this https://week-dates.netlify.app/calendars/hijri-week-calendars.html will still be possible with some additional implementation details?

Also for the proof of concept. I would be happy to collaborate and make it work in https://week-dates.netlify.app for both aforementioned use cases

@khawarizmus Yes, the intention is that you'll still be able to do things like this, but you'll have to either do it by not overriding built-in Temporal APIs, or monkeypatching more of Temporal if you want the custom calendar to appear built-in.

I hope to illustrate more with the proof of concept.

I understand it's a heavy change but I don't think we'll be able to move the proposal forward without it.

[justingrant]

Datetimes with custom time zones are a pretty major part of working with iCalendar (RFC 5545; https://datatracker.ietf.org/doc/html/rfc5545), since the spec has no provision for reference to a common time zone database. It would be very helpful to get a picture of what this might look like with the revised scope of this proposal.

@leftmostcat Our resident RFC 5545 expert @justingrant may be able to give you a better answer about VTIMEZONEs. For TZID, It looks like it's recommended but not required to use identifiers from TZDB so my guess is that for most usages the builtin time zones would be sufficient; hopefully the usages where they weren't, would be covered by the proof of concept I intend to create.

We understand that removing custom time zones from Temporal V1 will create challenges for any application that needs to take a datetime+VTIMEZONE from an iCalendar message and turn that into a Temporal.ZonedDateTime object, especially if the TZID isn't an IANA time zone name. (If it is an IANA zone, you can just use it... and you could validate that the built-in zone matches the VTIMEZONE data before doing that.)

But at this point it's not clear we have another option. We need to remove this functionality so that we can ship the rest of Temporal. Here's why:

• Without shrinking the size of this proposal, Google and Apple are reluctant to ship Temporal due to code size and overall complexity. (Especially how Temporal objects can call into user code for calendars and time zones)
• The current custom time zone protocol was defined when built-in time zones used the same protocol. But built-in time zones were changed to use strings, which made the current protocol inconsistent with built-in zones.
• Combining both the above concerns, the current consensus is that the best way to define a custom time zone is to use data, not code. There's lots of prior art to choose from for this, including iCalendar's VTIMEZONE or its JSCalendar equivalent, or the data format used in the IANA Time Zone Database itself. TC39 is very careful to avoid shipping the wrong API, even if it means a delay.
• Earlier changes in the Temporal proposal removed the ability to do string parsing of custom time zone IDs. This meant that support of custom time zones was partial and incomplete. If we do revisit custom time zones then we'd want to solve this too so that we could have round-trip ability including string parsing.

So to summarize, it seems very, very likely at this point that the current custom time zone implementation will be removed. But it's also likely that there will be lots of demand for a built-in custom timezone solution in a future proposal. And it seems likely that any future solution will use a data format (ideally one based on an existing standard, of which JSCalendar seems closest in spirit to ECMAScript's design) to define a time zone instead of custom userland code.

I know this isn't a great answer for folks who have been interested in making custom time zones, but it does seem like the only realistic path forward so we can get Temporal finally shipped into browsers.

[leftmostcat]

I understand the need for a change in the spec. I'm just hoping it's possible to find a way to provide for use cases where tzdb can't be the source of truth. As noted, it's possible to fall back to tzdb in a lot of cases, but there are common clients out there which don't use standard IDs (Microsoft Exchange, notably). I have trouble seeing a way to implement that with the current API minus custom time zones.

It would be a more invasive change to the proposal, but something like OffsetDateTime instead of ZonedDateTime could potentially offer the same functionality without much change in usability, while potentially also allowing custom time zone definitions.

OffsetDateTime would just store an offset instead of a reference to a time zone. A TimeZone would just need to implement a function mapping an Instant to an offset.

[ptomato]

@leftmostcat You can effectively have OffsetDateTime already, by using ZonedDateTime with a fixed UTC offset, which is also a valid time zone identifier. For example, Temporal.ZonedDateTime.from({ year, month, day, hour, ..., timeZone: '-04:30' }). Would that be sufficient for the use case you're proposing?

[leftmostcat]

@leftmostcat You can effectively have OffsetDateTime already, by using ZonedDateTime with a fixed UTC offset, which is also a valid time zone identifier. For example, Temporal.ZonedDateTime.from({ year, month, day, hour, ..., timeZone: '-04:30' }). Would that be sufficient for the use case you're proposing?

This solution feels problematic, as it means that common operations which are currently part of ZonedDateTime need to be reinvented for any consumer which can't use IANA time zones. For example, ZonedDateTime provides the instance method add() for getting a later ZonedDateTime in the same time zone, while accounting for offset changes, etc. With a pseudo-OffsetDateTime, it's now the consumer's responsibility to understand that the time zone on the ZonedDateTime doesn't represent a real time zone, but an offset, and that add() is inappropriate. It is also the consumer's responsibility to implement their own add() functionality which adds the duration and adjusts the offset. In the end, a "correct" implementation of custom time zones requires careful maintenance of private semantics/invariants, which is one of the big problems I encounter using Date.

Building the API around OffsetDateTime means that the semantics of time zones don't have to be abused to get a correct solution. The spec and naming can make it clear that adding a duration to OffsetDateTime will not account for time zone, and those semantics would be universal across implementations. zonedInstance.add(duration) becomes offsetInstance.add(duration).relativeTo(timeZone), where timeZone is anything with an offsetAt(instant) method. The Temporal global can provide something like Temporal.getIanaTimeZone() to get suitable implementations for standard time zones.