@engine262/engine262 0.0.1-01e9fa95a4e8a1c042efd00492309a2de4998fd0

package/src/abstract-ops/temporal/time-zone.mts

@@ -0,0 +1,304 @@
+import type { ISODateRecord } from '../../intrinsics/Temporal/PlainDate.mts';
+import type { ISODateTimeRecord } from '../../intrinsics/Temporal/PlainDateTime.mts';
+import { ParseTemporalTimeZoneString, ParseTimeZoneIdentifier } from '../../parser/TemporalParser.mts';
+import {
+  HourFromTime, MinFromTime, SecFromTime, MillisecFromTime,
+} from '../date-objects.mts';
+import { isTemporalZonedDateTimeObject } from '../../intrinsics/Temporal/ZonedDateTime.mts';
+import { abs, floorDiv, modulo } from '../math.mts';
+import { Decimal } from '../../host-defined/decimal.mts';
+import {
+  IsOffsetTimeZoneIdentifier, GetNamedTimeZoneEpochNanoseconds, GetUTCEpochNanoseconds, RoundingMode,
+  AvailableNamedTimeZoneIdentifiers,
+  GetNamedTimeZoneOffsetNanoseconds,
+} from './addition.mts';
+import type { TimeZoneIdentifier } from './addition.mts';
+import {
+  RoundNumberToIncrement, EpochTimeToDate, EpochTimeToEpochYear, EpochTimeToMonthInYear, CheckISODaysRange,
+  FormatTimeString,
+  TemporalUnit,
+  type EpochNanoseconds,
+} from './temporal.mts';
+import {
+  Assert, JSStringValue, ObjectValue, Value, type PlainCompletion, Q,
+  Throw,
+  X,
+  AddDaysToISODate,
+  AddTime,
+  BalanceISODateTime,
+  CombineISODateAndTimeRecord,
+  IsValidEpochNanoseconds,
+  MidnightTimeRecord,
+  NanosecondsPerDay,
+  TimeDurationFromComponents,
+  type Integer,
+  CompareISODateTime,
+} from '#self';
+
+// https://tc39.es/proposal-temporal/#sec-temporal-getavailablenamedtimezoneidentifier
+export function GetAvailableNamedTimeZoneIdentifier(timeZoneIdentifier: TimeZoneIdentifier): TimeZoneIdentifierRecord | undefined {
+  for (const record of AvailableNamedTimeZoneIdentifiers()) {
+    if (record.Identifier.toLowerCase() === timeZoneIdentifier.toLowerCase()) {
+      return record;
+    }
+  }
+  return undefined;
+}
+
+/** https://tc39.es/ecma262/#sec-time-zone-identifier-record */
+export interface TimeZoneIdentifierRecord {
+  readonly Identifier: TimeZoneIdentifier;
+  readonly PrimaryIdentifier: TimeZoneIdentifier;
+}
+
+// https://tc39.es/proposal-temporal/#sec-temporal-getnamedtimezonenexttransition
+export function GetNamedTimeZoneNextTransition(timeZoneIdentifier: TimeZoneIdentifier, _epochNanoseconds: EpochNanoseconds): bigint | null {
+  Assert(timeZoneIdentifier === 'UTC');
+  return null;
+}
+
+// https://tc39.es/proposal-temporal/#sec-temporal-getnamedtimezoneprevioustransition
+export function GetNamedTimeZonePreviousTransition(timeZoneIdentifier: TimeZoneIdentifier, _epochNanoseconds: EpochNanoseconds): bigint | null {
+  Assert(timeZoneIdentifier === 'UTC');
+  return null;
+}
+
+// https://tc39.es/proposal-temporal/#sec-temporal-formatoffsettimezoneidentifier
+export function FormatOffsetTimeZoneIdentifier(offsetMinutes: Integer, style: 'separated' | 'unseparated' = 'separated'): TimeZoneIdentifier {
+  const sign = offsetMinutes >= 0 ? '+' : '-';
+  const absoluteMinutes = abs(offsetMinutes);
+  const hour = floorDiv(absoluteMinutes, 60n);
+  const minute = modulo(absoluteMinutes, 60n);
+  const timeString = FormatTimeString(hour, minute, 0n, 0n, TemporalUnit.Minute, style);
+  return sign + timeString as TimeZoneIdentifier;
+}
+
+// https://tc39.es/proposal-temporal/#sec-temporal-formatutcoffsetnanoseconds
+export function FormatUTCOffsetNanoseconds(offsetNanoseconds: Integer): string {
+  const sign = offsetNanoseconds >= 0 ? '+' : '-';
+  const absoluteNanoseconds = abs(offsetNanoseconds);
+  const hour = floorDiv(absoluteNanoseconds, BigInt(3600 * 1e9));
+  const minute = modulo(floorDiv(absoluteNanoseconds, BigInt(60 * 1e9)), 60n);
+  const second = modulo(floorDiv(absoluteNanoseconds, BigInt(1e9)), 60n);
+  const subSecondNanoseconds = modulo(absoluteNanoseconds, BigInt(1e9));
+  const precision: TemporalUnit.Minute | 'auto' = second === 0n && subSecondNanoseconds === 0n ? TemporalUnit.Minute : 'auto';
+  const timeString = FormatTimeString(hour, minute, second, subSecondNanoseconds, precision);
+  return sign + timeString;
+}
+
+// https://tc39.es/proposal-temporal/#sec-temporal-formatdatetimeutcoffsetrounded
+export function FormatDateTimeUTCOffsetRounded(offsetNanoseconds: Integer): string {
+  offsetNanoseconds = RoundNumberToIncrement(Decimal(offsetNanoseconds), BigInt(60 * 1e9), RoundingMode.HalfExpand);
+  const offsetMinutes = offsetNanoseconds / BigInt(60 * 1e9);
+  return FormatOffsetTimeZoneIdentifier(offsetMinutes);
+}
+
+// https://tc39.es/proposal-temporal/#sec-temporal-totemporaltimezoneidentifier
+export function ToTemporalTimeZoneIdentifier(temporalTimeZoneLike: Value | string): PlainCompletion<TimeZoneIdentifier> {
+  if (temporalTimeZoneLike instanceof ObjectValue && isTemporalZonedDateTimeObject(temporalTimeZoneLike)) {
+    return temporalTimeZoneLike.TimeZone;
+  }
+  if (!(temporalTimeZoneLike instanceof JSStringValue) && typeof temporalTimeZoneLike !== 'string') {
+    return Throw.TypeError('$1 is not a string', temporalTimeZoneLike);
+  }
+  const temporalTimeZoneLikeString = temporalTimeZoneLike instanceof JSStringValue ? temporalTimeZoneLike.stringValue() : temporalTimeZoneLike;
+  const parseResult = Q(ParseTemporalTimeZoneString(temporalTimeZoneLikeString));
+  const offsetMinutes = parseResult.OffsetMinutes;
+  if (offsetMinutes !== undefined) {
+    return FormatOffsetTimeZoneIdentifier(offsetMinutes);
+  }
+  const name = parseResult.Name;
+  const timeZoneIdentifierRecord = GetAvailableNamedTimeZoneIdentifier(name! as TimeZoneIdentifier);
+  if (timeZoneIdentifierRecord === undefined) {
+    return Throw.RangeError('Invalid time zone identifier: $1', temporalTimeZoneLikeString);
+  }
+  return timeZoneIdentifierRecord.Identifier;
+}
+
+// https://tc39.es/proposal-temporal/#sec-temporal-getoffsetnanosecondsfor
+export function GetOffsetNanosecondsFor(timeZone: TimeZoneIdentifier, epochNs: EpochNanoseconds): Integer {
+  const parseResult = X(ParseTimeZoneIdentifier(timeZone));
+  if (parseResult.OffsetMinutes !== undefined) {
+    return parseResult.OffsetMinutes * (60n * BigInt(1e9));
+  }
+  return GetNamedTimeZoneOffsetNanoseconds(parseResult.Name!, epochNs);
+}
+
+// https://tc39.es/proposal-temporal/#sec-temporal-getisodatetimefor
+export function GetISODateTimeFor(timeZone: TimeZoneIdentifier, epochNs: EpochNanoseconds): ISODateTimeRecord {
+  Assert(IsValidEpochNanoseconds(epochNs));
+  const offsetNanoseconds = GetOffsetNanosecondsFor(timeZone, epochNs);
+  const remainderNs = modulo(epochNs, BigInt(1e6));
+  const epochMilliseconds = (epochNs - remainderNs) / BigInt(1e6);
+  const year = EpochTimeToEpochYear(epochMilliseconds);
+  const month = EpochTimeToMonthInYear(epochMilliseconds) + 1n;
+  const day = EpochTimeToDate(epochMilliseconds);
+  const hour = HourFromTime(Number(epochMilliseconds));
+  const minute = MinFromTime(Number(epochMilliseconds));
+  const second = SecFromTime(Number(epochMilliseconds));
+  const millisecond = MillisecFromTime(Number(epochMilliseconds));
+  const microsecond = floorDiv(remainderNs, 1000n);
+  Assert(microsecond < 1000);
+  const nanosecond = modulo(remainderNs, 1000n);
+  return BalanceISODateTime(year, month, day, BigInt(hour), BigInt(minute), BigInt(second), BigInt(millisecond), microsecond, nanosecond + offsetNanoseconds);
+}
+
+// https://tc39.es/proposal-temporal/#sec-temporal-getepochnanosecondsfor
+export function GetEpochNanosecondsFor(
+  timeZone: TimeZoneIdentifier,
+  isoDateTime: ISODateTimeRecord,
+  disambiguation: 'compatible' | 'earlier' | 'later' | 'reject',
+): PlainCompletion<EpochNanoseconds> {
+  const possibleEpochNs = Q(GetPossibleEpochNanoseconds(timeZone, isoDateTime));
+  return DisambiguatePossibleEpochNanoseconds(possibleEpochNs, timeZone, isoDateTime, disambiguation);
+}
+
+// https://tc39.es/proposal-temporal/#sec-temporal-disambiguatepossibleepochnanoseconds
+export function DisambiguatePossibleEpochNanoseconds(
+  possibleEpochNs: readonly EpochNanoseconds[],
+  timeZone: TimeZoneIdentifier,
+  isoDateTime: ISODateTimeRecord,
+  disambiguation: 'compatible' | 'earlier' | 'later' | 'reject',
+): PlainCompletion<EpochNanoseconds> {
+  let n = possibleEpochNs.length;
+  if (n === 1) {
+    return possibleEpochNs[0];
+  }
+  if (n !== 0) {
+    if (disambiguation === 'earlier' || disambiguation === 'compatible') {
+      return possibleEpochNs[0];
+    }
+    if (disambiguation === 'later') {
+      return possibleEpochNs[n - 1];
+    }
+    Assert(disambiguation === 'reject');
+    return Throw.RangeError('Multiple possible epoch nanoseconds');
+  }
+  Assert(n === 0);
+  if (disambiguation === 'reject') {
+    return Throw.RangeError('No possible epoch nanoseconds');
+  }
+
+  const _ns = GetUTCEpochNanoseconds(isoDateTime);
+  // 6. Let before be the latest possible ISO Date-Time Record for which CompareISODateTime(before, isoDateTime) = -1 and !GetPossibleEpochNanoseconds(timeZone, before) is not empty.
+  let before: ISODateTimeRecord;
+  {
+    const dayBeforeNs = _ns - NanosecondsPerDay;
+    Assert(IsValidEpochNanoseconds(dayBeforeNs));
+    before = GetISODateTimeFor(timeZone, dayBeforeNs);
+  }
+  Assert(CompareISODateTime(before, isoDateTime) === -1n && X(GetPossibleEpochNanoseconds(timeZone, before)).length > 0);
+
+  // 7. Let after be the earliest possible ISO Date-Time Record for which CompareISODateTime(after, isoDateTime) = 1 and !GetPossibleEpochNanoseconds(timeZone, after) is not empty.
+  let after: ISODateTimeRecord;
+  {
+    const dayAfterNs = _ns + NanosecondsPerDay;
+    Assert(IsValidEpochNanoseconds(dayAfterNs));
+    after = GetISODateTimeFor(timeZone, dayAfterNs);
+  }
+  Assert(CompareISODateTime(after, isoDateTime) === 1n && X(GetPossibleEpochNanoseconds(timeZone, after)).length > 0);
+
+  const beforePossible = X(GetPossibleEpochNanoseconds(timeZone, before));
+  Assert(beforePossible.length === 1);
+  const afterPossible = X(GetPossibleEpochNanoseconds(timeZone, after));
+  Assert(afterPossible.length === 1);
+  const offsetBefore = GetOffsetNanosecondsFor(timeZone, beforePossible[0]);
+  const offsetAfter = GetOffsetNanosecondsFor(timeZone, afterPossible[0]);
+  const nanoseconds = offsetAfter - offsetBefore;
+  Assert(abs(nanoseconds) <= NanosecondsPerDay);
+  if (disambiguation === 'earlier') {
+    const timeDuration = TimeDurationFromComponents(0n, 0n, 0n, 0n, 0n, -nanoseconds);
+    const earlierTime = AddTime(isoDateTime.Time, timeDuration);
+    const earlierDate = AddDaysToISODate(isoDateTime.ISODate, earlierTime.Days);
+    const earlierDateTime = CombineISODateAndTimeRecord(earlierDate, earlierTime);
+    possibleEpochNs = Q(GetPossibleEpochNanoseconds(timeZone, earlierDateTime));
+    Assert(possibleEpochNs.length > 0);
+    return possibleEpochNs[0];
+  }
+  Assert(disambiguation === 'compatible' || disambiguation === 'later');
+  const timeDuration = TimeDurationFromComponents(0n, 0n, 0n, 0n, 0n, nanoseconds);
+  const laterTime = AddTime(isoDateTime.Time, timeDuration);
+  const laterDate = AddDaysToISODate(isoDateTime.ISODate, laterTime.Days);
+  const laterDateTime = CombineISODateAndTimeRecord(laterDate, laterTime);
+  possibleEpochNs = Q(GetPossibleEpochNanoseconds(timeZone, laterDateTime));
+  n = possibleEpochNs.length;
+  Assert(n > 0);
+  return possibleEpochNs[n - 1];
+}
+
+// https://tc39.es/proposal-temporal/#sec-temporal-getpossibleepochnanoseconds
+export function GetPossibleEpochNanoseconds(
+  timeZone: TimeZoneIdentifier,
+  isoDateTime: ISODateTimeRecord,
+): PlainCompletion<EpochNanoseconds[]> {
+  const parseResult = X(ParseTimeZoneIdentifier(timeZone));
+  let possibleEpochNanoseconds: EpochNanoseconds[];
+  if (parseResult.OffsetMinutes !== undefined) {
+    const balanced = BalanceISODateTime(
+      isoDateTime.ISODate.Year,
+      isoDateTime.ISODate.Month,
+      isoDateTime.ISODate.Day,
+      isoDateTime.Time.Hour,
+      isoDateTime.Time.Minute - parseResult.OffsetMinutes,
+      isoDateTime.Time.Second,
+      isoDateTime.Time.Millisecond,
+      isoDateTime.Time.Microsecond,
+      isoDateTime.Time.Nanosecond,
+    );
+    Q(CheckISODaysRange(balanced.ISODate));
+    const epochNanoseconds = GetUTCEpochNanoseconds(balanced);
+    possibleEpochNanoseconds = [epochNanoseconds];
+  } else {
+    possibleEpochNanoseconds = GetNamedTimeZoneEpochNanoseconds(parseResult.Name! as TimeZoneIdentifier, isoDateTime);
+  }
+  for (const epochNanoseconds of possibleEpochNanoseconds) {
+    if (!IsValidEpochNanoseconds(epochNanoseconds)) {
+      return Throw.RangeError('$1 is not a valid epoch nanoseconds', epochNanoseconds);
+    }
+  }
+  return possibleEpochNanoseconds;
+}
+
+/** https://tc39.es/proposal-temporal/#sec-temporal-getstartofday */
+export function GetStartOfDay(
+  timeZone: TimeZoneIdentifier,
+  isoDate: ISODateRecord,
+): PlainCompletion<EpochNanoseconds> {
+  const isoDateTime = CombineISODateAndTimeRecord(isoDate, MidnightTimeRecord());
+  const possibleEpochNs = Q(GetPossibleEpochNanoseconds(timeZone, isoDateTime));
+  if (possibleEpochNs.length) {
+    return possibleEpochNs[0];
+  }
+  Assert(!IsOffsetTimeZoneIdentifier(timeZone));
+
+  // Code below only reachable with named timezone
+  // 5. Let possibleEpochNsAfter be GetNamedTimeZoneEpochNanoseconds(timeZone, isoDateTimeAfter), where isoDateTimeAfter is the ISO Date-Time Record for which DifferenceISODateTime(isoDateTime, isoDateTimeAfter, "iso8601", hour).[[Time]] is the smallest possible value > 0 for which possibleEpochNsAfter is not empty (i.e., isoDateTimeAfter represents the first local time after the transition).
+  // 6. Assert: The number of elements in possibleEpochNsAfter = 1.
+  // 7. Return the sole element of possibleEpochNsAfter.
+  const dayBefore = GetUTCEpochNanoseconds(isoDateTime) - NanosecondsPerDay;
+  Assert(IsValidEpochNanoseconds(dayBefore));
+  return GetNamedTimeZoneNextTransition(timeZone, dayBefore) ?? 0n;
+}
+
+// https://tc39.es/proposal-temporal/#sec-temporal-timezoneequals
+export function TimeZoneEquals(one: TimeZoneIdentifier, two: TimeZoneIdentifier): boolean {
+  if (one === two) {
+    return true;
+  }
+  if (!IsOffsetTimeZoneIdentifier(one) && !IsOffsetTimeZoneIdentifier(two)) {
+    const recordOne = GetAvailableNamedTimeZoneIdentifier(one);
+    const recordTwo = GetAvailableNamedTimeZoneIdentifier(two);
+    Assert(recordOne !== undefined);
+    Assert(recordTwo !== undefined);
+    if (recordOne.PrimaryIdentifier === recordTwo.PrimaryIdentifier) {
+      return true;
+    }
+  }
+  // 3. Assert: If one and two are both offset time zone identifiers, they do not represent the same number of offset minutes.
+  if (IsOffsetTimeZoneIdentifier(one) && IsOffsetTimeZoneIdentifier(two)) {
+    const oneOffsetMinutes = X(ParseTimeZoneIdentifier(one)).OffsetMinutes;
+    const twoOffsetMinutes = X(ParseTimeZoneIdentifier(two)).OffsetMinutes;
+    Assert(oneOffsetMinutes !== twoOffsetMinutes);
+  }
+  return false;
+}

