Module

JS.Temporal.ZonedDateTime

Package
purescript-js-temporal
Repository
pete-murphy/purescript-js-temporal

A date and time with time zone, representing a unique instant plus a time zone and calendar. Use when you need an absolute point in time with human-readable components in a specific zone.

See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime

#new Source

new :: BigInt -> String -> Effect ZonedDateTime

Creates a ZonedDateTime from epoch nanoseconds and a time zone ID.

locale <- JS.Intl.Locale.new_ "en-US"
zoned <- ZonedDateTime.new (BigInt.fromInt 0) "UTC"
formatter <- JS.Intl.DateTimeFormat.new [ locale ] { dateStyle: "long", timeStyle: "medium", timeZone: "UTC" }
Console.log (JS.Intl.DateTimeFormat.format formatter zoned)

January 1, 1970 at 12:00:00 AM

#from Source

from :: forall provided. ConvertOptionsWithDefaults ToFromOptions (Record FromOptions) (Record provided) (Record FromOptions) => Record provided -> String -> Effect ZonedDateTime

Parses an ISO 8601 string with time zone (e.g. "2024-01-15T12:00-05:00[America/New_York]"). Options: overflow, disambiguation, offset.

locale <- JS.Intl.Locale.new_ "en-US"
zoned <- ZonedDateTime.from { overflow: Overflow.Constrain } "2024-01-15T12:00:00-05:00[America/New_York]"
formatter <- JS.Intl.DateTimeFormat.new [ locale ] { dateStyle: "long", timeStyle: "medium" }
Console.log (JS.Intl.DateTimeFormat.format formatter zoned)

January 15, 2024 at 12:00:00 PM

#from_ Source

from_ :: String -> Effect ZonedDateTime

Same as from with default options.

#year Source

year :: ZonedDateTime -> Int

Calendar year in this zoned date-time's calendar.

#month Source

month :: ZonedDateTime -> Int

Calendar month number in this zoned date-time's calendar.

#day Source

day :: ZonedDateTime -> Int

Day of the month in this zoned date-time's calendar.

#monthCode Source

monthCode :: ZonedDateTime -> String

Calendar-specific month code (for example "M01").

#hour Source

hour :: ZonedDateTime -> Int

Hour of the day in the zoned wall-clock view.

#minute Source

minute :: ZonedDateTime -> Int

Minute of the hour in the zoned wall-clock view.

#second Source

second :: ZonedDateTime -> Int

Second of the minute in the zoned wall-clock view.

#millisecond Source

millisecond :: ZonedDateTime -> Int

Millisecond of the second in the zoned wall-clock view.

#microsecond Source

microsecond :: ZonedDateTime -> Int

Microsecond of the millisecond in the zoned wall-clock view.

#nanosecond Source

nanosecond :: ZonedDateTime -> Int

Nanosecond of the microsecond in the zoned wall-clock view.

#dayOfWeek Source

dayOfWeek :: ZonedDateTime -> Int

ISO day of week, from 1 (Monday) to 7 (Sunday).

#dayOfYear Source

dayOfYear :: ZonedDateTime -> Int

Day number within the year in this zoned date-time's calendar.

#weekOfYear Source

weekOfYear :: ZonedDateTime -> Maybe Int

Week number within the year, if the calendar defines week numbering.

#yearOfWeek Source

yearOfWeek :: ZonedDateTime -> Maybe Int

Week-numbering year, if the calendar defines week numbering.

#daysInMonth Source

daysInMonth :: ZonedDateTime -> Int

Number of days in the current month.

#daysInYear Source

daysInYear :: ZonedDateTime -> Int

Number of days in the current year.

#daysInWeek Source

daysInWeek :: ZonedDateTime -> Int

Number of days in the current week according to the calendar.

#monthsInYear Source

monthsInYear :: ZonedDateTime -> Int

Number of months in the current year.

#inLeapYear Source

inLeapYear :: ZonedDateTime -> Boolean

Whether the current year is a leap year in this calendar.

#calendarId Source

calendarId :: ZonedDateTime -> String

Identifier of the current calendar (for example "iso8601").

#era Source

era :: ZonedDateTime -> Maybe String

Calendar era name, if this calendar uses eras.

#eraYear Source

eraYear :: ZonedDateTime -> Maybe Int

Year number within the current era, if this calendar uses eras.

#timeZoneId Source

timeZoneId :: ZonedDateTime -> String

Identifier of the associated time zone (for example "America/New_York").

#offset Source

offset :: ZonedDateTime -> String

Numeric UTC offset string for this instant in the associated time zone.

