Polyfill: Refactor time zone identifier handling

Author: justingrant

polyfill/lib/ecmascript.mjs

@@ -357,13 +357,22 @@ export function RejectTemporalLikeObject(item) {
   }
 }
 
+export function CanonicalizeTimeZoneOffsetString(identifier) {
+  const offsetNs = ParseTimeZoneOffsetString(identifier);
+  return FormatTimeZoneOffsetString(offsetNs);
+}
+
 export function ParseTemporalTimeZone(stringIdent) {
   const { ianaName, offset, z } = ParseTemporalTimeZoneString(stringIdent);
-  if (ianaName) return GetCanonicalTimeZoneIdentifier(ianaName);
+  if (ianaName) {
+    if (IsTimeZoneOffsetString(ianaName)) return CanonicalizeTimeZoneOffsetString(ianaName);
+    const record = GetAvailableNamedTimeZoneIdentifier(ianaName);
+    if (!record) throw new RangeError(`Unrecognized time zone ${ianaName}`);
+    return record.primaryIdentifier;
+  }
   if (z) return 'UTC';
   // if !ianaName && !z then offset must be present
-  const offsetNs = ParseTimeZoneOffsetString(offset);
-  return FormatTimeZoneOffsetString(offsetNs);
+  return CanonicalizeTimeZoneOffsetString(offset);
 }
 
 export function MaybeFormatCalendarAnnotation(calendar, showCalendar) {
@@ -2585,13 +2594,76 @@ export function ParseTimeZoneOffsetString(string) {
   return sign * (((hours * 60 + minutes) * 60 + seconds) * 1e9 + nanoseconds);
 }
 
-export function GetCanonicalTimeZoneIdentifier(timeZoneIdentifier) {
-  if (IsTimeZoneOffsetString(timeZoneIdentifier)) {
-    const offsetNs = ParseTimeZoneOffsetString(timeZoneIdentifier);
-    return FormatTimeZoneOffsetString(offsetNs);
+export function GetAvailableNamedTimeZoneIdentifier(identifier) {
+  // TODO: should there be an assertion here that IsTimeZoneOffsetString returns false?
+  if (IsTimeZoneOffsetString(identifier)) return undefined;
+
+  let primaryIdentifier;
+  try {
+    const formatter = getIntlDateTimeFormatEnUsForTimeZone(String(identifier));
+    primaryIdentifier = formatter.resolvedOptions().timeZone;
+  } catch {
+    return undefined;
+  }
+
+  const lower = ASCIILowercase(identifier);
+  if (ASCIILowercase(primaryIdentifier) === lower) return { identifier: primaryIdentifier, primaryIdentifier };
+
+  // The identifier is an alias (a deprecated identifier that's a synonym for
+  // a primary identifier), so we need to case-normalize the identifier to
+  // match the IANA TZDB, e.g. america/new_york => America/New_York. There's
+  // no built-in way to do this using Intl.DateTimeFormat, but the we can
+  // normalize almost all aliases (modulo a few special cases) using the
+  // TZDB's basic capitalization pattern:
+  // 1. capitalize the first letter of the identifier
+  // 2. capitalize the letter after every slash, dash, or underscore delimiter
+  const standardCase = [...lower]
+    .map((c, i) => (i === 0 || '/-_'.includes(lower[i - 1]) ? c.toUpperCase() : c))
+    .join('');
+  const segments = standardCase.split('/');
+
+  if (segments.length === 1) {
+    // For single-segment legacy IDs, if it's 2-3 chars or contains a number of dash, then
+    // (except for the "GB-Eire" special case) the case-normalized form is all uppercase.
+    // GMT+0, GMT-0, ACT, LHI, NSW, GB, NZ, PRC, ROC, ROK, UCT, GMT, GMT0,
+    // CET, CST6CDT, EET, EST, HST, MET, MST, MST7MDT, PST8PDT, WET, NZ-CHAT, W-SU
+    // Otherwise it's the standard form: first letter capitalized, e.g. Iran, Egypt, Hongkong
+    if (lower === 'gb-eire') return { identifier: 'GB-Eire', primaryIdentifier };
+    return {
+      identifier: lower.length <= 3 || /[-0-9]/.test(lower) ? lower.toUpperCase() : segments[0],
+      primaryIdentifier
+    };
   }
-  const formatter = getIntlDateTimeFormatEnUsForTimeZone(String(timeZoneIdentifier));
-  return formatter.resolvedOptions().timeZone;
+
+  // All Etc zone names are upper case except a few exceptions.
+  if (segments[0] === 'Etc') {
+    const etcName = ['Zulu', 'Greenwich', 'Universal'].includes(segments[1]) ? segments[1] : segments[1].toUpperCase();
+    return { identifier: `Etc/${etcName}`, primaryIdentifier };
+  }
+
+  // Legacy US identifiers like US/Alaska or US/Indiana-Starke. They're always 2 segments and use standard case.
+  if (segments[0] === 'Us') return { identifier: `US/${segments[1]}`, primaryIdentifier };
+
+  // For multi-segment IDs, there's a few special cases in the second/third segments
+  const specialCases = {
+    Act: 'ACT',
+    Lhi: 'LHI',
+    Nsw: 'NSW',
+    Dar_Es_Salaam: 'Dar_es_Salaam',
+    Port_Of_Spain: 'Port_of_Spain',
+    Isle_Of_Man: 'Isle_of_Man',
+    Comodrivadavia: 'ComodRivadavia',
+    Knox_In: 'Knox_IN',
+    Dumontdurville: 'DumontDUrville',
+    Mcmurdo: 'McMurdo',
+    Denoronha: 'DeNoronha',
+    Easterisland: 'EasterIsland',
+    Bajanorte: 'BajaNorte',
+    Bajasur: 'BajaSur'
+  };
+  segments[1] = specialCases[segments[1]] ?? segments[1];
+  if (segments.length > 2) segments[2] = specialCases[segments[2]] ?? segments[2];
+  return { identifier: segments.join('/'), primaryIdentifier };
 }
 
 export function GetNamedTimeZoneOffsetNanoseconds(id, epochNanoseconds) {

polyfill/lib/intl.mjs

@@ -21,7 +21,8 @@ const TIME = Symbol('time');
 const DATETIME = Symbol('datetime');
 const INST = Symbol('instant');
 const ORIGINAL = Symbol('original');
-const TZ_RESOLVED = Symbol('timezone');
+const TZ_CANONICAL = Symbol('timezone-canonical');
+const TZ_ORIGINAL = Symbol('timezone-original');
 const CAL_ID = Symbol('calendar-id');
 const LOCALE = Symbol('locale');
 const OPTIONS = Symbol('options');
@@ -81,14 +82,33 @@ export function DateTimeFormat(locale = undefined, options = undefined) {
 
   this[LOCALE] = ro.locale;
   this[ORIGINAL] = original;
-  this[TZ_RESOLVED] = ro.timeZone;
+  this[TZ_CANONICAL] = ro.timeZone;
   this[CAL_ID] = ro.calendar;
   this[DATE] = dateAmend;
   this[YM] = yearMonthAmend;
   this[MD] = monthDayAmend;
   this[TIME] = timeAmend;
   this[DATETIME] = datetimeAmend;
   this[INST] = instantAmend;
+
+  // Save the original time zone, for a few reasons:
+  // - Clearer error messages
+  // - More clearly follows the spec for InitializeDateTimeFormat
+  // - Because it follows the spec more closely, will make it easier to integrate
+  //   support of offset strings and other potential changes like proposal-canonical-tz.
+  const timeZoneOption = hasOptions ? options.timeZone : undefined;
+  if (timeZoneOption === undefined) {
+    this[TZ_ORIGINAL] = ro.timeZone;
+  } else {
+    const id = ES.ToString(timeZoneOption);
+    if (ES.IsTimeZoneOffsetString(id)) {
+      // Note: https://github.com/tc39/ecma402/issues/683 will remove this
+      throw new RangeError('Intl.DateTimeFormat does not currently support offset time zones');
+    }
+    const record = ES.GetAvailableNamedTimeZoneIdentifier(id);
+    if (!record) throw new RangeError(`Intl.DateTimeFormat formats built-in time zones, not ${id}`);
+    this[TZ_ORIGINAL] = record.primaryIdentifier;
+  }
 }
 
 DateTimeFormat.supportedLocalesOf = function (...args) {
@@ -118,7 +138,9 @@ Object.defineProperty(DateTimeFormat, 'prototype', {
 });
 
 function resolvedOptions() {
-  return this[ORIGINAL].resolvedOptions();
+  const resolved = this[ORIGINAL].resolvedOptions();
+  resolved.timeZone = this[TZ_ORIGINAL];
+  return resolved;
 }
 
 function format(datetime, ...rest) {
@@ -335,7 +357,7 @@ function extractOverrides(temporalObj, main) {
     const nanosecond = GetSlot(temporalObj, ISO_NANOSECOND);
     const datetime = new DateTime(1970, 1, 1, hour, minute, second, millisecond, microsecond, nanosecond, main[CAL_ID]);
     return {
-      instant: ES.GetInstantFor(main[TZ_RESOLVED], datetime, 'compatible'),
+      instant: ES.GetInstantFor(main[TZ_CANONICAL], datetime, 'compatible'),
       formatter: getPropLazy(main, TIME)
     };
   }
@@ -352,7 +374,7 @@ function extractOverrides(temporalObj, main) {
     }
     const datetime = new DateTime(isoYear, isoMonth, referenceISODay, 12, 0, 0, 0, 0, 0, calendar);
     return {
-      instant: ES.GetInstantFor(main[TZ_RESOLVED], datetime, 'compatible'),
+      instant: ES.GetInstantFor(main[TZ_CANONICAL], datetime, 'compatible'),
       formatter: getPropLazy(main, YM)
     };
   }
@@ -369,7 +391,7 @@ function extractOverrides(temporalObj, main) {
     }
     const datetime = new DateTime(referenceISOYear, isoMonth, isoDay, 12, 0, 0, 0, 0, 0, calendar);
     return {
-      instant: ES.GetInstantFor(main[TZ_RESOLVED], datetime, 'compatible'),
+      instant: ES.GetInstantFor(main[TZ_CANONICAL], datetime, 'compatible'),
       formatter: getPropLazy(main, MD)
     };
   }
@@ -384,7 +406,7 @@ function extractOverrides(temporalObj, main) {
     }
     const datetime = new DateTime(isoYear, isoMonth, isoDay, 12, 0, 0, 0, 0, 0, main[CAL_ID]);
     return {
-      instant: ES.GetInstantFor(main[TZ_RESOLVED], datetime, 'compatible'),
+      instant: ES.GetInstantFor(main[TZ_CANONICAL], datetime, 'compatible'),
       formatter: getPropLazy(main, DATE)
     };
   }
@@ -421,7 +443,7 @@ function extractOverrides(temporalObj, main) {
       );
     }
     return {
-      instant: ES.GetInstantFor(main[TZ_RESOLVED], datetime, 'compatible'),
+      instant: ES.GetInstantFor(main[TZ_CANONICAL], datetime, 'compatible'),
       formatter: getPropLazy(main, DATETIME)
     };
   }

polyfill/lib/timezone.mjs

@@ -26,8 +26,14 @@ export class TimeZone {
     if (arguments.length < 1) {
       throw new RangeError('missing argument: identifier is required');
     }
-
-    timeZoneIdentifier = ES.GetCanonicalTimeZoneIdentifier(timeZoneIdentifier);
+    timeZoneIdentifier = ES.ToString(timeZoneIdentifier);
+    if (ES.IsTimeZoneOffsetString(timeZoneIdentifier)) {
+      timeZoneIdentifier = ES.CanonicalizeTimeZoneOffsetString(timeZoneIdentifier);
+    } else {
+      const record = ES.GetAvailableNamedTimeZoneIdentifier(timeZoneIdentifier);
+      if (!record) throw new RangeError(`Invalid time zone identifier: ${timeZoneIdentifier}`);
+      timeZoneIdentifier = record.primaryIdentifier;
+    }
     CreateSlots(this);
     SetSlot(this, TIMEZONE_ID, timeZoneIdentifier);
 

polyfill/lib/zoneddatetime.mjs

@@ -472,13 +472,15 @@ export class ZonedDateTime {
       // The rest of the defaults will be filled in by formatting the Instant
     }
 
-    let timeZone = ES.ToTemporalTimeZoneIdentifier(GetSlot(this, TIME_ZONE));
-    if (ES.IsTimeZoneOffsetString(timeZone)) {
+    const timeZoneIdentifier = ES.ToTemporalTimeZoneIdentifier(GetSlot(this, TIME_ZONE));
+    if (ES.IsTimeZoneOffsetString(timeZoneIdentifier)) {
       // Note: https://github.com/tc39/ecma402/issues/683 will remove this
-      throw new RangeError('toLocaleString does not support offset string time zones');
+      throw new RangeError('toLocaleString does not currently support offset time zones');
+    } else {
+      const record = ES.GetAvailableNamedTimeZoneIdentifier(timeZoneIdentifier);
+      if (!record) throw new RangeError(`toLocaleString formats built-in time zones, not ${timeZoneIdentifier}`);
+      optionsCopy.timeZone = record.primaryIdentifier;
     }
-    timeZone = ES.GetCanonicalTimeZoneIdentifier(timeZone);
-    optionsCopy.timeZone = timeZone;
 
     const formatter = new DateTimeFormat(locales, optionsCopy);