Temporal.Instant

fromEpochNanoseconds :: BigInt -> Maybe Instant

Construct an Instant from nanoseconds since the Unix epoch. Returns Nothing if the value is outside the representable range (approximately ±10^8 days from epoch).

fromEpochMilliseconds :: Number -> Maybe Instant

Construct an Instant from milliseconds since the Unix epoch. Returns Nothing if the value is outside the representable range.

The fractional part is truncated (not rounded).

fromString :: String -> Maybe Instant

Parse an ISO 8601 string with a UTC offset (e.g. "2024-03-15T10:30:00Z", "2024-03-15T10:30:00+05:30"). Returns Nothing for invalid strings or strings without a UTC offset.

getEpochMilliseconds :: Instant -> Number

Milliseconds since the Unix epoch. This may lose sub-millisecond precision.

getEpochNanoseconds :: Instant -> BigInt

Nanoseconds since the Unix epoch (full precision).

add :: Duration -> Instant -> Maybe Instant

Add a time-only duration. Returns Nothing if the duration contains date components (years, months, weeks, or days) or if the result would be outside the representable range.

subtract :: Duration -> Instant -> Maybe Instant

Subtract a time-only duration. Same restrictions as add.

type InstantDiffOptions = { largestUnit :: TimeUnit, roundingIncrement :: Int, roundingMode :: RoundingMode, smallestUnit :: TimeUnit }

Options for since and until. Only time units (hours and below) are allowed. Default: largest unit is Hours, smallest unit is Nanoseconds.

defaultInstantDiffOptions :: InstantDiffOptions

since :: InstantDiffOptions -> Instant -> Instant -> 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 :: InstantDiffOptions -> Instant -> Instant -> 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' :: Instant -> Instant -> Duration

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

until' :: Instant -> Instant -> Duration

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

type InstantRoundOptions = { roundingIncrement :: Int, roundingMode :: RoundingMode, smallestUnit :: TimeUnit }

Options for round. Only time units are allowed.

defaultInstantRoundOptions :: InstantRoundOptions

round :: InstantRoundOptions -> Instant -> Instant

Round the instant to the given precision.

toZonedDateTimeISO :: String -> Instant -> ZonedDateTime

Convert to a ZonedDateTime in the given IANA time zone using the ISO 8601 calendar.

toZonedDateTimeISO "America/New_York" instant

toString :: Instant -> String

Serialize to an ISO 8601 string with Z suffix (e.g. "2024-03-15T10:30:00Z").

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 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