Skip to content
@northguild/gmt

convertPlainDateTimeToZoned

Playground

call
result 

Signature

Section titled “Signature”
convertPlainDateTimeToZoned(value: string, timeZone: string, optionsArg?: { smallestUnit?: Temporal.ZonedDateTimeToStringOptions; disambiguation?: Disambiguation; offset?: Offset; }): string
import { convertPlainDateTimeToZoned } from "@northguild/gmt/zoned/convert";

Attach the specified timeZone to a plain datetime string and return a zoned ISO 8601 datetime string.

  • Combines plain datetime with timezone to create ZonedDateTime.
  • disambiguation controls DST gap/overlap resolution: “compatible” (default, matches Temporal’s default), “earlier”, “later”, or “reject” (throws, resulting in “”).
  • offset (“prefer” | “use” | “ignore” (default) | “reject”, per Temporal’s OffsetDisambiguationOptions) is accepted for API consistency with sibling zoned-construction functions (see startOfZoned, endOfZoned, etc.) but has no effect here: value is a plain datetime string with no UTC offset embedded, so there is never a stored offset for offset to prefer/use/ignore/reject against. disambiguation is the only option that affects this function’s output.
  • Returns “” for invalid input.

Parameters

Section titled “Parameters”
Parameter Type Description
value string plain datetime string (e.g. “2024-02-29T14:30:45”)
timeZone string IANA timeZone identifier

Options

Section titled “Options”

options

Option Type Default
smallestUnit? Temporal.ZonedDateTimeToStringOptions —
disambiguation? Disambiguation —
offset? Offset —

Returns

Section titled “Returns”

zoned ISO 8601 datetime string or “” when invalid

Section titled “Related types”

Examples

Section titled “Examples”
convertPlainDateTimeToZoned("2024-02-29T14:30:45", "America/New_York") // "2024-02-29T14:30:45.123-05:00[America/New_York]"
convertPlainDateTimeToZoned("invalid", "America/New_York") // ""
convertPlainDateTimeToZoned("2024-03-10T02:30:00", "America/New_York", { disambiguation: "earlier" }) // "2024-03-10T01:30:00.000-05:00[America/New_York]" (spring-forward gap)
convertPlainDateTimeToZoned("2024-11-03T01:30:00", "America/New_York", { disambiguation: "later" }) // "2024-11-03T01:30:00.000-05:00[America/New_York]" (fall-back overlap)
convertPlainDateTimeToZoned("2024-03-10T02:30:00", "America/New_York", { disambiguation: "reject" }) // ""

Source

Section titled “Source”

zoned/convert/convertPlainDateTimeToZoned.ts