Temporal.Duration

type DurationFields = { days :: Number, hours :: Number, microseconds :: Number, milliseconds :: Number, minutes :: Number, months :: Number, nanoseconds :: Number, seconds :: Number, weeks :: Number, years :: Number }

All fields of a Duration. Every field defaults to 0.0 — set only the fields you need.

All non-zero fields must share the same sign, or construction will fail.

defaultDurationFields :: DurationFields

All fields set to 0.0. Use record update syntax:

duration (defaultDurationFields { hours = 2.0, minutes = 30.0 })

duration :: DurationFields -> Maybe Duration

Construct a Duration from explicit fields. Returns Nothing if the fields have mixed signs (e.g. positive years with negative months).

fromString :: String -> Maybe Duration

Parse an ISO 8601 duration string (e.g. "PT1H30M", "P1Y2M3D"). Returns Nothing for invalid strings.

Note: subsecond components are collapsed during serialization, so fromString (toString d) may produce a structurally different (but equal) duration. For example, { milliseconds: 1000 } serializes to "PT1S" and parses back as { seconds: 1 }.

years :: Number -> Duration

Create a duration of the given number of years. Always succeeds for finite values.

months :: Number -> Duration

Create a duration of the given number of months.

weeks :: Number -> Duration

Create a duration of the given number of weeks.

days :: Number -> Duration

Create a duration of the given number of days.

hours :: Number -> Duration

Create a duration of the given number of hours.

minutes :: Number -> Duration

Create a duration of the given number of minutes.

seconds :: Number -> Duration

Create a duration of the given number of seconds.

milliseconds :: Number -> Duration

Create a duration of the given number of milliseconds.

microseconds :: Number -> Duration

Create a duration of the given number of microseconds.

nanoseconds :: Number -> Duration

Create a duration of the given number of nanoseconds.

getYears :: Duration -> Number

getMonths :: Duration -> Number

getWeeks :: Duration -> Number

getDays :: Duration -> Number

getHours :: Duration -> Number

getMinutes :: Duration -> Number

getSeconds :: Duration -> Number

getMilliseconds :: Duration -> Number

getMicroseconds :: Duration -> Number

getNanoseconds :: Duration -> Number

sign :: Duration -> Int

The sign of the duration: 1 for positive, -1 for negative, 0 for blank.

blank :: Duration -> Boolean

Whether all fields are zero.

add :: Maybe RelativeTo -> Duration -> Duration -> Maybe Duration

Add two durations. Returns Nothing if the result would have mixed signs.

When adding durations that contain calendar units (years, months, weeks), a relativeTo reference point is required to resolve the variable length of those units.

-- Time-only: no relativeTo needed
add Nothing (hours 1.0) (hours 2.0)  -- Just PT3H

-- Calendar units: provide a reference date
add (Just (RelDate someDate)) (months 1.0) (months 2.0)  -- Just P3M

subtract :: Maybe RelativeTo -> Duration -> Duration -> Maybe Duration

Subtract one duration from another. Same caveats as add regarding calendar units and relativeTo.

negated :: Duration -> Duration

Return the duration with all component signs flipped. negated (negated d) == d for all durations.

abs :: Duration -> Duration

Return the duration with all components made non-negative. abs d == abs (negated d) for all durations.

type DurationRoundOptions = { largestUnit :: DateTimeUnit, relativeTo :: Maybe RelativeTo, roundingIncrement :: Int, roundingMode :: RoundingMode, smallestUnit :: DateTimeUnit }

Options for round. The roundingIncrement must evenly divide the next-larger unit's maximum (e.g. for minutes: 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30).

When relativeTo is Nothing, rounding fails for durations with calendar units. Provide a RelDate or RelDateTime for calendar-aware rounding, or a RelZoned for DST-aware rounding.

defaultDurationRoundOptions :: DurationRoundOptions

round :: DurationRoundOptions -> Duration -> Maybe Duration

Round and/or rebalance a duration. Returns Nothing if the operation fails (e.g. calendar units without relativeTo).

To rebalance without rounding, set largestUnit to the desired largest unit:

-- Time-only rebalancing
round (defaultDurationRoundOptions { largestUnit = TimeU Hours }) (minutes 90.0)
-- Just PT1H30M

-- Calendar-aware rebalancing
round (defaultDurationRoundOptions
  { largestUnit = DateU Years
  , relativeTo = Just (RelDate someDate)
  }) (months 18.0)