package/src/abstract-ops/temporal/zoned-datetime.mts

@@ -0,0 +1,373 @@
+import type { TemporalDurationObject } from '../../intrinsics/Temporal/Duration.mts';
+import type { ISODateRecord } from '../../intrinsics/Temporal/PlainDate.mts';
+import { type TemporalZonedDateTimeObject, isTemporalZonedDateTimeObject } from '../../intrinsics/Temporal/ZonedDateTime.mts';
+import { ParseISODateTime, ParseDateTimeUTCOffset, DateParser } from '../../parser/TemporalParser.mts';
+import { Decimal } from '../../host-defined/decimal.mts';
+import {
+  type TimeZoneIdentifier, GetUTCEpochNanoseconds, RoundingMode,
+} from './addition.mts';
+import {
+  type PlainCompletion, Assert, Q, GetStartOfDay, GetEpochNanosecondsFor, CheckISODaysRange, IsValidEpochNanoseconds, Throw, GetPossibleEpochNanoseconds, RoundNumberToIncrement, DisambiguatePossibleEpochNanoseconds, Value, type ValueEvaluator, type CalendarType, ObjectValue, GetTemporalDisambiguationOption, GetTemporalOffsetOption, GetTemporalOverflowOption, X, GetTemporalCalendarIdentifierWithISODefault, PrepareCalendarFields, JSStringValue, ToTemporalTimeZoneIdentifier, CanonicalizeCalendar, CreateISODateRecord, type FunctionObject, surroundingAgent, OrdinaryCreateFromConstructor, type Mutable, RoundEpochNanoseconds, TemporalUnit, GetOffsetNanosecondsFor, GetISODateTimeFor, FormatDateTimeUTCOffsetRounded, FormatCalendarAnnotation, type InternalDurationRecord, DateDurationSign, AddEpochNanoseconds, CalendarDateAdd, CombineDateAndTimeDuration, ZeroDateDuration, CompareISODate, TimeDurationFromEpochNanosecondsDifference, TimeDurationSign, AddDaysToISODate, LargerOfTwoTemporalUnits, CalendarDateUntil, type DateUnit, isTimeUnit, DifferenceEpochNanoseconds, type TimeUnit, RoundRelativeDuration, TotalTimeDuration, TotalRelativeDuration, CalendarEquals, GetDifferenceSettings, TemporalDurationFromInternal, CreateNegatedTemporalDuration, TimeZoneEquals, CreateTemporalDuration, ToTemporalDuration, ToInternalDurationRecord,
+  BalanceISODateTime,
+  CombineISODateAndTimeRecord,
+  DifferenceTime,
+  InterpretTemporalDateTimeFields,
+  FormatISODateTime,
+  ISODateTimeWithinLimits,
+  type TimeRecord,
+  type Integer,
+  type EpochNanoseconds,
+  type MathematicalValue,
+  GetOptionsObject,
+} from '#self';
+
+export type ISODateTimeOffsetBehaviour = 'option' | 'exact' | 'wall';
+export type ISODateTimeMatchBehaviour = 'match-exactly' | 'match-minutes';
+
+/** https://tc39.es/proposal-temporal/#sec-temporal-interpretisodatetimeoffset */
+export function InterpretISODateTimeOffset(
+  isoDate: ISODateRecord,
+  time: TimeRecord | 'start-of-day',
+  offsetBehaviour: ISODateTimeOffsetBehaviour,
+  offsetNanoseconds: Integer,
+  timeZone: TimeZoneIdentifier,
+  disambiguation: 'earlier' | 'later' | 'compatible' | 'reject',
+  offsetOption: 'ignore' | 'use' | 'prefer' | 'reject',
+  matchBehaviour: ISODateTimeMatchBehaviour,
+): PlainCompletion<EpochNanoseconds> {
+  if (time === 'start-of-day') {
+    Assert(offsetBehaviour === 'wall');
+    Assert(offsetNanoseconds === 0n);
+    return Q(GetStartOfDay(timeZone, isoDate));
+  }
+  const isoDateTime = CombineISODateAndTimeRecord(isoDate, time);
+  if (offsetBehaviour === 'wall' || (offsetBehaviour === 'option' && offsetOption === 'ignore')) {
+    return Q(GetEpochNanosecondsFor(timeZone, isoDateTime, disambiguation));
+  }
+  if (offsetBehaviour === 'exact' || (offsetBehaviour === 'option' && offsetOption === 'use')) {
+    const balanced = BalanceISODateTime(isoDate.Year, isoDate.Month, isoDate.Day, time.Hour, time.Minute, time.Second, time.Millisecond, time.Microsecond, time.Nanosecond - offsetNanoseconds);
+    Q(CheckISODaysRange(balanced.ISODate));
+    const epochNanoseconds = GetUTCEpochNanoseconds(balanced);
+    if (!IsValidEpochNanoseconds(epochNanoseconds)) {
+      return Throw.RangeError('Invalid date');
+    }
+    return epochNanoseconds;
+  }
+  Assert(offsetBehaviour === 'option');
+  Assert(offsetOption === 'prefer' || offsetOption === 'reject');
+  Q(CheckISODaysRange(isoDate));
+  const utcEpochNanoseconds = GetUTCEpochNanoseconds(isoDateTime);
+  const possibleEpochNs = Q(GetPossibleEpochNanoseconds(timeZone, isoDateTime));
+  for (const candidate of possibleEpochNs) {
+    const candidateOffset = utcEpochNanoseconds - candidate;
+    if (candidateOffset === offsetNanoseconds) {
+      return candidate;
+    }
+    if (matchBehaviour === 'match-minutes') {
+      const roundedCandidateNanoseconds = RoundNumberToIncrement(Decimal(candidateOffset), BigInt(60 * 1e9), RoundingMode.HalfExpand);
+      if (roundedCandidateNanoseconds === offsetNanoseconds) {
+        return candidate;
+      }
+    }
+  }
+  if (offsetOption === 'reject') {
+    return Throw.RangeError('No matching offset found for the given date and time');
+  }
+  return Q(DisambiguatePossibleEpochNanoseconds(possibleEpochNs, timeZone, isoDateTime, disambiguation));
+}
+
+/** https://tc39.es/proposal-temporal/#sec-temporal-totemporalzoneddatetime */
+export function* ToTemporalZonedDateTime(
+  item: Value,
+  options: Value = Value.undefined,
+): ValueEvaluator<TemporalZonedDateTimeObject> {
+  let hasUTCDesignator = false;
+  let matchBehaviour: ISODateTimeMatchBehaviour = 'match-exactly';
+  let calendar: CalendarType;
+  let isoDate: ISODateRecord;
+  let time: TimeRecord | 'start-of-day';
+  let timeZone: TimeZoneIdentifier;
+  let offsetString: string | undefined;
+  let disambiguation: 'earlier' | 'later' | 'compatible' | 'reject';
+  let offsetOption: 'ignore' | 'use' | 'prefer' | 'reject';
+  if (item instanceof ObjectValue) {
+    if (isTemporalZonedDateTimeObject(item)) {
+      const resolvedOptions = Q(GetOptionsObject(options));
+      Q(yield* GetTemporalDisambiguationOption(resolvedOptions));
+      Q(yield* GetTemporalOffsetOption(resolvedOptions, 'reject'));
+      Q(yield* GetTemporalOverflowOption(resolvedOptions));
+      return X(CreateTemporalZonedDateTime(item.EpochNanoseconds, item.TimeZone, item.Calendar));
+    }
+    calendar = Q(yield* GetTemporalCalendarIdentifierWithISODefault(item));
+    const fields = Q(yield* PrepareCalendarFields(calendar, item, ['year', 'month', 'month-code', 'day'], ['hour', 'minute', 'second', 'millisecond', 'microsecond', 'nanosecond', 'offset', 'time-zone'], ['time-zone']));
+    timeZone = fields.TimeZone! as TimeZoneIdentifier;
+    offsetString = fields.OffsetString;
+    const resolvedOptions = Q(GetOptionsObject(options));
+    disambiguation = Q(yield* GetTemporalDisambiguationOption(resolvedOptions));
+    offsetOption = Q(yield* GetTemporalOffsetOption(resolvedOptions, 'reject'));
+    const overflow = Q(yield* GetTemporalOverflowOption(resolvedOptions));
+    const result = Q(yield* InterpretTemporalDateTimeFields(calendar, fields, overflow));
+    isoDate = result.ISODate;
+    time = result.Time;
+  } else {
+    if (!(item instanceof JSStringValue)) {
+      return Throw.TypeError('$1 is not a string', item);
+    }
+    const result = Q(ParseISODateTime(item.stringValue(), ['TemporalDateTimeString[+Zoned]']));
+    const annotation = result.TimeZone.TimeZoneAnnotation;
+    Assert(annotation !== undefined);
+    timeZone = Q(ToTemporalTimeZoneIdentifier(annotation));
+    offsetString = result.TimeZone.OffsetString;
+    if (result.TimeZone.Z) {
+      hasUTCDesignator = true;
+    }
+    calendar = result.Calendar as CalendarType ?? 'iso8601';
+    calendar = Q(CanonicalizeCalendar(calendar));
+    matchBehaviour = 'match-minutes';
+    if (offsetString) {
+      const offsetParseResult = DateParser.parse(offsetString, (parser) => parser.with({ SubMinutePrecision: true }, () => parser.parseUTCOffset()));
+      Assert(offsetParseResult && !Array.isArray(offsetParseResult));
+      // If offsetParseResult contains more than one MinuteSecond Parse Node, set matchBehaviour to match-exactly.
+      if (offsetParseResult.Minute !== undefined && offsetParseResult.Second !== undefined) {
+        matchBehaviour = 'match-exactly';
+      }
+    }
+    const resolvedOptions = Q(GetOptionsObject(options));
+    disambiguation = Q(yield* GetTemporalDisambiguationOption(resolvedOptions));
+    offsetOption = Q(yield* GetTemporalOffsetOption(resolvedOptions, 'reject'));
+    Q(yield* GetTemporalOverflowOption(resolvedOptions));
+    isoDate = CreateISODateRecord(result.Year!, result.Month, result.Day);
+    time = result.Time;
+  }
+  let offsetBehaviour: ISODateTimeOffsetBehaviour;
+  if (hasUTCDesignator) {
+    offsetBehaviour = 'exact';
+  } else if (offsetString === undefined) {
+    offsetBehaviour = 'wall';
+  } else {
+    offsetBehaviour = 'option';
+  }
+  let offsetNanoseconds = 0n;
+  if (offsetBehaviour === 'option') {
+    offsetNanoseconds = X(ParseDateTimeUTCOffset(offsetString!));
+  }
+  const epochNanoseconds = Q(InterpretISODateTimeOffset(isoDate, time, offsetBehaviour, offsetNanoseconds, timeZone, disambiguation, offsetOption, matchBehaviour));
+  return X(CreateTemporalZonedDateTime(epochNanoseconds, timeZone, calendar));
+}
+
+/** https://tc39.es/proposal-temporal/#sec-temporal-createtemporalzoneddatetime */
+export function* CreateTemporalZonedDateTime(
+  epochNanoseconds: EpochNanoseconds,
+  timeZone: TimeZoneIdentifier,
+  calendar: CalendarType,
+  newTarget?: FunctionObject,
+): ValueEvaluator<TemporalZonedDateTimeObject> {
+  Assert(IsValidEpochNanoseconds(epochNanoseconds));
+  if (newTarget === undefined) {
+    newTarget = surroundingAgent.intrinsic('%Temporal.ZonedDateTime%');
+  }
+  const object = Q(yield* OrdinaryCreateFromConstructor(newTarget, '%Temporal.ZonedDateTime.prototype%', [
+    'InitializedTemporalZonedDateTime',
+    'EpochNanoseconds',
+    'TimeZone',
+    'Calendar',
+  ])) as Mutable<TemporalZonedDateTimeObject>;
+  object.EpochNanoseconds = epochNanoseconds;
+  object.TimeZone = timeZone;
+  object.Calendar = calendar;
+  return object;
+}
+
+/** https://tc39.es/proposal-temporal/#sec-temporal-temporalzoneddatetimetostring */
+export function TemporalZonedDateTimeToString(
+  zonedDateTime: TemporalZonedDateTimeObject,
+  precision: Integer | TemporalUnit.Minute | 'auto',
+  showCalendar: 'auto' | 'always' | 'never' | 'critical',
+  showTimeZone: 'auto' | 'never' | 'critical',
+  showOffset: 'auto' | 'never',
+  increment: Integer = 1n,
+  unit: TemporalUnit.Minute | TemporalUnit.Second | TemporalUnit.Millisecond | TemporalUnit.Microsecond | TemporalUnit.Nanosecond = TemporalUnit.Nanosecond,
+  roundingMode = RoundingMode.Trunc,
+): string {
+  let epochNs = zonedDateTime.EpochNanoseconds;
+  epochNs = RoundEpochNanoseconds(epochNs, increment, unit, roundingMode);
+  const timeZone = zonedDateTime.TimeZone;
+  const offsetNanoseconds = GetOffsetNanosecondsFor(timeZone, epochNs);
+  const isoDateTime = GetISODateTimeFor(timeZone, epochNs);
+  const dateTimeString = FormatISODateTime(isoDateTime, 'iso8601', precision, 'never');
+  const offsetString = showOffset === 'never' ? '' : FormatDateTimeUTCOffsetRounded(offsetNanoseconds);
+  let timeZoneString;
+  if (showTimeZone === 'never') {
+    timeZoneString = '';
+  } else {
+    const flag = showTimeZone === 'critical' ? '!' : '';
+    timeZoneString = `[${flag}${timeZone}]`;
+  }
+  const calendarString = FormatCalendarAnnotation(zonedDateTime.Calendar, showCalendar);
+  return dateTimeString + offsetString + timeZoneString + calendarString;
+}
+
+/** https://tc39.es/proposal-temporal/#sec-temporal-addzoneddatetime */
+export function AddZonedDateTime(
+  epochNanoseconds: EpochNanoseconds,
+  timeZone: TimeZoneIdentifier,
+  calendar: CalendarType,
+  duration: InternalDurationRecord,
+  overflow: 'constrain' | 'reject',
+): PlainCompletion<EpochNanoseconds> {
+  if (DateDurationSign(duration.Date) === 0n) {
+    return AddEpochNanoseconds(epochNanoseconds, duration.Time);
+  }
+  const isoDateTime = GetISODateTimeFor(timeZone, epochNanoseconds);
+  const addedDate = Q(CalendarDateAdd(calendar, isoDateTime.ISODate, duration.Date, overflow));
+  const intermediateDateTime = CombineISODateAndTimeRecord(addedDate, isoDateTime.Time);
+  if (!ISODateTimeWithinLimits(intermediateDateTime)) {
+    return Throw.RangeError('Resulting date-time is out of range');
+  }
+  const intermediateNs = X(GetEpochNanosecondsFor(timeZone, intermediateDateTime, 'compatible'));
+  return AddEpochNanoseconds(intermediateNs, duration.Time);
+}
+
+/** https://tc39.es/proposal-temporal/#sec-temporal-differencezoneddatetime */
+export function DifferenceZonedDateTime(
+  ns1: EpochNanoseconds,
+  ns2: EpochNanoseconds,
+  timeZone: TimeZoneIdentifier,
+  calendar: CalendarType,
+  largestUnit: TemporalUnit,
+): PlainCompletion<InternalDurationRecord> {
+  if (ns1 === ns2) {
+    return CombineDateAndTimeDuration(ZeroDateDuration(), 0n);
+  }
+  const startDateTime = GetISODateTimeFor(timeZone, ns1);
+  const endDateTime = GetISODateTimeFor(timeZone, ns2);
+  if (CompareISODate(startDateTime.ISODate, endDateTime.ISODate) === 0n) {
+    const timeDuration = TimeDurationFromEpochNanosecondsDifference(ns2, ns1);
+    return CombineDateAndTimeDuration(ZeroDateDuration(), timeDuration);
+  }
+  const sign = ns2 - ns1 < 0n ? 1n : -1n;
+  const maxDayCorrection = sign === -1n ? 2n : 1n;
+  let dayCorrection = 0n;
+  let timeDuration = DifferenceTime(startDateTime.Time, endDateTime.Time);
+  if (TimeDurationSign(timeDuration) === sign) dayCorrection += 1n;
+  let success = false;
+  let intermediateDateTime;
+  while (dayCorrection <= maxDayCorrection && !success) {
+    const intermediateDate = AddDaysToISODate(endDateTime.ISODate, dayCorrection * sign);
+    intermediateDateTime = CombineISODateAndTimeRecord(intermediateDate, startDateTime.Time);
+    const intermediateNs = Q(GetEpochNanosecondsFor(timeZone, intermediateDateTime, 'compatible'));
+    timeDuration = TimeDurationFromEpochNanosecondsDifference(ns2, intermediateNs);
+    const timeSign = TimeDurationSign(timeDuration);
+    if (sign !== timeSign) {
+      success = true;
+    }
+    dayCorrection += 1n;
+  }
+  Assert(success);
+  const dateLargestUnit = LargerOfTwoTemporalUnits(largestUnit, TemporalUnit.Day);
+  const dateDifference = CalendarDateUntil(calendar, startDateTime.ISODate, intermediateDateTime!.ISODate, dateLargestUnit as DateUnit);
+  return CombineDateAndTimeDuration(dateDifference, timeDuration);
+}
+
+/** https://tc39.es/proposal-temporal/#sec-temporal-differencezoneddatetimewithrounding */
+export function DifferenceZonedDateTimeWithRounding(
+  ns1: EpochNanoseconds,
+  ns2: EpochNanoseconds,
+  timeZone: TimeZoneIdentifier,
+  calendar: CalendarType,
+  largestUnit: TemporalUnit,
+  roundingIncrement: Integer,
+  smallestUnit: TemporalUnit,
+  roundingMode: RoundingMode,
+): PlainCompletion<InternalDurationRecord> {
+  if (isTimeUnit(largestUnit)) {
+    return DifferenceEpochNanoseconds(ns1, ns2, roundingIncrement, smallestUnit as TimeUnit, roundingMode);
+  }
+  const difference = Q(DifferenceZonedDateTime(ns1, ns2, timeZone, calendar, largestUnit));
+  if (smallestUnit === TemporalUnit.Nanosecond && roundingIncrement === 1n) {
+    return difference;
+  }
+  const dateTime = GetISODateTimeFor(timeZone, ns1);
+  return RoundRelativeDuration(difference, ns1, ns2, dateTime, timeZone, calendar, largestUnit, roundingIncrement, smallestUnit, roundingMode);
+}
+
+/** https://tc39.es/proposal-temporal/#sec-temporal-differencezoneddatetimewithtotal */
+export function DifferenceZonedDateTimeWithTotal(
+  ns1: EpochNanoseconds,
+  ns2: EpochNanoseconds,
+  timeZone: TimeZoneIdentifier,
+  calendar: CalendarType,
+  unit: TemporalUnit,
+): PlainCompletion<MathematicalValue> {
+  if (isTimeUnit(unit)) {
+    const difference = TimeDurationFromEpochNanosecondsDifference(ns2, ns1);
+    return TotalTimeDuration(difference, unit as TimeUnit);
+  }
+  const difference = Q(DifferenceZonedDateTime(ns1, ns2, timeZone, calendar, unit));
+  const dateTime = GetISODateTimeFor(timeZone, ns1);
+  return TotalRelativeDuration(difference, ns1, ns2, dateTime, timeZone, calendar, unit);
+}
+
+/** https://tc39.es/proposal-temporal/#sec-temporal-differencetemporalzoneddatetime */
+export function* DifferenceTemporalZonedDateTime(
+  operation: 'until' | 'since',
+  zonedDateTime: TemporalZonedDateTimeObject,
+  _other: Value,
+  options: Value,
+): ValueEvaluator<TemporalDurationObject> {
+  const other = Q(yield* ToTemporalZonedDateTime(_other));
+  if (!CalendarEquals(zonedDateTime.Calendar, other.Calendar)) {
+    return Throw.RangeError('Calendars are not equal');
+  }
+  const resolvedOptions = Q(GetOptionsObject(options));
+  const settings = Q(yield* GetDifferenceSettings(operation, resolvedOptions, 'datetime', [], TemporalUnit.Nanosecond, TemporalUnit.Hour));
+  if (isTimeUnit(settings.LargestUnit)) {
+    const internalDuration = DifferenceEpochNanoseconds(zonedDateTime.EpochNanoseconds, other.EpochNanoseconds, settings.RoundingIncrement, settings.SmallestUnit as TimeUnit, settings.RoundingMode);
+    let result = X(TemporalDurationFromInternal(internalDuration, settings.LargestUnit));
+    if (operation === 'since') {
+      result = CreateNegatedTemporalDuration(result);
+    }
+    return result;
+  }
+  if (!TimeZoneEquals(zonedDateTime.TimeZone, other.TimeZone)) {
+    return Throw.RangeError('Time zones are not equal');
+  }
+  if (zonedDateTime.EpochNanoseconds === other.EpochNanoseconds) {
+    return X(CreateTemporalDuration(0n, 0n, 0n, 0n, 0n, 0n, 0n, 0n, 0n, 0n));
+  }
+  const internalDuration = Q(DifferenceZonedDateTimeWithRounding(
+    zonedDateTime.EpochNanoseconds,
+    other.EpochNanoseconds,
+    zonedDateTime.TimeZone,
+    zonedDateTime.Calendar,
+    settings.LargestUnit,
+    settings.RoundingIncrement,
+    settings.SmallestUnit,
+    settings.RoundingMode,
+  ));
+  let result = X(TemporalDurationFromInternal(internalDuration, TemporalUnit.Hour));
+  if (operation === 'since') {
+    result = CreateNegatedTemporalDuration(result);
+  }
+  return result;
+}
+
+/** https://tc39.es/proposal-temporal/#sec-temporal-adddurationtozoneddatetime */
+export function* AddDurationToZonedDateTime(
+  operation: 'add' | 'subtract',
+  zonedDateTime: TemporalZonedDateTimeObject,
+  temporalDurationLike: Value,
+  options: Value,
+): ValueEvaluator<TemporalZonedDateTimeObject> {
+  let duration = Q(yield* ToTemporalDuration(temporalDurationLike));
+  if (operation === 'subtract') {
+    duration = CreateNegatedTemporalDuration(duration);
+  }
+  const resolvedOptions = Q(GetOptionsObject(options));
+  const overflow = Q(yield* GetTemporalOverflowOption(resolvedOptions));
+  const calendar = zonedDateTime.Calendar;
+  const timeZone = zonedDateTime.TimeZone;
+  const internalDuration = ToInternalDurationRecord(duration);
+  const epochNanoseconds = Q(AddZonedDateTime(zonedDateTime.EpochNanoseconds, timeZone, calendar, internalDuration, overflow));
+  return X(CreateTemporalZonedDateTime(epochNanoseconds, timeZone, calendar));
+}