Skip to main content
Temporal.OffsetDisambiguationOptions.offset - Temporal - Web documentation
property Temporal.OffsetDisambiguationOptions.offset

Time zone definitions can change. If an application stores data about events in the future, then stored data about future events may become ambiguous, for example if a country permanently abolishes DST. The offset option controls this unusual case.

  • 'use' always uses the offset (if it's provided) to calculate the instant. This ensures that the result will match the instant that was originally stored, even if local clock time is different.
  • 'prefer' uses the offset if it's valid for the date/time in this time zone, but if it's not valid then the time zone will be used as a fallback to calculate the instant.
  • 'ignore' will disregard any provided offset. Instead, the time zone and date/time value are used to calculate the instant. This will keep local clock time unchanged but may result in a different real-world instant.
  • 'reject' acts like 'prefer', except it will throw a RangeError if the offset is not valid for the given time zone identifier and date/time value.

If the ISO string ends in 'Z' then this option is ignored because there is no possibility of ambiguity.

If a time zone offset is not present in the input, then this option is ignored because the time zone will always be used to calculate the offset.

If the offset is not used, and if the date/time and time zone don't uniquely identify a single instant, then the disambiguation option will be used to choose the correct instant. However, if the offset is used then the disambiguation option will be ignored.

Type

"use"
| "prefer"
| "ignore"
| "reject"