Temporal.ZonedDateTime

type ZonedDateTimeFromOptions = { disambiguation :: Disambiguation, offset :: OffsetDisambiguation, overflow :: Overflow }

Options controlling how ambiguous inputs are resolved during construction.

• disambiguation: how to handle wall-clock times that don't exist (spring forward) or are ambiguous (fall back)
• offset: how to handle conflicts between an explicit UTC offset and the IANA timezone rules
• overflow: how to handle out-of-range field values

defaultZonedDateTimeFromOptions :: ZonedDateTimeFromOptions

fromEpochNanoseconds :: BigInt -> String -> Maybe ZonedDateTime

Construct from nanoseconds since the Unix epoch and an IANA time zone name. Returns Nothing for invalid time zones or out-of-range epoch values.

fromString :: String -> Maybe ZonedDateTime

Parse a string with timezone annotation (e.g. "2024-03-15T10:30:00+00:00[UTC]"). Returns Nothing for invalid strings.

The UTC offset in the string is validated against the timezone rules. If the offset is inconsistent with the IANA timezone at that instant (e.g. due to changed DST rules), parsing fails. Use fromStringWith with offset: Ignore to handle strings where timezone rules may have changed.

fromStringWith :: ZonedDateTimeFromOptions -> String -> Maybe ZonedDateTime

Parse with explicit disambiguation options. See ZonedDateTimeFromOptions.

getYear :: ZonedDateTime -> Int

Calendar year.

getMonth :: ZonedDateTime -> Int

Month of the year (1–12).

getDay :: ZonedDateTime -> Int

Day of the month (1–31).

getHour :: ZonedDateTime -> Int

Hour of the day (0–23).

getMinute :: ZonedDateTime -> Int

Minute of the hour (0–59).

getSecond :: ZonedDateTime -> Int

Second of the minute (0–59).

getMillisecond :: ZonedDateTime -> Int

Millisecond (0–999).

getMicrosecond :: ZonedDateTime -> Int

Microsecond (0–999).

getNanosecond :: ZonedDateTime -> Int

Nanosecond (0–999).

getDayOfWeek :: ZonedDateTime -> Int

Day of the week (1 = Monday, 7 = Sunday), per ISO 8601.

getDayOfYear :: ZonedDateTime -> Int

Day of the year (1–366).

getWeekOfYear :: ZonedDateTime -> Int

ISO 8601 week number (1–53).

getYearOfWeek :: ZonedDateTime -> Int

The year that corresponds to getWeekOfYear.

getDaysInMonth :: ZonedDateTime -> Int

Number of days in this month (28–31).

getDaysInWeek :: ZonedDateTime -> Int

Always 7.

getDaysInYear :: ZonedDateTime -> Int

Number of days in this year (365 or 366).

getMonthsInYear :: ZonedDateTime -> Int

Always 12 for the ISO calendar.

getInLeapYear :: ZonedDateTime -> Boolean

Whether this year is a leap year.

getTimeZoneId :: ZonedDateTime -> String

The IANA time zone identifier (e.g. "America/New_York", "UTC").

getOffset :: ZonedDateTime -> String

The UTC offset as a string (e.g. "+00:00", "-05:00").

getOffsetNanoseconds :: ZonedDateTime -> Int

The UTC offset in nanoseconds.

getEpochMilliseconds :: ZonedDateTime -> Number

Milliseconds since the Unix epoch. May lose sub-millisecond precision.

getEpochNanoseconds :: ZonedDateTime -> BigInt

Nanoseconds since the Unix epoch (full precision).

getHoursInDay :: ZonedDateTime -> Number

The number of real-world hours in this calendar day, accounting for DST. Usually 24, but can be 23 or 25 during DST transitions.

with :: ZonedDateTimeFromOptions -> ZonedDateTimeWithFields -> ZonedDateTime -> Maybe ZonedDateTime

Create a modified copy with the given fields and disambiguation options. Returns Nothing if the result would be invalid.

withPlainTime :: PlainTime -> ZonedDateTime -> ZonedDateTime

Replace the time component, keeping date and timezone.

withTimeZone :: String -> ZonedDateTime -> ZonedDateTime

Change the time zone, preserving the exact instant. The wall-clock time will change to reflect the new timezone.

add :: Duration -> ZonedDateTime -> Maybe ZonedDateTime

Add a duration. Date components are added as calendar arithmetic (wall-clock time preserved), then time components as real elapsed time. Returns Nothing on overflow.

subtract :: Duration -> ZonedDateTime -> Maybe ZonedDateTime

Subtract a duration. Same semantics as add.

type ZonedDateTimeDiffOptions = { largestUnit :: DateTimeUnit, roundingIncrement :: Int, roundingMode :: RoundingMode, smallestUnit :: DateTimeUnit }

Options for since and until. Default: largest unit is Years, smallest unit is Nanoseconds.

