formatRfc3339
Signature
Section titled “Signature”formatRfc3339(value: string): stringFormat a zoned ISO 8601 datetime string as strict RFC 3339 — the ISO 8601 profile RFC 3339 §5.6 defines, permitting only an explicit numeric offset or Z, never a bracketed IANA zone name.
- Not a passthrough. GMT’s own zoned strings always carry a bracketed IANA zone annotation (e.g.
...+00:00[UTC]) that plainTemporal.ZonedDateTime.prototype.toString()reproduces by default — that annotation is not valid RFC 3339. This function’s only job is to strip it ({ timeZoneName: "never" }), which is exactly the detail a caller reaching for “give me RFC 3339” would otherwise miss. (This narrow gap is real; a parallelutc/unixwrapper was not added, becauseTemporal.Instant.prototype.toString()is already fully RFC 3339 compliant with no bracket to strip — that would be a pure passthrough.) - Sub-minute offsets are written in UTC.
time-numoffsetholds whole minutes, and RFC 3339 §4.2 says historical offsets that are not (“applications must convert them to a representable time zone”). A local mean time such as Africa/Monrovia’s −00:44:30 is therefore written as the same instant at+00:00.Zis not used: RFC 9557 §2.2 gives it the meaning “the offset to local time is unknown”, and here the offset is known, only not representable. - Returns
""for a year outsidedate-fullyear = 4DIGIT(0000–9999). - Fractional seconds are kept, with trailing zeros dropped.
- Compatibility: before 1.16.0 a sub-minute offset was rounded to the minute, naming a different instant, and years outside 0000–9999 were written in expanded form. For either string use
Temporal.ZonedDateTime#toString({ timeZoneName: "never" }).
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
value | string | zoned ISO 8601 datetime string (e.g. “2024-03-15T14:30:00-04:00[America/New_York]”) |
Returns
Section titled “Returns”RFC 3339 datetime string, or "" on invalid input or a year outside 0000–9999
Examples
Section titled “Examples”import { formatRfc3339 } from "@northguild/gmt/zoned/format";
formatRfc3339("2024-03-15T14:30:00-04:00[America/New_York]") // "2024-03-15T14:30:00-04:00"