Skip to content
@northguild/gmt

fromOffsetInstant

Signature

Section titled “Signature”
fromOffsetInstant(value: OffsetInstant): string

Render an instant-plus-offset pair back to the local time it describes.

  • The inverse of toOffsetInstant: toOffsetInstant(fromOffsetInstant(pair)) returns pair, for zones with and without DST.
  • Without timeZone, returns <date>T<time>±HH:MM — the wall clock the event carried and the offset it carried it in, which is all an offset-only pair knows.
  • With timeZone, returns the bracketed zoned string <date>T<time>±HH:MM[Zone], so the zone survives the round trip instead of being silently dropped.
  • A timeZone whose offset at instant is not offset returns "". The pair is stating two things that cannot both be true, and the whole point of carrying both fields is that a contradiction between them is visible.
  • timeZone accepts every identifier Temporal does, as toOffsetInstant’s bracket does — including the single-component IANA names (EST5EDT, Zulu). A timeZone that is really an offset ("-04:00", or the "-0400"/"+05" spellings Temporal canonicalises to one) returns "": it names no place, and no pair toOffsetInstant produces carries one.
  • offset is canonicalised, so "+05:45:00" renders as +05:45 and "-00:00" as +00:00. Z is not an accepted offset — for an event that happened at UTC the pair’s offset is +00:00. RFC 9557 §2.2 gives Z and -00:00 a different meaning from +00:00 (“UTC known, local offset unknown”); a pair cannot carry that, so all three render as +00:00.
  • With a timeZone, a sub-minute offset is written rounded to the minute, because RFC 9557 has no field for the seconds — Africa/Monrovia’s -00:44:30 renders as -00:45. The bracketed zone is what resolves it, so the instant stays exact and the round trip returns -00:44:30. Two exceptions, both Temporal’s own: a wall time repeated inside a sub-minute offset change reads back as its first pass (see isValidInstant), and a string whose local date is −271821-04-19 is refused by toOffsetInstant. Without a timeZone there is no zone to resolve against, so the full ±HH:MM:SS is written instead; that is ISO 8601, not RFC 9557.
  • Returns "" on invalid input.
  • A timeZone that is an offset with seconds (-00:44:30) returns "", as any offset there does. A written zone cannot carry seconds (RFC 9557 §4.1), so the result could not name it. Pass the IANA name as timeZone, or leave timeZone out for the local time with its full offset and no bracket.

Parameters

Section titled “Parameters”
ParameterTypeDescription
valueOffsetInstant{ instant, offset, timeZone? } pair, as produced by toOffsetInstant

Returns

Section titled “Returns”

local ISO 8601 string carrying the pair’s own offset, or "" on invalid input

Section titled “Related types”

Examples

Section titled “Examples”
import { fromOffsetInstant } from "@northguild/gmt/instant/convert";


fromOffsetInstant({ instant: "2024-07-15T16:00:00Z", offset: "-04:00" }) // "2024-07-15T12:00:00-04:00"
output 

Source

Section titled “Source”

instant/convert/fromOffsetInstant.ts