Editorial: refactor time zone identifier spec text

justingrant · justingrant · commit 8f36268ef8fa · 2023-05-17T22:53:27.000-07:00
This commit simplifies and clarifies spec text related to time zone identifiers. Goals include making it easier to integrate Temporal into ECMA-262 soon, and simplifying both Temporal and ECMA-402 spec text by centralizing common logic in ECMA-262. If this commit is merged into ECMA-262, editorial PRs will follow for Temporal (draft: tc39/proposal-temporal#2573) and ECMA-402 (draft TBD) to leverage the updated spec text and AOs to simplify those specs. Changes: * Adds editorial spec text explaining how time zone identifiers work in ECMAScript, and pointing readers to 402 for implementations that use the IANA TimeZoneDatabase. * Adds definitions related to time zone identifiers. * Renames `DefaultTimeZone` to `SystemTimeZoneIdentifier` in order to more clearly match its intent. * Removes the need to override `SystemTimeZoneIdentifier` in ECMA-402. * Renames variables named _timeZone_ to _timeZoneIdentifier_ to avoid future ambiguity with `Temporal.TimeZone`. * Adds text that more clearly explains existing spec text allowing non-402 implementations to support non-UTC time zones. * Adds new abstract operation `AvailableNamedTimeZoneIdentifiers` which, along with the existing (renamed) `SystemTimeZoneIdentifier`, enables all ECMA-402 and Temporal operations related to time zone identifiers to be implemented on top of these AOs.
diff --git a/esmeta-ignore.json b/esmeta-ignore.json
@@ -33,7 +33,6 @@
   "GetPrototypeFromConstructor",
   "GetThisValue",
   "HostEnqueuePromiseJob",
-  "INTRINSICS.DefaultTimeZone",
   "InnerModuleEvaluation",
   "IntegerIndexedObjectCreate",
   "LabelledItem[1,0].LabelledEvaluation",
diff --git a/spec.html b/spec.html
@@ -32143,6 +32143,33 @@ <h1>
         </emu-alg>
       </emu-clause>
 
+      <emu-clause id="sec-time-zone-identifiers">
+        <h1>Time Zone Identifiers</h1>
+
+        <p>
+          Time zones in ECMAScript are described using <dfn variants="time zone identifier">time zone identifiers</dfn>, which must be Strings composed entirely of characters from the Unicode Basic Latin block.
+          Time zone identifiers are case-insensitive and so are compared using ASCII case-insensitive comparisons.
+          Built-in time zones may be <dfn variants="named time zone">named time zones</dfn>, represented by the [[Identifier]] property of the records returned by AvailableTimeZoneIdentifiers.
+          They may also be <dfn variants="offset time zone">offset time zones</dfn>, represented by Strings for which IsTimeZoneOffsetString returns *true*.
+        </p>
+        <p>
+          A <dfn variants="primary time zone identifiers">primary time zone identifier</dfn> represents the preferred identifier of a named time zone, while a <dfn variants="non-primary time zone identifiers">non-primary time zone identifier</dfn> is an alternate identifier for the same named time zone.
+          The set of built-in, named time zone identifiers (both primary and non-primary) that are supported by an ECMAScript implementation are called available time zone identifiers.
+        </p>
+        <p>
+          At a minimum, ECMAScript implementations must support a built-in time zone with the identifier *"UTC"*, which must be primary.
+          If the return value _tz_ of SystemTimeZoneIdentifier is different from *"UTC"*, and IsTimeZoneOffsetString(_tz_) is *false*, then implementations must also support _tz_ as a built-in time zone identifier, and it must be primary as well.
+          In addition, implementations may support any number of other built-in time zones.
+        </p>
+        <p>
+          Implementations that follow the requirements for time zones as described in the ECMA-402 Internationalization API specification are called <dfn>time zone aware</dfn>.
+          Time zone aware implementations must define built-in named time zones corresponding to the Zone and Link names of the IANA Time Zone Database (and <strong>only</strong> such names) and use best available current and historical information about their offsets from UTC and their daylight saving time rules in calculations as specified in the ECMA-402 specification.
+          An ECMAScript implementation that includes the ECMA-402 Internationalization API <b>must</b> be time zone aware.
+          However, it is recommended that all ECMAScript implementations be time zone aware, including those that do not implement the ECMA-402 Internationalization API.
+          Furthermore, even non-time zone aware implementations that do not support the entire IANA Time Zone Database are still recommended to use IANA Time Zone Database names as identifiers to represent time zones.
+        </p>
+      </emu-clause>
+
       <emu-clause id="sec-getnamedtimezoneepochnanoseconds" type="implementation-defined abstract operation">
         <h1>
           GetNamedTimeZoneEpochNanoseconds (
@@ -32176,7 +32203,7 @@ <h1>
           1. Return « _epochNanoseconds_ ».
         </emu-alg>
         <emu-note>
-          <p>It is recommended that implementations use the time zone information of the IANA Time Zone Database <a href="https://www.iana.org/time-zones/">https://www.iana.org/time-zones/</a>.</p>
+          <p>It is required for time zone aware implementations (and recommended for all others) to use the time zone information of the IANA Time Zone Database <a href="https://www.iana.org/time-zones/">https://www.iana.org/time-zones/</a>.</p>
           <p>1:30 AM on 5 November 2017 in America/New_York is repeated twice, so GetNamedTimeZoneEpochNanoseconds(*"America/New_York"*, 2017, 11, 5, 1, 30, 0, 0, 0, 0) would return a List of length 2 in which the first element represents 05:30 UTC (corresponding with 01:30 US Eastern Daylight Time at UTC offset -04:00) and the second element represents 06:30 UTC (corresponding with 01:30 US Eastern Standard Time at UTC offset -05:00).</p>
           <p>2:30 AM on 12 March 2017 in America/New_York does not exist, so GetNamedTimeZoneEpochNanoseconds(*"America/New_York"*, 2017, 3, 12, 2, 30, 0, 0, 0, 0) would return an empty List.</p>
         </emu-note>
@@ -32202,26 +32229,88 @@ <h1>
         </emu-note>
       </emu-clause>
 
-      <emu-clause id="sec-defaulttimezone" type="implementation-defined abstract operation">
-        <h1>DefaultTimeZone ( ): a String</h1>
+      <emu-clause id="sec-time-zone-identifier-record">
+        <h1>Time Zone Identifier Record</h1>
+        <p>A <dfn variants="Time Zone Identifier Records">Time Zone Identifier Record</dfn> is a Record used to describe an available time zone identifier, as well as the primary time zone identifier corresponding to it.</p>
+        <p>Time Zone Identifier Records have the fields listed in <emu-xref href="#table-time-zone-identifier-record-fields"></emu-xref>.</p>
+        <emu-table id="table-time-zone-identifier-record-fields" caption="Time Zone Identifier Record Fields">
+          <table>
+            <tr>
+              <th>Field Name</th>
+              <th>Value</th>
+              <th>Meaning</th>
+            </tr>
+            <tr>
+              <td>[[Identifier]]</td>
+              <td>a String</td>
+              <td>An available time zone identifier that is supported by the implementation.</td>
+            </tr>
+            <tr>
+              <td>[[PrimaryIdentifier]]</td>
+              <td>a String</td>
+              <td>The primary time zone identifier that [[Identifier]] resolves to.</td>
+            </tr>
+          </table>
+        </emu-table>
+        <emu-note>
+          <p>If [[Identifier]] is a primary time zone identifier, then [[Identifier]] will be [[PrimaryIdentifier]].</p>
+        </emu-note>
+      </emu-clause>
+
+      <emu-clause id="sec-availabletimezoneidentifiers" type="implementation-defined abstract operation">
+        <h1>AvailableTimeZoneIdentifiers ( ): a List of Time Zone Identifier Records</h1>
         <dl class="header">
           <dt>description</dt>
-          <dd>It returns a String value representing the host environment's current time zone, which is either a String representing a UTC offset for which IsTimeZoneOffsetString returns *true*, or a String identifier accepted by GetNamedTimeZoneEpochNanoseconds and GetNamedTimeZoneOffsetNanoseconds.</dd>
+          <dd>
+            Its result describes all available time zone identifiers in this implementation, as well as the primary time zone identifier corresponding to each available identifier.
+            The List is sorted by [[Identifier]] of each Time Zone Identifier Record.
+          </dd>
         </dl>
+        <p>
+          Time zone aware implementations, including all implementations that implement the ECMA-402 Internationalization API, must implement the AvailableTimeZoneIdentifiers abstract operation as specified in the ECMA-402 specification.
+          For implementations that are not time zone aware, the following specification is used.
+        </p>
+        <emu-alg>
+          1. If the implementation does not include local political rules for any time zones, then
+            1. Return a new List containing only one element: the Time Zone Identifier Record { [[Identifier]]: *"UTC"*, [[PrimaryIdentifier]]: *"UTC"* }.
+          1. Let _identifiers_ be the List of String values representing time zones supported by the implementation.
+          1. [declared="comparefn"] Sort _identifiers_ into the same order as if an Array of the same values had been sorted using %Array.prototype.sort% with *undefined* as _comparefn_.
+          1. Let _result_ be a new empty List.
+          1. For each element _identifier_ of _identifiers_, do
+            1. Let _primary_ be _identifier_.
+            1. If _identifier_ is a non-primary time zone identifier in this implementation and _identifier_ is not *"UTC"*, then
+              1. Set _primary_ to the name of the primary time zone identifier that _identifier_ resolves to in this implementation.
+              1. NOTE: If _identifier_ resolves to another non-primary time zone identifier, then the implementation must continue resolution of the entire chain until its terminal primary time zone identifier.
+            1. Let _record_ be the Time Zone Identifier Record { [[Identifier]]: _identifier_, [[PrimaryIdentifier]]: _primary_ }.
+            1. Append _record_ to the end of _result_.
+          1. Assert: One element of _result_ is the Time Zone Identifier Record { [[Identifier]]: *"UTC"*, [[PrimaryIdentifier]]: *"UTC"* }.
+          1. Return _result_.
+        </emu-alg>
+      </emu-clause>
 
-        <p>An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement the DefaultTimeZone abstract operation as specified in the ECMA-402 specification.</p>
-        <p>The default implementation of DefaultTimeZone, to be used for ECMAScript implementations that do not include local political rules for any time zones, performs the following steps when called:</p>
+      <emu-clause id="sec-systemtimezoneidentifier" oldids="sec-defaulttimezone" type="implementation-defined abstract operation">
+        <h1>SystemTimeZoneIdentifier ( ): a String</h1>
+        <dl class="header">
+          <dt>description</dt>
+          <dd>
+            It returns a String value representing the environment's current time zone, which is either a String representing a UTC offset for which IsTimeZoneOffsetString returns *true*, or a primary time zone identifier.
+          </dd>
+        </dl>
 
         <emu-alg>
-          1. Return *"UTC"*.
+          1. If the implementation only supports the UTC time zone, return *"UTC"*.
+          1. Let _systemTimeZoneString_ be the String representing the host environment's current time zone, either a time zone identifier or a UTC offset string.
+          1. If IsTimeZoneOffsetString(_systemTimeZoneString_) is *true*, return _systemTimeZoneString_.
+          1. Assert: _systemTimeZoneString_ is equal to the [[PrimaryIdentifier]] property of at least one Time Zone Identifier Record returned by AvailableTimeZoneIdentifiers().
+          1. Return _systemTimeZoneString_.
         </emu-alg>
 
         <emu-note>
           <p>
-            To ensure the level of functionality that implementations commonly provide in the methods of the Date object, it is recommended that DefaultTimeZone return an IANA time zone name corresponding to the host environment's time zone setting, if such a thing exists.
+            To ensure the level of functionality that implementations commonly provide in the methods of the Date object, it is recommended that SystemTimeZoneIdentifier return an IANA time zone name corresponding to the host environment's time zone setting, if such a thing exists.
             GetNamedTimeZoneEpochNanoseconds and GetNamedTimeZoneOffsetNanoseconds must reflect the local political rules for standard time and daylight saving time in that time zone, if such rules exist.
           </p>
-          <p>For example, if the host environment is a browser on a system where the user has chosen US Eastern Time as their time zone, DefaultTimeZone returns *"America/New_York"*.</p>
+          <p>For example, if the host environment is a browser on a system where the user has chosen US Eastern Time as their time zone, SystemTimeZoneIdentifier returns *"America/New_York"*.</p>
         </emu-note>
       </emu-clause>
 
@@ -32239,17 +32328,17 @@ <h1>
           </dd>
         </dl>
         <emu-alg>
-          1. Let _localTimeZone_ be DefaultTimeZone().
-          1. If IsTimeZoneOffsetString(_localTimeZone_) is *true*, then
-            1. Let _offsetNs_ be ParseTimeZoneOffsetString(_localTimeZone_).
+          1. Let _systemTimeZoneIdentifier_ be SystemTimeZoneIdentifier().
+          1. If IsTimeZoneOffsetString(_systemTimeZoneIdentifier_) is *true*, then
+            1. Let _offsetNs_ be ParseTimeZoneOffsetString(_systemTimeZoneIdentifier_).
           1. Else,
-            1. Let _offsetNs_ be GetNamedTimeZoneOffsetNanoseconds(_localTimeZone_, ℤ(ℝ(_t_) × 10<sup>6</sup>)).
+            1. Let _offsetNs_ be GetNamedTimeZoneOffsetNanoseconds(_systemTimeZoneIdentifier_, ℤ(ℝ(_t_) × 10<sup>6</sup>)).
           1. Let _offsetMs_ be truncate(_offsetNs_ / 10<sup>6</sup>).
           1. Return _t_ + 𝔽(_offsetMs_).
         </emu-alg>
-        <p>If political rules for the local time _t_ are not available within the implementation, the result is _t_ because DefaultTimeZone returns *"UTC"* and GetNamedTimeZoneOffsetNanoseconds returns 0.</p>
+        <p>If political rules for the local time _t_ are not available within the implementation, the result is _t_ because SystemTimeZoneIdentifier returns *"UTC"* and GetNamedTimeZoneOffsetNanoseconds returns 0.</p>
         <emu-note>
-          <p>It is recommended that implementations use the time zone information of the IANA Time Zone Database <a href="https://www.iana.org/time-zones/">https://www.iana.org/time-zones/</a>.</p>
+          <p>It is required for time zone aware implementations (and recommended for all others) to use the time zone information of the IANA Time Zone Database <a href="https://www.iana.org/time-zones/">https://www.iana.org/time-zones/</a>.</p>
         </emu-note>
         <emu-note>
           <p>Two different input time values <emu-eqn>_t_<sub>UTC</sub></emu-eqn> are converted to the same local time <emu-eqn>t<sub>local</sub></emu-eqn> at a negative time zone transition when there are repeated times (e.g. the daylight saving time ends or the time zone adjustment is decreased.).</p>
@@ -32271,19 +32360,19 @@ <h1>
           </dd>
         </dl>
         <emu-alg>
-          1. Let _localTimeZone_ be DefaultTimeZone().
-          1. If IsTimeZoneOffsetString(_localTimeZone_) is *true*, then
-            1. Let _offsetNs_ be ParseTimeZoneOffsetString(_localTimeZone_).
+          1. Let _systemTimeZoneIdentifier_ be SystemTimeZoneIdentifier().
+          1. If IsTimeZoneOffsetString(_systemTimeZoneIdentifier_) is *true*, then
+            1. Let _offsetNs_ be ParseTimeZoneOffsetString(_systemTimeZoneIdentifier_).
           1. Else,
-            1. Let _possibleInstants_ be GetNamedTimeZoneEpochNanoseconds(_localTimeZone_, ℝ(YearFromTime(_t_)), ℝ(MonthFromTime(_t_)) + 1, ℝ(DateFromTime(_t_)), ℝ(HourFromTime(_t_)), ℝ(MinFromTime(_t_)), ℝ(SecFromTime(_t_)), ℝ(msFromTime(_t_)), 0, 0).
+            1. Let _possibleInstants_ be GetNamedTimeZoneEpochNanoseconds(_systemTimeZoneIdentifier_, ℝ(YearFromTime(_t_)), ℝ(MonthFromTime(_t_)) + 1, ℝ(DateFromTime(_t_)), ℝ(HourFromTime(_t_)), ℝ(MinFromTime(_t_)), ℝ(SecFromTime(_t_)), ℝ(msFromTime(_t_)), 0, 0).
             1. NOTE: The following steps ensure that when _t_ represents local time repeating multiple times at a negative time zone transition (e.g. when the daylight saving time ends or the time zone offset is decreased due to a time zone rule change) or skipped local time at a positive time zone transition (e.g. when the daylight saving time starts or the time zone offset is increased due to a time zone rule change), _t_ is interpreted using the time zone offset before the transition.
             1. If _possibleInstants_ is not empty, then
               1. Let _disambiguatedInstant_ be _possibleInstants_[0].
             1. Else,
               1. NOTE: _t_ represents a local time skipped at a positive time zone transition (e.g. due to daylight saving time starting or a time zone rule change increasing the UTC offset).
-              1. [declared="tBefore"] Let _possibleInstantsBefore_ be GetNamedTimeZoneEpochNanoseconds(_localTimeZone_, ℝ(YearFromTime(_tBefore_)), ℝ(MonthFromTime(_tBefore_)) + 1, ℝ(DateFromTime(_tBefore_)), ℝ(HourFromTime(_tBefore_)), ℝ(MinFromTime(_tBefore_)), ℝ(SecFromTime(_tBefore_)), ℝ(msFromTime(_tBefore_)), 0, 0), where _tBefore_ is the largest integral Number &lt; _t_ for which _possibleInstantsBefore_ is not empty (i.e., _tBefore_ represents the last local time before the transition).
+              1. [declared="tBefore"] Let _possibleInstantsBefore_ be GetNamedTimeZoneEpochNanoseconds(_systemTimeZoneIdentifier_, ℝ(YearFromTime(_tBefore_)), ℝ(MonthFromTime(_tBefore_)) + 1, ℝ(DateFromTime(_tBefore_)), ℝ(HourFromTime(_tBefore_)), ℝ(MinFromTime(_tBefore_)), ℝ(SecFromTime(_tBefore_)), ℝ(msFromTime(_tBefore_)), 0, 0), where _tBefore_ is the largest integral Number &lt; _t_ for which _possibleInstantsBefore_ is not empty (i.e., _tBefore_ represents the last local time before the transition).
               1. Let _disambiguatedInstant_ be the last element of _possibleInstantsBefore_.
-            1. Let _offsetNs_ be GetNamedTimeZoneOffsetNanoseconds(_localTimeZone_, _disambiguatedInstant_).
+            1. Let _offsetNs_ be GetNamedTimeZoneOffsetNanoseconds(_systemTimeZoneIdentifier_, _disambiguatedInstant_).
           1. Let _offsetMs_ be truncate(_offsetNs_ / 10<sup>6</sup>).
           1. Return _t_ - 𝔽(_offsetMs_).
         </emu-alg>
@@ -32293,9 +32382,9 @@ <h1>
           For example, the maximum time value is 8.64 × 10<sup>15</sup>, corresponding with *"+275760-09-13T00:00:00Z"*.
           In an environment where the local time zone offset is ahead of UTC by 1 hour at that instant, it is represented by the larger input of 8.64 × 10<sup>15</sup> + 3.6 × 10<sup>6</sup>, corresponding with *"+275760-09-13T01:00:00+01:00"*.
         </p>
-        <p>If political rules for the local time _t_ are not available within the implementation, the result is _t_ because DefaultTimeZone returns *"UTC"* and GetNamedTimeZoneOffsetNanoseconds returns 0.</p>
+        <p>If political rules for the local time _t_ are not available within the implementation, the result is _t_ because SystemTimeZoneIdentifier returns *"UTC"* and GetNamedTimeZoneOffsetNanoseconds returns 0.</p>
         <emu-note>
-          <p>It is recommended that implementations use the time zone information of the IANA Time Zone Database <a href="https://www.iana.org/time-zones/">https://www.iana.org/time-zones/</a>.</p>
+          <p>It is required for time zone aware implementations (and recommended for all others) to use the time zone information of the IANA Time Zone Database <a href="https://www.iana.org/time-zones/">https://www.iana.org/time-zones/</a>.</p>
           <p>
             1:30 AM on 5 November 2017 in America/New_York is repeated twice (fall backward), but it must be interpreted as 1:30 AM UTC-04 instead of 1:30 AM UTC-05.
             In UTC(TimeClip(MakeDate(MakeDay(2017, 10, 5), MakeTime(1, 30, 0, 0)))), the value of _offsetMs_ is <emu-eqn>-4 × msPerHour</emu-eqn>.
@@ -33625,11 +33714,11 @@ <h1>
           <dl class="header">
           </dl>
           <emu-alg>
-            1. Let _localTimeZone_ be DefaultTimeZone().
-            1. If IsTimeZoneOffsetString(_localTimeZone_) is *true*, then
-              1. Let _offsetNs_ be ParseTimeZoneOffsetString(_localTimeZone_).
+            1. Let _systemTimeZoneIdentifier_ be SystemTimeZoneIdentifier().
+            1. If IsTimeZoneOffsetString(_systemTimeZoneIdentifier_) is *true*, then
+              1. Let _offsetNs_ be ParseTimeZoneOffsetString(_systemTimeZoneIdentifier_).
             1. Else,
-              1. Let _offsetNs_ be GetNamedTimeZoneOffsetNanoseconds(_localTimeZone_, ℤ(ℝ(_tv_) × 10<sup>6</sup>)).
+              1. Let _offsetNs_ be GetNamedTimeZoneOffsetNanoseconds(_systemTimeZoneIdentifier_, ℤ(ℝ(_tv_) × 10<sup>6</sup>)).
             1. Let _offset_ be 𝔽(truncate(_offsetNs_ / 10<sup>6</sup>)).
             1. If _offset_ is *+0*<sub>𝔽</sub> or _offset_ > *+0*<sub>𝔽</sub>, then
               1. Let _offsetSign_ be *"+"*.