#offsetNanoseconds Source

offsetNanoseconds :: ZonedDateTime -> Int

UTC offset for this instant, in nanoseconds.

#hoursInDay Source

hoursInDay :: ZonedDateTime -> Int

Number of wall-clock hours in this calendar day in the associated time zone.

#epochMilliseconds Source

epochMilliseconds :: ZonedDateTime -> Number

Milliseconds since the Unix epoch for the represented instant.

#epochNanoseconds Source

epochNanoseconds :: ZonedDateTime -> BigInt

Nanoseconds since the Unix epoch for the represented instant.

#add Source

add :: forall provided. ConvertOptionsWithDefaults ToArithmeticOptions (Record ArithmeticOptions) (Record provided) (Record ArithmeticOptions) => Record provided -> Duration -> ZonedDateTime -> Effect ZonedDateTime

Adds a duration. Supports calendar durations. Options: overflow.

locale <- JS.Intl.Locale.new_ "en-US"
start <- ZonedDateTime.from_ "2024-01-15T12:00:00-05:00[America/New_York]"
twoHours <- Duration.new { hours: 2 }
later <- ZonedDateTime.add { overflow: Overflow.Constrain } twoHours start
formatter <- JS.Intl.DateTimeFormat.new [ locale ] { dateStyle: "long", timeStyle: "medium" }
Console.log (JS.Intl.DateTimeFormat.format formatter later)

January 15, 2024 at 2:00:00 PM

#add_ Source

add_ :: Duration -> ZonedDateTime -> Effect ZonedDateTime

Same as add with default options.

#subtract Source

subtract :: forall provided. ConvertOptionsWithDefaults ToArithmeticOptions (Record ArithmeticOptions) (Record provided) (Record ArithmeticOptions) => Record provided -> Duration -> ZonedDateTime -> Effect ZonedDateTime

Subtracts a duration. Arg order: subtract options duration subject.

locale <- JS.Intl.Locale.new_ "en-US"
zoned <- ZonedDateTime.from_ "2024-03-15T14:00:00[America/New_York]"
twoHours <- Duration.new { hours: 2 }
earlier <- ZonedDateTime.subtract { overflow: Overflow.Constrain } twoHours zoned
formatter <- JS.Intl.DateTimeFormat.new [ locale ] { dateStyle: "long", timeStyle: "medium" }
Console.log (JS.Intl.DateTimeFormat.format formatter earlier)

March 15, 2024 at 12:00:00 PM

#subtract_ Source

subtract_ :: Duration -> ZonedDateTime -> Effect ZonedDateTime

Same as subtract with default options.

#with Source

with :: forall optsProvided fields rest. Union fields rest WithFields => ConvertOptionsWithDefaults ToFromOptions (Record FromOptions) (Record optsProvided) (Record FromOptions) => Record optsProvided -> Record fields -> ZonedDateTime -> Effect ZonedDateTime

Returns a copy with some wall-clock fields replaced. Options: overflow, disambiguation, offset.

locale <- JS.Intl.Locale.new_ "en-US"
meeting <- ZonedDateTime.from_ "2024-01-15T09:30:45-05:00[America/New_York]"
noon <- ZonedDateTime.with { overflow: Overflow.Constrain } { hour: 12, minute: 0, second: 0 } meeting
formatter <- JS.Intl.DateTimeFormat.new [ locale ] { dateStyle: "long", timeStyle: "medium" }
Console.log (JS.Intl.DateTimeFormat.format formatter noon)

January 15, 2024 at 12:00:00 PM

#with_ Source

with_ :: forall fields rest. Union fields rest WithFields => Record fields -> ZonedDateTime -> Effect ZonedDateTime

Same as with with default options.

#withTimeZone Source

withTimeZone :: String -> ZonedDateTime -> Effect ZonedDateTime

Returns the same instant interpreted in a different time zone.

zoned <- ZonedDateTime.from_ "2024-01-15T12:00:00-05:00[America/New_York]"
inTokyo <- ZonedDateTime.withTimeZone "Asia/Tokyo" zoned
Console.log (ZonedDateTime.toString_ inTokyo)

2024-01-16T02:00:00+09:00[Asia/Tokyo]

#withCalendar Source

withCalendar :: String -> ZonedDateTime -> Effect ZonedDateTime

Returns a copy with the same instant and time zone, but a different calendar.

zoned <- ZonedDateTime.from_ "2024-01-15T12:00:00-05:00[America/New_York]"
gregory <- ZonedDateTime.withCalendar "gregory" zoned
Console.log (ZonedDateTime.toString { calendarName: CalendarName.Always } gregory)

