purescript-js-temporal

PureScript bindings for the JavaScript Temporal API.

spago install js-temporal

Module documentation is published on Pursuit.

The examples/ directory is a separate Spago package containing PureScript translations of recipes from the Temporal Cookbook. Run all examples:

nix develop
just run-examples

Or run a single example:

spago run -p js-temporal-examples -m Examples.Cookbook.CurrentDateTime

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.