Normative: In `InitializeDateTimeFormat` options, Temporal object or ISO string forms of `calendar` and `timeZone` will throw

[justingrant]

While working on another fix, I noticed unexpected spec text and polyfill behavior for toLocaleString's calendar and timeZone options.

From js-temporal/temporal-polyfill#118:

the spec and the polyfill also accept a ZDT-like property bag too, per tc39/proposal-temporal#925. Specifically, they accept any object with a timeZone property and will use that property's value as the time zone, with one exception: per tc39/proposal-temporal#925 (comment), recursive bags like {timeZone: {timeZone: 'Asia/Tokyo'}} are disallowed.

The above is also true for calendars.

Update 2022-02-13: looks like the same spec text also breaks using ISO strings like "2020-04-25[Europe/Paris][u-ca=islamic]" for the calendar or timeZone options.

Update 2023-05-12: property bag forms of these options are no longer supported. So this issue is now scoped to just Temporal objects and ISO strings.

But AFAICT, a timezone-like or calendar-like object is currently accepted in all places where a TimeZone instance and timezone/calendar ID string are accepted... except toLocaleString methods (and the Temporal-aware Intl.DateTimeFormat constructor). The spec text for these operations coerce the timeZone or calendar option to a string, and then use that string. But if the option is an ISO string or a ZonedDateTime or Plain* instance, then InitializeDateTimeFormat will throw because coercing the option to a string yields something that will never be a timezone nor calendar ID.

I'm assuming that this is a spec bug, because AFAIK our intent was that all places where a calendar or time zone is required will either accept a Temporal.Calendar/Temporal.TimeZone instance, a string ID, an ISO string like 2020-01-01T00:00Z[America/Los_Angeles][u-ca=chinese] or an object like Temporal.ZonedDateTime.

Repro:

zdt = Temporal.ZonedDateTime.from('2000-01-01[Asia/Tokyo][u-ca=japanese]');
// => 2000-01-01T00:00:00+09:00[Asia/Tokyo][u-ca=japanese]
zdt2 = Temporal.ZonedDateTime.from({ year: 2000, month: 1, day: 1, calendar: zdt, timeZone: zdt });
// => Temporal.ZonedDateTime <2000-01-01T00:00:00+09:00[Asia/Tokyo][u-ca=japanese]
zdt.toLocaleString('ja-JP', { calendar: zdt, timeZone: zdt });
// => Uncaught RangeError: Invalid calendar : 2000-01-01T00:00:00+09:00[Asia/Tokyo][u-ca=japanese]

The problematic spec text is here:

### for calendars

6. Let calendar be ? GetOption(options, "calendar", "string", undefined, undefined).
7. If calendar is not undefined, then
  a. If calendar does not match the Unicode Locale Identifier type nonterminal, throw a RangeError exception.

### for time zones

32. Else,
  a. Let timeZone be ? ToString(timeZone).
  b. If the result of IsValidTimeZoneName(timeZone) is false, then
    i. Throw a RangeError exception.

[ptomato]

This is difficult, because these are Intl's calendar and timeZone options, not Temporal's: https://devdocs.io/javascript/global_objects/intl/datetimeformat/datetimeformat
As such, they only accept strings, and would not be able to handle custom calendars and time zones.

I agree this is a confusing inconsistency though. Any ideas on how to solve it?

[justingrant]

A possible way to address this could be for the various toLocaleString implementations to check to see calendar or timeZone options are objects, and if they are then handle the string coercion on the Temporal side. This would fix toLocaleString so at least any Temporal API would be consistent, even if it'd be inconsistent with Intl. This approach would require cloning the options object before handing off to Intl, so I'm not sure if that would cause more problems than it solves.

The other option would be for Intl to also accept property bag inputs too for calendar and timeZone options.

Neither option handles custom calendars/timezones and I think that's OK.

@sffc @ryzokuken @gibson042 what do you think?

[sffc]

In my opinion: Given that Temporal is going into 262, and 402 assumes 262 exists, what I'd eventually like to get to is a world where the normative spec text for DateTimeFormat operates on upgraded Temporal objects. The downgrading to String that we currently do is a hack. That should be limited to perhaps the resolvedOptions impl on DateTimeFormat, but the internal slot can rightfully be a Temporal object.

CC @FrankYFTang

[justingrant]

@sffc I'm not sure I understand your comment so will try to clarify. Today, all of the following are acceptable for a calendar (time zone has same behavior too) parameter to any non-toLocaleString Temporal API:

1. a built-in calendar ID string
2. a Temporal.Calendar instance
3. a CalendarProtocol object that's not a Temporal.Calendar instance
4. any Temporal instance that carries a calendar property
5. any object with a calendar property whose value is (1), (2), or (3).
6. a valid ISO string (if there's no calendar annotation, then the ISO calendar will be used)

My reading of your comment above is that you're talking about (2). Is that correct?

Obviously (3) and the (3)-dependent case of (5) won't work because CalendarProtocol doesn't include text localization features.

But currently (4), (5), and (6) don't work with .toLocaleString() on Temporal objects or with new DateTimeFormat(). Should they?

[sffc]

Yes. Everything that we are coercing to a Calendar in Temporal should also be coerced in Intl.DateTimeFormat.

---

My comment was regarding this section: https://tc39.es/proposal-temporal/#sec-properties-of-intl-datetimeformat-instances

We say "[[Calendar]] is a String value" and "[[TimeZone]] is a String value". I think we should consider generalizing these to be Temporal instances stored in the internal slots. If we did this, then the above question about coercion follows. However, the two questions are decoupled.

[justingrant]

Meeting 2022-01-20: property bag calendar and timeZone options should work in toLocaleString as well as Intl.DateTimeFormat constructor. Should review this with TG2.

[FrankYFTang]

It seems to me that what is required is to create the necessary ECMA402 changes into a PR toward https://tc39.es/proposal-temporal/#sec-temporal-intl and present such PR to TG2 also.

[justingrant]

For whoever PRs this change, here's some code (copied from #925 (comment)) that can be used for tests. I'm not sure if there's already Test262 coverage for the non-Intl uses of bag inputs, so I pasted those below too.

bag = { year: 2020, month: 1, day: 1, timeZone: 'Asia/Tokyo', calendar: 'japanese' };
zdt = Temporal.ZonedDateTime.from(bag);
instant = Temporal.Instant.from('2020-01-01T00:00Z');
plainDate = Temporal.PlainDate.from('2020-01-01');
plainTime = Temporal.PlainTime.from('00:00');
plainTime.toZonedDateTime({ timeZone: bag, plainDate });
instant.toZonedDateTime({ timeZone: 'Europe/London', calendar: bag});
instant.toZonedDateTime({ timeZone: bag, calendar: 'japanese' });
instant.toString({ timeZone: bag });
// the code below will currently throw, but if #2005 is approved then it won't throw
plainDate.toLocaleString('ja-JP', { timeZone: bag, calendar: bag });
new DateTimeFormat('ja-JP', { timeZone: bag, calendar: bag });