2024-01-15T12:00:00-05:00[America/New_York][u-ca=gregory]

#withPlainTime Source

withPlainTime :: PlainTime -> ZonedDateTime -> Effect ZonedDateTime

Returns a copy with the wall-clock time replaced.

zoned <- ZonedDateTime.from_ "2024-01-15T09:30:45-05:00[America/New_York]"
closingTime <- PlainTime.from_ "17:00:00"
updated <- ZonedDateTime.withPlainTime closingTime zoned
Console.log (ZonedDateTime.toString_ updated)

2024-01-15T17:00:00-05:00[America/New_York]

#withPlainDate Source

withPlainDate :: PlainDate -> ZonedDateTime -> Effect ZonedDateTime

Returns a copy with the calendar date replaced.

zoned <- ZonedDateTime.from_ "2024-01-15T09:30:45-05:00[America/New_York]"
nextDay <- PlainDate.from_ "2024-01-16"
updated <- ZonedDateTime.withPlainDate nextDay zoned
Console.log (ZonedDateTime.toString_ updated)

2024-01-16T09:30:45-05:00[America/New_York]

#until Source

until :: forall provided. ConvertOptionsWithDefaults ToDifferenceOptions (Record DifferenceOptions) (Record provided) (Record DifferenceOptions) => Record provided -> ZonedDateTime -> ZonedDateTime -> Effect Duration

Duration from subject (last arg) until other (second arg). Arg order: until options other subject.

locale <- JS.Intl.Locale.new_ "en-US"
departure <- ZonedDateTime.from_ "2020-03-08T11:55:00+08:00[Asia/Hong_Kong]"
arrival <- ZonedDateTime.from_ "2020-03-08T09:50:00-07:00[America/Los_Angeles]"
flightTime <- ZonedDateTime.until { largestUnit: TemporalUnit.Hour } arrival departure
formatter <- JS.Intl.DurationFormat.new [ locale ] { style: "long" }
Console.log ("Flight time: " <> JS.Intl.DurationFormat.format formatter flightTime)

Flight time: 12 hours, 55 minutes

#until_ Source

until_ :: ZonedDateTime -> ZonedDateTime -> Effect Duration

Same as until with default options. Arg order: until_ other subject.

#since Source

since :: forall provided. ConvertOptionsWithDefaults ToDifferenceOptions (Record DifferenceOptions) (Record provided) (Record DifferenceOptions) => Record provided -> ZonedDateTime -> ZonedDateTime -> Effect Duration

Duration from other to subject (inverse of until). Arg order: since options other subject.

locale <- JS.Intl.Locale.new_ "en-US"
start <- ZonedDateTime.from_ "2024-01-01T00:00:00[America/New_York]"
end <- ZonedDateTime.from_ "2024-03-15T12:00:00[America/New_York]"
elapsed <- ZonedDateTime.since { largestUnit: TemporalUnit.Hour } start end
formatter <- JS.Intl.DurationFormat.new [ locale ] { style: "long" }
Console.log ("Elapsed: " <> JS.Intl.DurationFormat.format formatter elapsed)

Elapsed: 1,787 hours

#since_ Source

since_ :: ZonedDateTime -> ZonedDateTime -> Effect Duration

Same as since with default options. Arg order: since_ other subject.

#round Source

round :: forall provided. ConvertOptionsWithDefaults ToRoundOptions (Record RoundOptions) (Record provided) (Record RoundOptions) => Record provided -> ZonedDateTime -> Effect ZonedDateTime

Rounds this zoned date-time to a smaller unit. Options: smallestUnit, roundingIncrement, roundingMode.

zoned <- ZonedDateTime.from_ "2024-01-15T09:30:45.123456789-05:00[America/New_York]"
rounded <- ZonedDateTime.round { smallestUnit: TemporalUnit.Minute, roundingMode: RoundingMode.HalfExpand } zoned
Console.log (ZonedDateTime.toString_ rounded)

2024-01-15T09:31:00-05:00[America/New_York]

#startOfDay Source

startOfDay :: ZonedDateTime -> Effect ZonedDateTime

Returns the start of the calendar day in this time zone.

zoned <- ZonedDateTime.from_ "2024-03-10T12:00:00-04:00[America/New_York]"
start <- ZonedDateTime.startOfDay zoned
Console.log (ZonedDateTime.toString_ start)

2024-03-10T00:00:00-05:00[America/New_York]

#getTimeZoneTransition Source

getTimeZoneTransition :: String -> ZonedDateTime -> Maybe ZonedDateTime

