getTimeZoneOffset

Signature

getTimeZoneOffset(timeZone: string, instant: string): string

Return a time zone’s UTC offset at a given instant.

• Unlike getZonedOffset, this doesn’t need an existing zoned value in hand — pass any timeZone identifier and an instant to look up, which is why (like getDstTransitions) it lives in get/ despite taking two arguments: neither is a date value being described, both are coordinates for a zone-level lookup.
• Returns "" for an invalid timeZone or instant, including a leap second in any spelling (23:59:60, t/space separator, basic 235960), which Temporal would read as :59. Compatibility: to look up the offset at the clamped :59 instant as earlier releases did, pass that instant ("2016-12-31T23:59:59Z"), or call Temporal.Instant.from(instant).toZonedDateTimeISO(timeZone).offset directly.
• The instant is ISO 8601 extended format before any annotation (<date>T<time>, then Z or ±HH:MM[:SS[.fraction]]): basic format, a t or space separator, a lower-case z and an hour-only offset return "".
• Only the instant is read from instant, as isValidInstant describes it: a bracketed zone in it is not validated, and an offset written to the minute that is that zone’s sub-minute offset rounded (-00:45[Africa/Monrovia], for −00:44:30) names the instant the zone gives.
• The result is ±HH:MM, or ±HH:MM:SS where the zone was not on a whole minute (Africa/Monrovia stood at -00:44:30 until 1972). It goes straight into the time zone position of any function whose result has no zone in it, and of this one: a UTC offset is its own answer at every instant, written without seconds when they are zero.

Parameters

Parameter	Type	Description
timeZone	string	IANA name or UTC offset: a time zone identifier (+05:30, +0530, -08) or a stored offset (±HH:MM[:SS], what getTimeZoneOffset returns)
instant	string	ISO 8601 instant string (e.g. “2024-07-15T12:00:00Z”)

Returns

offset string (e.g. “-04:00”), or "" on invalid input

Examples

import { getTimeZoneOffset } from "@northguild/gmt/zoned/get";

getTimeZoneOffset("America/New_York", "2024-07-15T12:00:00Z") // "-04:00"

instant

output

 

Source

zoned/get/getTimeZoneOffset.ts