purescript-js-temporal

PureScript bindings for the JavaScript Temporal API.

spago install js-temporal

Module documentation is published on Pursuit.

The examples/ directory contains PureScript translations of recipes from the Temporal Cookbook. Each one can be run in the browser on Try PureScript:

• Frequently Asked Questions
  • Current date and time
  • Unix timestamp
• Converting between Temporal types and legacy Date
  • Convert between legacy Date and Temporal
• Construction
  • Calendar input element
• Converting between types
  • Noon on a particular date
  • Birthday in 2030
• Serialization
  • Zoned instant from instant and time zone
• Sorting
  • Sort PlainDateTime values
  • Sort ISO date/time strings
• Rounding
  • Round a time down to whole hours
  • Round a date to the nearest start of the month
• Time zone conversion
  • Preserving local time
  • Preserving exact time
  • Daily occurrence in local time
  • UTC offset for a zoned event
  • Dealing with dates and times in a fixed location
  • Book a meeting across time zones
• Arithmetic
  • How many days until a future date
  • Unit-constrained duration between now and a past/future zoned event
  • Next offset transition in a time zone
  • Comparison of an exact time to business hours
  • Flight arrival/departure/duration
  • Push back a launch date
  • Schedule a reminder ahead of matching a record-setting duration
  • Nth weekday of the month (variant)
  • Manipulating the day of the month
  • Same date in another month
  • Next weekly occurrence
  • Weekday of yearly occurrence
• Advanced use cases
  • Extra-expanded years
  • Adjustable Hijri calendar

Temporal types work directly with js-intl for locale-aware formatting—useful any time you need to display a date, time, or duration to a user.

Formatting dates and times with DateTimeFormat:

import JS.Intl.DateTimeFormat as DateTimeFormat
import JS.Intl.Locale as Locale
import JS.Temporal.PlainDate as PlainDate

do
  locale <- Locale.new_ "en-US"
  date <- PlainDate.from_ { year: 2024, month: 7, day: 1 }
  formatter <- DateTimeFormat.new [ locale ] { dateStyle: "long" }
  log (DateTimeFormat.format formatter date)
  -- "July 1, 2024"

Formatting durations with DurationFormat:

import JS.Intl.DurationFormat as DurationFormat
import JS.Intl.Locale as Locale
import JS.Temporal.Duration as Duration

do
  locale <- Locale.new_ "en-US"
  duration <- Duration.from { hours: 2, minutes: 30 }
  formatter <- DurationFormat.new [ locale ] { style: "long" }
  log (DurationFormat.format formatter duration)
  -- "2 hours and 30 minutes"

All Temporal types that represent a point in time (PlainDate, PlainTime, PlainDateTime, PlainYearMonth, PlainMonthDay, Instant, ZonedDateTime) work with DateTimeFormat, and Duration works with DurationFormat. See the examples/ directory for more usage patterns.

The library provides conversion functions between js-temporal types and datetime types, so you can integrate with existing code that uses Data.Date, Data.Time, Data.DateTime, or Data.DateTime.Instant.

Each module exports fromX / toX functions for its corresponding type — for example, PlainDate.fromDate and PlainDate.toDate. All conversions round-trip at the precision supported by datetime (milliseconds). Microsecond and nanosecond components are dropped when converting to datetime types.

Duration.fromMilliseconds and Duration.toMilliseconds support fixed-unit durations only (days, hours, minutes, seconds, milliseconds); calendar units (years, months, weeks) are not supported.

ZonedDateTime, PlainYearMonth, and PlainMonthDay have no datetime equivalents.