Editorial: Simplify date/time range validation

This commit refactors several operations related to range validation of
Temporal.PlainDateTime and Temporal.Instant.

* Makes polyfill GetUTCEpochNanoseconds infallible, like in the spec.
* Simplifies the polyfill's GetNamedTimeZoneOffsetNanoseconds by using
  the now-infallible GetUTCEpochNanoseconds.
* Adds a new AO GetEpochNanoseconds to DRY date/time/offset=>nanoseconds
  calculations, and changes some call sites of GetUTCEpochNanoseconds
  to use this new AO instead.
* Simplifies the polyfill's PlainDateTime range validation in
  RejectDateTimeRange.
* Clarifies the PlainDateTime docs about that type's valid range.
* Simplifies Instant parsing by using the new GetEpochNanoseconds AO.
* Splits parsing from logic when parsing Instant strings.
* Marks ParseDateTimeUTCOffset as infallible in ParseTemporalInstant.
  Fixes #2637.
* Aligns polyfill to spec for Instant parsing.

docs/plaindatetime.md

@@ -62,8 +62,10 @@ Together, `isoYear`, `isoMonth`, and `isoDay` must represent a valid date in tha
 > **NOTE**: Although Temporal does not deal with leap seconds, dates coming from other software may have a `second` value of 60.
 > This value will cause the constructor will throw, so if you have to interoperate with times that may contain leap seconds, use `Temporal.PlainDateTime.from()` instead.
 