-- Just P1Y6M

type DurationTotalOptions = { relativeTo :: Maybe RelativeTo, unit :: DateTimeUnit }

Options for total.

When relativeTo is Nothing, computing the total fails for durations with calendar units. Provide a reference point to resolve calendar ambiguity.

defaultDurationTotalOptions :: DurationTotalOptions

total :: DurationTotalOptions -> Duration -> Maybe Number

Compute the total duration in the given unit as a fractional number. Returns Nothing if the operation fails (e.g. calendar units without relativeTo).

-- Time-only
total { unit: TimeU Minutes, relativeTo: Nothing } (hours 1.0)
-- Just 60.0

-- Calendar-aware: "how many months is 45 days from Jan 1?"
total { unit: DateU Months, relativeTo: Just (RelDate jan1) } (days 45.0)
-- Just 1.5 (approximately)

compare :: RelativeTo -> Duration -> Duration -> Ordering

Compare two durations relative to a reference point, returning their ordering.

Unlike Eq (which compares component-by-component), compare resolves durations to actual elapsed time from the reference point. This means compare ref (days 30.0) (months 1.0) can determine which is longer for a specific starting date.

A relativeTo is always required because even time-only durations are compared via the Temporal spec's Duration.compare static method.

compare (RelDate jan1) (days 31.0) (months 1.0)  -- EQ (January has 31 days)
compare (RelDate feb1) (days 30.0) (months 1.0)  -- GT (February has 28 days)

toString :: Duration -> String

Serialize to an ISO 8601 duration string (e.g. "PT1H30M").

zero :: Duration

The zero duration (all fields 0). blank zero == true.

data TimeUnit

Units that apply only to time components.

Constructors

• Hours
• Minutes
• Seconds
• Milliseconds
• Microseconds
• Nanoseconds

Instances

• Eq TimeUnit
• Ord TimeUnit
• Show TimeUnit
• Generic TimeUnit _
• EncodeJson TimeUnit
• DecodeJson TimeUnit

data RoundingMode

Rounding modes matching TC39 Temporal specification.

• HalfExpand (default) — round half toward positive infinity ("normal" rounding)
• Ceil — round toward positive infinity
• Floor — round toward negative infinity
• Trunc — round toward zero
• Expand — round away from zero
• HalfCeil — round half toward positive infinity
• HalfFloor — round half toward negative infinity
• HalfTrunc — round half toward zero
• HalfEven — round half to even (banker's rounding)

Constructors

• Ceil
• Floor
• Expand
• Trunc
• HalfCeil
• HalfFloor
• HalfExpand
• HalfTrunc
• HalfEven

Instances

• Eq RoundingMode
• Ord RoundingMode
• Show RoundingMode
• Generic RoundingMode _
• EncodeJson RoundingMode
• DecodeJson RoundingMode

data RelativeTo

A reference point for calendar-aware Duration operations (round, total, add, subtract, compare).

• RelDate — resolves calendar ambiguity (month/year lengths). All days are treated as exactly 24 hours. The duration is anchored at midnight.
• RelDateTime — same as RelDate but anchored at the given wall-clock time, which affects how hours cross day boundaries.
• RelZoned — resolves calendar ambiguity and DST. Days may be 23 or 25 hours near DST transitions.

Constructors

• RelDate PlainDate
• RelDateTime PlainDateTime
• RelZoned ZonedDateTime

Instances

• Generic RelativeTo _
• EncodeJson RelativeTo
• DecodeJson RelativeTo

data DateUnit

Units that apply only to date components.

Constructors

• Years
• Months
• Weeks
• Days

Instances

• Eq DateUnit
• Ord DateUnit
• Show DateUnit
• Generic DateUnit _
• EncodeJson DateUnit
• DecodeJson DateUnit

data DateTimeUnit

Combined date+time units for operations that accept either.

Constructors

• DateU DateUnit
• TimeU TimeUnit

Instances

• Eq DateTimeUnit
• Ord DateTimeUnit
• Show DateTimeUnit
• Generic DateTimeUnit _
• EncodeJson DateTimeUnit
• DecodeJson DateTimeUnit

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
• EncodeJson ZonedDateTime
• DecodeJson ZonedDateTime

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
• EncodeJson PlainDateTime
• DecodeJson 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
• EncodeJson PlainDate
• DecodeJson PlainDate

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
• EncodeJson Duration
• DecodeJson Duration