Gets the next or previous time zone transition. Direction: "next" or "previous".

zoned <- ZonedDateTime.from_ "2024-03-09T12:00:00-05:00[America/New_York]"
case ZonedDateTime.getTimeZoneTransition "next" zoned of
  Nothing -> Console.log "No transition"
  Just transition -> Console.log (ZonedDateTime.toString_ transition)

2024-03-10T03:00:00-04:00[America/New_York]

#toInstant Source

toInstant :: ZonedDateTime -> Instant

Extracts the absolute instant (no time zone).

zoned <- ZonedDateTime.from_ "2024-01-15T12:00:00-05:00[America/New_York]"
Console.log (Instant.toString_ (ZonedDateTime.toInstant zoned))

2024-01-15T17:00:00Z

#toPlainDateTime Source

toPlainDateTime :: ZonedDateTime -> PlainDateTime

Extracts date and time in the zoned wall-clock view (drops time zone).

zoned <- ZonedDateTime.from_ "2024-01-15T12:00:00-05:00[America/New_York]"
Console.log (PlainDateTime.toString_ (ZonedDateTime.toPlainDateTime zoned))

2024-01-15T12:00:00

#toPlainDate Source

toPlainDate :: ZonedDateTime -> PlainDate

Extracts the calendar date in the zoned wall-clock view.

zoned <- ZonedDateTime.from_ "2024-01-15T12:00:00-05:00[America/New_York]"
Console.log (PlainDate.toString_ (ZonedDateTime.toPlainDate zoned))

2024-01-15

#toPlainTime Source

toPlainTime :: ZonedDateTime -> PlainTime

Extracts the wall-clock time in the associated time zone.

zoned <- ZonedDateTime.from_ "2024-01-15T12:00:00-05:00[America/New_York]"
Console.log (PlainTime.toString_ (ZonedDateTime.toPlainTime zoned))

12:00:00

#toPlainYearMonth Source

toPlainYearMonth :: ZonedDateTime -> PlainYearMonth

Extracts the year and month in the zoned wall-clock view.

zoned <- ZonedDateTime.from_ "2024-01-15T12:00:00-05:00[America/New_York]"
Console.log (PlainYearMonth.toString_ (ZonedDateTime.toPlainYearMonth zoned))

2024-01

#toPlainMonthDay Source

toPlainMonthDay :: ZonedDateTime -> PlainMonthDay

Extracts the month and day in the zoned wall-clock view.

zoned <- ZonedDateTime.from_ "2024-01-15T12:00:00-05:00[America/New_York]"
Console.log (PlainMonthDay.toString_ (ZonedDateTime.toPlainMonthDay zoned))

01-15

#toString Source

toString :: forall provided. ConvertOptionsWithDefaults ToToStringOptions (Record ToStringOptions) (Record provided) (Record ToStringOptions) => Record provided -> ZonedDateTime -> String

Serializes to ISO 8601 format with time zone. Options: calendarName, timeZoneName, offset, fractionalSecondDigits, smallestUnit, roundingMode.

zoned <- ZonedDateTime.from_ "2024-01-15T12:00:00.123456789-05:00[America/New_York]"
Console.log
  ( ZonedDateTime.toString
      { smallestUnit: TemporalUnit.Minute
      , calendarName: CalendarName.Never
      }
      zoned
  )

2024-01-15T12:00-05:00[America/New_York]

#toString_ Source

toString_ :: ZonedDateTime -> String

Same as toString with default options.

Re-exports from JS.Temporal.ZonedDateTime.Internal

Modules
JS.Temporal.Duration
JS.Temporal.Duration.Internal
JS.Temporal.Instant
JS.Temporal.Instant.Internal
JS.Temporal.Internal
JS.Temporal.Now
JS.Temporal.Options.CalendarName
JS.Temporal.Options.Disambiguation
JS.Temporal.Options.OffsetDisambiguation
JS.Temporal.Options.Overflow
JS.Temporal.Options.RoundingMode
JS.Temporal.Options.TemporalUnit
JS.Temporal.PlainDate
JS.Temporal.PlainDate.Internal
JS.Temporal.PlainDateTime
JS.Temporal.PlainDateTime.Internal
JS.Temporal.PlainMonthDay
JS.Temporal.PlainMonthDay.Internal
JS.Temporal.PlainTime
JS.Temporal.PlainTime.Internal
JS.Temporal.PlainYearMonth
JS.Temporal.PlainYearMonth.Internal
JS.Temporal.ZonedDateTime
JS.Temporal.ZonedDateTime.Internal