tc39 / proposal-intl-zoneddatetimeformat

Intl Format for Temporal.ZonedDateTime

Intl ZonedDateTimeFormat Proposal

This is a proposal for Intl.ZonedDateTimeFormat, a new format to support the formating of Temporal.ZonedDateTime object.

Stage

Stage 1

• Slides for Stage 1 Advancement for TC39 2023 May Meeting
  • TG2 May 2023 Discussion
  • TC39 May 2023 Discussion

Moviation

Temporal proposal enhances the pre-existing Intl.DateTimeFormat to support some, but not all, Temporal objects:

• Temporal.PlainDateTime
• Temporal.PlainDate
• Temporal.PlainTime
• Temporal.PlainMonthDay
• Temporal.PlainYearMonth
• Temporal.Instant

Other Temporal objects are prosposed NOT to be be formatted by Intl.DateTimeFormat:

• Temporal.Calendar
• Temporal.TimeZone
• Temporal.Duration: Formatted by Intl.DurationFormat

There was an earlier attempt in the Temporal proposal to change Intl.DateTimeFormat to also format Temporal.ZonedDateTime but cannot reach consensus after endless dicussion about how to resolve the timeZone from both objects.

This proposal proposes a new Intl formatter, Intl.ZonedDateTimeFormat, designed to format Temporal.ZonedDateTime objects and leave Intl.DateTimeFormat not to support the format of Temporal.ZonedDateTime.

Alternative Consideration

What Temporal.ZonedDateTime.prototype.toLocaleString cannot?

Two reasons why we cannot just use Temporal.ZonedDateTime.prototype.toLocaleString but need a new object:

• The need to format a string to represent the time period between TWO Temporal.ZonedDateTime. toLocaleString can only format string for one of them, but not the range between two Temporal.ZonedDateTime. The formatRange (and formtRangeToParts) function will be able to do so in this object.
• Some of the important information could be computed and cashed into the object to speed up some performance during the format function.

Why not just Intl.DateTimeFormat?

Intl.DateTimeFormat was designed to format the Date object which does not contains a timeZone nor a Calendar. The TimeZone and Calendar of the Intl.DateTimeFormat therefore were resolved during the time of the object construction. Temporal.ZonedDateTime, in the other hand, always carry a TimeZone. Reusing Intl.DateTimeFormat to format Temporal.ZonedDateTime would cause conflict of timeZone and damage the purity of the Intl.DateTimeFormat API.

API Proposal

Intl.ZonedDateTimeFormat constructor

• Same as Intl.DateTimeFormat except it will throw RangeError if timeZone is presented in the option bag.

Intl.ZonedDateTimeFormat.supportedLocales()

Intl.ZonedDateTimeFormat.prototype.resolvedOptions()

• without return timeZone

Intl.ZonedDateTimeFormat.prototype.format(x)

• Throw TypeError if x is not a Temporal.ZonedDateTime
• (Later on, we may decide to accept a string which can be used to construct a Temporal.ZonedDateTime )

Intl.ZonedDateTimeFormat.prototype.formatToParts(x)

• Throw TypeError if x is not a Temporal.ZonedDateTime
• (Later on, we may decide to accept a string which can be used to construct a Temporal.ZonedDateTime )

Intl.ZonedDateTimeFormat.prototype.formatRange(x, y)

• Throw TypeError if x is not a Temporal.ZonedDateTime
• Throw TypeError if y is not a Temporal.ZonedDateTime
• Throw RangeError if the timeZone of x and y are different
• (Later on, we may decide to accept string as x or y which can be used to construct a Temporal.ZonedDateTime )

Intl.ZonedDateTimeFormat.prototype.formatRangeToParts(x, y)

• Throw TypeError if x is not a Temporal.ZonedDateTime
• Throw TypeError if y is not a Temporal.ZonedDateTime
• Throw RangeError if the timeZone of x and y are different
• (Later on, we may decide to accept string as x or y which can be used to construct a Temporal.ZonedDateTime )

Intl.ZonedDateTimeFormat.prototype.withTimeZone( [ timeZone ] )

• timeZone could be a valid IANA timezone String or undefined (to indicate the current user timezone).
• return an Intl.DateTimeFormat with the timeZone set to the string or undefined

Intl.DateTimeFormat.prototype.toZonedDateTimeFormat()

• return an Intl.ZonedDateTimeFormat ignoring the timeZone in the internal slot.

---

Below should be removed later

Before creating a proposal

Please ensure the following:

1. You have read the process document
2. You have reviewed the existing proposals
3. You are aware that your proposal requires being a member of TC39, or locating a TC39 delegate to "champion" your proposal

Create your proposal repo

Follow these steps:

1. Click the green "use this template" button in the repo header. (Note: Do not fork this repo in GitHub's web interface, as that will later prevent transfer into the TC39 organization)
2. Update the biblio to the latest version: npm install --save-dev --save-exact @tc39/ecma262-biblio@latest.
3. Go to your repo settings “Options” page, under “GitHub Pages”, and set the source to the main branch under the root (and click Save, if it does not autosave this setting)
   1. check "Enforce HTTPS"
   2. On "Options", under "Features", Ensure "Issues" is checked, and disable "Wiki", and "Projects" (unless you intend to use Projects)
   3. Under "Merge button", check "automatically delete head branches"

3. "How to write a good explainer" explains how to make a good first impression.

   Each TC39 proposal should have a README.md file which explains the purpose of the proposal and its shape at a high level.

   ...

   The rest of this page can be used as a template ...

   Your explainer can point readers to the index.html generated from spec.emu via markdown like

   You can browse the [ecmarkup output](https://ACCOUNT.github.io/PROJECT/)
   or browse the [source](https://github.com/ACCOUNT/PROJECT/blob/HEAD/spec.emu).

   where ACCOUNT and PROJECT are the first two path elements in your project's Github URL. For example, for github.com/tc39/template-for-proposals, ACCOUNT is "tc39" and PROJECT is "template-for-proposals".

Maintain your proposal repo

1. Make your changes to spec.emu (ecmarkup uses HTML syntax, but is not HTML, so I strongly suggest not naming it ".html")
2. Any commit that makes meaningful changes to the spec, should run npm run build and commit the resulting output.
3. Whenever you update ecmarkup, run npm run build and commit any changes that come from that dependency.

proposal-intl-zoneddatetimeformat's Issues

Remove withTimeZone / toZonedDateTimeFormat

During TC39 May 2023 meeting, @justingrant suggest no to include them
"And actually, one more thing is the withTimeZone and two date time zone format, I think it’s a bad idea to teach users that the localization APIs are the places you go to manipulate different Temporal objects like to change time zones or do other things. I think it’s probably best to leave that on the Temporal side and say once you have a thing you like, you can go format it, rather than confuse users with two ways to do the same thing. That’s one of the problems we have now with the existing date time format object is, that there's two places to put a time zone, one and another, and I don’t think we want to multiply that problem. "

Intl.ZonedDateTimeFormat.prototype.withTimeZone( [ timeZone ] )
Intl.DateTimeFormat.prototype.toZonedDateTimeFormat()

Proposal for Stage 1

Opening this issue to track the consensus required for advancing to Stage 1.

TG2 agreement: https://github.com/tc39/ecma402/blob/master/meetings/notes-2023-04-06.md#zoneddatetimeformat