-The range of allowed values for this type is exactly enough that calling `timeZone.getPlainDateTimeFor(instant)` will succeed when `timeZone` is any built-in `Temporal.TimeZone` and `instant` is any valid `Temporal.Instant`.
-If the parameters passed in to this constructor form a date outside of this range, then this function will throw a `RangeError`.
+The range of allowed values for this type is wider (by one nanosecond smaller than one day) on each end than the range of `Temporal.Instant`.
+Because the magnitude of built-in time zones' UTC offset will always be less than 24 hours, this extra range ensures that a valid `Temporal.Instant` can always be converted to a valid `Temporal.PlainDateTime` using any built-in time zone.
+Note that the reverse conversion is not guaranteed to succeed; a valid `Temporal.PlainDateTime` at the edge of its range may, for some built-in time zones, be out of range of `Temporal.Instant`.
+If the parameters passed in to this constructor are out of range, then this function will throw a `RangeError`.
 
 Usually `calendar` will be a string containing the identifier of a built-in calendar, such as `'islamic'` or `'gregory'`.
 Use an object if you need to supply [custom calendar behaviour](./calendar.md#custom-calendars).

polyfill/lib/ecmascript.mjs

@@ -90,8 +90,14 @@ const $isEnumerable = callBound('Object.prototype.propertyIsEnumerable');
 
 const DAY_SECONDS = 86400;
 const DAY_NANOS = bigInt(DAY_SECONDS).multiply(1e9);
-const NS_MIN = bigInt(-DAY_SECONDS).multiply(1e17);
-const NS_MAX = bigInt(DAY_SECONDS).multiply(1e17);
+// Instant range is 100 million days (inclusive) before or after epoch.
+const NS_MIN = DAY_NANOS.multiply(-1e8);
+const NS_MAX = DAY_NANOS.multiply(1e8);
+// PlainDateTime range is 24 hours wider (exclusive) than the Instant range on
+// both ends, to allow for valid Instant=>PlainDateTime conversion for all
+// built-in time zones (whose offsets must have a magnitude less than 24 hours).
+const DATETIME_NS_MIN = NS_MIN.subtract(DAY_NANOS).add(bigInt.one);
+const DATETIME_NS_MAX = NS_MAX.add(DAY_NANOS).subtract(bigInt.one);
 const YEAR_MIN = -271821;
 const YEAR_MAX = 275760;
 const BEFORE_FIRST_DST = bigInt(-388152).multiply(1e13); // 1847-01-01T00:00:00Z
@@ -663,25 +669,12 @@ export function ParseTemporalDurationString(isoString) {
 }
 
 export function ParseTemporalInstant(isoString) {
-  let { year, month, day, hour, minute, second, millisecond, microsecond, nanosecond, offset, z } =
+  const { year, month, day, hour, minute, second, millisecond, microsecond, nanosecond, offset, z } =
     ParseTemporalInstantString(isoString);
 
-  // ParseTemporalInstantString ensures that either `z` or `offset` are non-undefined
+  // ParseTemporalInstantString ensures that either `z` is true or or `offset` is non-undefined
   const offsetNs = z ? 0 : ParseDateTimeUTCOffset(offset);
-  ({ year, month, day, hour, minute, second, millisecond, microsecond, nanosecond } = BalanceISODateTime(
-    year,
-    month,
-    day,
-    hour,
-    minute,
-    second,
-    millisecond,
-    microsecond,
-    nanosecond - offsetNs
-  ));
-  const epochNs = GetUTCEpochNanoseconds(year, month, day, hour, minute, second, millisecond, microsecond, nanosecond);
-  if (epochNs === null) throw new RangeError('DateTime outside of supported range');
-  return epochNs;
+  return GetEpochNanoseconds(year, month, day, hour, minute, second, millisecond, microsecond, nanosecond, offsetNs);
 }
 
 export function RegulateISODate(year, month, day, overflow) {
@@ -1421,19 +1414,7 @@ export function InterpretISODateTimeOffset(
   // for this timezone and date/time.
   if (offsetBehaviour === 'exact' || offsetOpt === 'use') {
     // Calculate the instant for the input's date/time and offset
-    const epochNs = GetUTCEpochNanoseconds(
-      year,
-      month,
-      day,
-      hour,
-      minute,
-      second,
-      millisecond,
-      microsecond,
-      nanosecond
-    );
-    if (epochNs === null) throw new RangeError('ZonedDateTime outside of supported range');
-    return epochNs.minus(offsetNs);
+    return GetEpochNanoseconds(year, month, day, hour, minute, second, millisecond, microsecond, nanosecond, offsetNs);
   }
 
   // "prefer" or "reject"
@@ -2309,9 +2290,12 @@ export function DisambiguatePossibleInstants(possibleInstants, timeZone, dateTim
   const microsecond = GetSlot(dateTime, ISO_MICROSECOND);
   const nanosecond = GetSlot(dateTime, ISO_NANOSECOND);
   const utcns = GetUTCEpochNanoseconds(year, month, day, hour, minute, second, millisecond, microsecond, nanosecond);
-  if (utcns === null) throw new RangeError('DateTime outside of supported range');
-  const dayBefore = new Instant(utcns.minus(86400e9));
-  const dayAfter = new Instant(utcns.plus(86400e9));
+
+  // In the spec, range validation of one day before/after utcns happens here.
+  // In the polyfill, this validation happens in the Instant constructor.
+  const dayBefore = new Instant(utcns.minus(DAY_NANOS));
+  const dayAfter = new Instant(utcns.plus(DAY_NANOS));
+
   const offsetBefore = GetOffsetNanosecondsFor(timeZone, dayBefore);
   const offsetAfter = GetOffsetNanosecondsFor(timeZone, dayAfter);
   const nanoseconds = offsetAfter - offsetBefore;
@@ -2744,28 +2728,8 @@ export function GetAvailableNamedTimeZoneIdentifier(identifier) {
 export function GetNamedTimeZoneOffsetNanoseconds(id, epochNanoseconds) {
   const { year, month, day, hour, minute, second, millisecond, microsecond, nanosecond } =
     GetNamedTimeZoneDateTimeParts(id, epochNanoseconds);
-
-  // The pattern of leap years in the ISO 8601 calendar repeats every 400
-  // years. To avoid overflowing at the edges of the range, we reduce the year
-  // to the remainder after dividing by 400, and then add back all the
-  // nanoseconds from the multiples of 400 years at the end.
-  const reducedYear = year % 400;
-  const yearCycles = (year - reducedYear) / 400;
-  const nsIn400YearCycle = bigInt(400 * 365 + 97).multiply(DAY_NANOS);
-
-  const reducedUTC = GetUTCEpochNanoseconds(
-    reducedYear,
-    month,
-    day,
-    hour,
-    minute,
-    second,
-    millisecond,
-    microsecond,
-    nanosecond
-  );
-  const utc = reducedUTC.plus(nsIn400YearCycle.multiply(yearCycles));
-  return +utc.minus(epochNanoseconds);
+  const utc = GetUTCEpochNanoseconds(year, month, day, hour, minute, second, millisecond, microsecond, nanosecond);
+  return utc.minus(epochNanoseconds).toJSNumber();
 }
 
 export function FormatOffsetTimeZoneIdentifier(offsetMinutes) {
@@ -2782,19 +2746,45 @@ export function FormatDateTimeUTCOffsetRounded(offsetNanoseconds) {
   return FormatOffsetTimeZoneIdentifier(offsetNanoseconds / 60e9);
 }
 
-export function GetUTCEpochNanoseconds(year, month, day, hour, minute, second, millisecond, microsecond, nanosecond) {
+export function GetEpochNanoseconds(
+  year,
+  month,
+  day,
+  hour,
+  minute,
+  second,
+  millisecond,
+  microsecond,
+  nanosecond,
+  offsetNs
+) {
+  let result = GetUTCEpochNanoseconds(year, month, day, hour, minute, second, millisecond, microsecond, nanosecond);
+  if (offsetNs) result = result.subtract(bigInt(offsetNs));
+  ValidateEpochNanoseconds(result);
+  return result;
+}
+
+function GetUTCEpochNanoseconds(year, month, day, hour, minute, second, millisecond, microsecond, nanosecond) {
+  // The pattern of leap years in the ISO 8601 calendar repeats every 400
+  // years. To avoid overflowing at the edges of the range, we reduce the year
+  // to the remainder after dividing by 400, and then add back all the
+  // nanoseconds from the multiples of 400 years at the end.
+  const reducedYear = year % 400;
+  const yearCycles = (year - reducedYear) / 400;
+  const nsIn400YearCycle = bigInt(400 * 365 + 97).multiply(DAY_NANOS);
+
   // Note: Date.UTC() interprets one and two-digit years as being in the
   // 20th century, so don't use it
   const legacyDate = new Date();
   legacyDate.setUTCHours(hour, minute, second, millisecond);
-  legacyDate.setUTCFullYear(year, month - 1, day);
+  legacyDate.setUTCFullYear(reducedYear, month - 1, day);
   const ms = legacyDate.getTime();
-  if (NumberIsNaN(ms)) return null;
   let ns = bigInt(ms).multiply(1e6);
   ns = ns.plus(bigInt(microsecond).multiply(1e3));
   ns = ns.plus(bigInt(nanosecond));
-  if (ns.lesser(NS_MIN) || ns.greater(NS_MAX)) return null;
-  return ns;
+
+  const result = ns.plus(nsIn400YearCycle.multiply(bigInt(yearCycles)));
+  return result;
 }
 
 export function GetISOPartsFromEpoch(epochNanoseconds) {
@@ -2927,6 +2917,11 @@ export function GetFormatterParts(timeZone, epochMilliseconds) {
   };
 }
 
+// The goal of this function is to find the exact time(s) that correspond to a
+// calendar date and clock time in a particular time zone. Normally there will
+// be only one match. But for repeated clock times after backwards transitions
+// (like when DST ends) there may be two matches. And for skipped clock times
+// after forward transitions, there will be no matches.
 export function GetNamedTimeZoneEpochNanoseconds(
   id,
   year,
@@ -2939,15 +2934,17 @@ export function GetNamedTimeZoneEpochNanoseconds(
   microsecond,
   nanosecond
 ) {
+  // Get the offset of one day before and after the requested calendar date and
+  // clock time, avoiding overflows if near the edge of the Instant range.
   let ns = GetUTCEpochNanoseconds(year, month, day, hour, minute, second, millisecond, microsecond, nanosecond);
-  if (ns === null) throw new RangeError('DateTime outside of supported range');
   let nsEarlier = ns.minus(DAY_NANOS);
   if (nsEarlier.lesser(NS_MIN)) nsEarlier = ns;
   let nsLater = ns.plus(DAY_NANOS);
   if (nsLater.greater(NS_MAX)) nsLater = ns;
-  const earliest = GetNamedTimeZoneOffsetNanoseconds(id, nsEarlier);
-  const latest = GetNamedTimeZoneOffsetNanoseconds(id, nsLater);
-  const found = earliest === latest ? [earliest] : [earliest, latest];
+  const earlierOffsetNs = GetNamedTimeZoneOffsetNanoseconds(id, nsEarlier);
+  const laterOffsetNs = GetNamedTimeZoneOffsetNanoseconds(id, nsLater);
+
+  const found = earlierOffsetNs === laterOffsetNs ? [earlierOffsetNs] : [earlierOffsetNs, laterOffsetNs];
   return found
     .map((offsetNanoseconds) => {
       const epochNanoseconds = bigInt(ns).minus(offsetNanoseconds);
@@ -3738,23 +3735,21 @@ export function RejectDateTime(year, month, day, hour, minute, second, milliseco
 }
 
 export function RejectDateTimeRange(year, month, day, hour, minute, second, millisecond, microsecond, nanosecond) {
-  RejectToRange(year, YEAR_MIN, YEAR_MAX);
-  // Reject any DateTime 24 hours or more outside the Instant range
-  if (
-    (year === YEAR_MIN &&
-      null ==
-        GetUTCEpochNanoseconds(year, month, day + 1, hour, minute, second, millisecond, microsecond, nanosecond - 1)) ||
-    (year === YEAR_MAX &&
-      null ==
-        GetUTCEpochNanoseconds(year, month, day - 1, hour, minute, second, millisecond, microsecond, nanosecond + 1))
-  ) {
-    throw new RangeError('DateTime outside of supported range');
+  const ns = GetUTCEpochNanoseconds(year, month, day, hour, minute, second, millisecond, microsecond, nanosecond);
+  if (ns.lesser(DATETIME_NS_MIN) || ns.greater(DATETIME_NS_MAX)) {
+    // Because PlainDateTime's range is wider than Instant's range, the line
+    // below will always throw. Calling `ValidateEpochNanoseconds` avoids
+    // repeating the same error message twice.
+    ValidateEpochNanoseconds(ns);
   }
 }
 
+// In the spec, IsValidEpochNanoseconds returns a boolean and call sites are
+// responsible for throwing. In the polyfill, ValidateEpochNanoseconds takes its
+// place so that we can DRY the throwing code.
 export function ValidateEpochNanoseconds(epochNanoseconds) {
   if (epochNanoseconds.lesser(NS_MIN) || epochNanoseconds.greater(NS_MAX)) {
-    throw new RangeError('Instant outside of supported range');
+    throw new RangeError('date/time value is outside of supported range');
   }
 }
 
@@ -5019,7 +5014,7 @@ export function RoundNumberToIncrement(quantity, increment, mode) {
 }
 
 export function RoundInstant(epochNs, increment, unit, roundingMode) {
-  let { remainder } = NonNegativeBigIntDivmod(epochNs, 86400e9);
+  let { remainder } = NonNegativeBigIntDivmod(epochNs, DAY_NANOS);
   const wholeDays = epochNs.minus(remainder);
   const roundedRemainder = RoundNumberToIncrement(remainder, nsPerTimeUnit[unit] * increment, roundingMode);
   return wholeDays.plus(roundedRemainder);

polyfill/lib/timezone.mjs

@@ -87,7 +87,7 @@ export class TimeZone {
 
     const offsetMinutes = ES.ParseTimeZoneIdentifier(id).offsetMinutes;
     if (offsetMinutes !== undefined) {
-      const epochNs = ES.GetUTCEpochNanoseconds(
+      const epochNs = ES.GetEpochNanoseconds(
         GetSlot(dateTime, ISO_YEAR),
         GetSlot(dateTime, ISO_MONTH),
         GetSlot(dateTime, ISO_DAY),
@@ -96,10 +96,10 @@ export class TimeZone {
         GetSlot(dateTime, ISO_SECOND),
         GetSlot(dateTime, ISO_MILLISECOND),
         GetSlot(dateTime, ISO_MICROSECOND),
-        GetSlot(dateTime, ISO_NANOSECOND)
+        GetSlot(dateTime, ISO_NANOSECOND),
+        offsetMinutes * 60e9
       );
-      if (epochNs === null) throw new RangeError('DateTime outside of supported range');
-      return [new Instant(epochNs.minus(offsetMinutes * 60e9))];
+      return [new Instant(epochNs)];
     }
 
     const possibleEpochNs = ES.GetNamedTimeZoneEpochNanoseconds(

spec/abstractops.html

@@ -1452,7 +1452,7 @@ <h1>
     <h1>
       ParseTemporalInstantString (
         _isoString_: a String,
-      )
+      ): either a normal completion containing a Record, or an abrupt completion
     </h1>
     <dl class="header">
       <dt>description</dt>
@@ -1461,21 +1461,19 @@ <h1>
     <emu-alg>
       1. If ParseText(StringToCodePoints(_isoString_), |TemporalInstantString|) is a List of errors, throw a *RangeError* exception.
       1. Let _result_ be ? ParseISODateTime(_isoString_).
-      1. Let _offsetString_ be _result_.[[TimeZone]].[[OffsetString]].
-      1. If _result_.[[TimeZone]].[[Z]] is *true*, then
-        1. Set _offsetString_ to *"+00:00"*.
-      1. Assert: _offsetString_ is not *undefined*.
+      1. Assert: Either _result_.[[TimeZone]].[[OffsetString]] is not *undefined* or _result_.[[TimeZone]].[[Z]] is *true*, but not both.
       1. Return the Record {
-        [[Year]]: _result_.[[Year]],
-        [[Month]]: _result_.[[Month]],
-        [[Day]]: _result_.[[Day]],
-        [[Hour]]: _result_.[[Hour]],
-        [[Minute]]: _result_.[[Minute]],
-        [[Second]]: _result_.[[Second]],
-        [[Millisecond]]: _result_.[[Millisecond]],
-        [[Microsecond]]: _result_.[[Microsecond]],
-        [[Nanosecond]]: _result_.[[Nanosecond]],
-        [[TimeZoneOffsetString]]: _offsetString_
+          [[Year]]: _result_.[[Year]],
+          [[Month]]: _result_.[[Month]],
+          [[Day]]: _result_.[[Day]],
+          [[Hour]]: _result_.[[Hour]],
+          [[Minute]]: _result_.[[Minute]],
+          [[Second]]: _result_.[[Second]],
+          [[Millisecond]]: _result_.[[Millisecond]],
+          [[Microsecond]]: _result_.[[Microsecond]],
+          [[Nanosecond]]: _result_.[[Nanosecond]],
+          [[OffsetString]]: _result_.[[TimeZone]].[[OffsetString]],
+          [[Z]]: _result_.[[TimeZone]].[[Z]]
         }.
     </emu-alg>
   </emu-clause>

spec/instant.html

@@ -526,16 +526,50 @@ <h1>ToTemporalInstant ( _item_ )</h1>
       </emu-alg>
     </emu-clause>
 
-    <emu-clause id="sec-temporal-parsetemporalinstant" aoid="ParseTemporalInstant">
-      <h1>ParseTemporalInstant ( _isoString_ )</h1>
+    <emu-clause id="sec-temporal-parsetemporalinstant" type="abstract operation">
+      <h1>ParseTemporalInstant (
+        _isoString_: a String
+      ): either a normal completion containing a BigInt, or a throw completion</h1>
+      <dl class="header">
+        <dt>description</dt>
+        <dd>It parses an ISO 8601 string and returns a BigInt representing a number of nanoseconds since the epoch that is represented by that string.</dd>
+      </dl>
       <emu-alg>
         1. Assert: Type(_isoString_) is String.
-        1. Let _result_ be ? ParseTemporalInstantString(_isoString_).
-        1. Let _offsetString_ be _result_.[[TimeZoneOffsetString]].
-        1. Assert: _offsetString_ is not *undefined*.
-        1. Let _utc_ be GetUTCEpochNanoseconds(_result_.[[Year]], _result_.[[Month]], _result_.[[Day]], _result_.[[Hour]], _result_.[[Minute]], _result_.[[Second]], _result_.[[Millisecond]], _result_.[[Microsecond]], _result_.[[Nanosecond]]).
-        1. Let _offsetNanoseconds_ be ? ParseDateTimeUTCOffset(_offsetString_).
-        1. Let _result_ be _utc_ - ℤ(_offsetNanoseconds_).
+        1. Let _parsed_ be ? ParseTemporalInstantString(_isoString_).
+        1. If _parsed_.[[Z]] is *true*, let _offsetNanoseconds_ be 0.
+        1. Else, let _offsetNanoseconds_ be ! ParseDateTimeUTCOffset(_parsed_.[[OffsetString]]).
+        1. Return ? GetEpochNanoseconds(_parsed_.[[Year]], _parsed_.[[Month]], _parsed_.[[Day]], _parsed_.[[Hour]], _parsed_.[[Minute]], _parsed_.[[Second]], _parsed_.[[Millisecond]], _parsed_.[[Microsecond]], _parsed_.[[Nanosecond]], _offsetNanoseconds_).
+      </emu-alg>
+    </emu-clause>
+
+    <emu-clause id="sec-temporal-getepochnanoseconds" type="abstract operation">
+      <h1>
+        GetEpochNanoseconds (
+          _year_: an integer,
+          _month_: an integer,
+          _day_: an integer,
+          _hour_: an integer,
+          _minute_: an integer,
+          _second_: an integer,
+          _millisecond_: an integer,
+          _microsecond_: an integer,
+          _nanosecond_: an integer,
+          _offsetNanoseconds_: an integer,
+        ): either a normal completion containing a BigInt or a throw completion
+      </h1>
+      <dl class="header">
+        <dt>description</dt>
+        <dd>
+          <p>
+            It determines the exact time, in nanoseconds since epoch, corresponding to the given calendar date, time, and time zone offset.
+            If the result is out of range for %Temporal.Instant%, a *RangeError* is thrown.
+          </p>
+        </dd>
+      </dl>
+      <emu-alg>
+        1. Let _result_ be GetUTCEpochNanoseconds(_year_, _month_, _day_, _hour_, _minute_, _second_, _millisecond_, _microsecond_, _nanosecond_).
+        1. If _offsetNanoseconds_ ≠ 0, set _result_ to _result_ - ℤ(_offsetNanoseconds_).
         1. If ! IsValidEpochNanoseconds(_result_) is *false*, then
           1. Throw a *RangeError* exception.
         1. Return _result_.