defaultZonedDateTimeDiffOptions :: ZonedDateTimeDiffOptions

since :: ZonedDateTimeDiffOptions -> ZonedDateTime -> ZonedDateTime -> Duration

since opts a b returns the duration from b to a (i.e., a.since(b) in JS). The result is positive when a is after b.

until :: ZonedDateTimeDiffOptions -> ZonedDateTime -> ZonedDateTime -> Duration

until opts a b returns the duration from a to b (i.e., a.until(b) in JS). The result is positive when b is after a.

since' :: ZonedDateTime -> ZonedDateTime -> Duration

since' a b — duration from b to a with default options.

until' :: ZonedDateTime -> ZonedDateTime -> Duration

until' a b — duration from a to b with default options.

type ZonedDateTimeRoundOptions = { roundingIncrement :: Int, roundingMode :: RoundingMode, smallestUnit :: DateTimeUnit }

Options for round.

defaultZonedDateTimeRoundOptions :: ZonedDateTimeRoundOptions

round :: ZonedDateTimeRoundOptions -> ZonedDateTime -> ZonedDateTime

Round the date-time to the given precision.

startOfDay :: ZonedDateTime -> ZonedDateTime

The first instant of the calendar day in this time zone. Usually midnight, but may be a later time in zones where DST transitions occur at midnight.

getTimeZoneTransition :: TransitionDirection -> ZonedDateTime -> Maybe Instant

Find the next or previous UTC offset transition (DST change) from this instant. Returns Nothing if there is no transition in the given direction (e.g. for fixed-offset zones like UTC).

toInstant :: ZonedDateTime -> Instant

Extract the exact instant, discarding timezone information.

toPlainDateTime :: ZonedDateTime -> PlainDateTime

Extract the wall-clock date and time, discarding timezone information.

toPlainDate :: ZonedDateTime -> PlainDate

Extract the date component.

toPlainTime :: ZonedDateTime -> PlainTime

Extract the time component.

toPlainYearMonth :: ZonedDateTime -> PlainYearMonth

Extract the year and month.

toPlainMonthDay :: ZonedDateTime -> PlainMonthDay

Extract the month and day.

toString :: ZonedDateTime -> String

Serialize to an ISO 8601 string with offset and timezone annotation (e.g. "2024-03-15T10:30:00-04:00[America/New_York]").

data ZonedDateTime

A date and time in a specific time zone, with full awareness of UTC offset and DST transitions (e.g. 2024-03-15T10:30:00-04:00[America/New_York]).

This is the richest Temporal type. Use it for scheduling future events where wall-clock time should be preserved even if DST rules change. For past events or timestamps, Instant is usually sufficient.

Instances

• Eq ZonedDateTime
• Ord ZonedDateTime
• Show ZonedDateTime

data PlainYearMonth

A year and month without a day component (e.g. 2024-03).

Useful for representing months in a calendar UI or credit card expiry dates.

Instances

• Eq PlainYearMonth
• Ord PlainYearMonth
• Show PlainYearMonth

data PlainTime

A wall-clock time without a date or time zone (e.g. 10:30:00). Range: 00:00:00.000000000 to 23:59:59.999999999.

Arithmetic wraps at midnight with no overflow indication.

Instances

• Eq PlainTime
• Ord PlainTime
• Show PlainTime
• Bounded PlainTime

data PlainMonthDay

A month and day without a year component (e.g. 12-25).

Useful for recurring annual dates like birthdays or holidays.

Instances

• Eq PlainMonthDay
• Show PlainMonthDay

data PlainDateTime

A calendar date and wall-clock time without a time zone (e.g. 2024-03-15T10:30:00).

Use PlainDateTime for events whose time zone is tracked separately, or for wall-clock displays. For unambiguous moments in time, use Instant or ZonedDateTime instead.

Instances

• Eq PlainDateTime
• Ord PlainDateTime
• Show PlainDateTime

data PlainDate

A calendar date without a time component or time zone (e.g. 2024-03-15).

Use PlainDate for birthdays, holidays, and other dates where time of day is irrelevant. Do not use for scheduling events — use ZonedDateTime instead.

Instances

• Eq PlainDate
• Ord PlainDate
• Show PlainDate

data Instant

An exact moment on the UTC timeline with nanosecond precision, independent of any time zone or calendar.

Use Instant for timestamps, event logs, and any case where you need an unambiguous point in time. Convert to ZonedDateTime when you need wall-clock representation in a specific time zone.

Instances

• Eq Instant
• Ord Instant
• Show Instant

data Duration

A length of time expressed as a combination of date and time components (years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds). All components must share the same sign.

Durations are unbalanced — { hours: 36 } is not automatically converted to { days: 1, hours: 12 }. Use round to balance.

Eq compares component-by-component (not total elapsed time), so { hours: 1 } is not equal to { minutes: 60 }.

Instances

• Eq Duration
• Show Duration