Module

JS.Temporal.Instant

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

A point in time with nanosecond precision, represented as nanoseconds since the Unix epoch (1970-01-01T00:00:00Z). No time zone or calendar. Use toZonedDateTimeISO to interpret in a time zone.

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

#new Source

new :: BigInt -> Effect Instant

Creates an Instant from epoch nanoseconds.

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

January 1, 1970 at 12:00:00 AM

#from Source

from :: String -> Effect Instant

Parses an ISO 8601 instant string (e.g. "2024-01-15T12:00:00Z"). Throws on invalid input.

locale <- JS.Intl.Locale.new_ "en-US"
instant <- Instant.from "2024-01-15T12:00:00Z"
formatter <- JS.Intl.DateTimeFormat.new [ locale ] { dateStyle: "long", timeStyle: "medium", timeZone: "UTC" }
Console.log (JS.Intl.DateTimeFormat.format formatter instant)

January 15, 2024 at 12:00:00 PM

#fromEpochMilliseconds Source

fromEpochMilliseconds :: Number -> Effect Instant

Creates an Instant from epoch milliseconds.

instant <- Instant.fromEpochMilliseconds 1000.0
Console.log (Instant.toString_ instant)

1970-01-01T00:00:01Z

#fromEpochNanoseconds Source

fromEpochNanoseconds :: BigInt -> Effect Instant

Creates an Instant from epoch nanoseconds.

instant <- Instant.fromEpochNanoseconds (BigInt.fromInt 1000000000)
Console.log (Instant.toString_ instant)

1970-01-01T00:00:01Z

#epochMilliseconds Source

epochMilliseconds :: Instant -> Number

Milliseconds since the Unix epoch.

#epochNanoseconds Source

epochNanoseconds :: Instant -> BigInt

Nanoseconds since the Unix epoch.

#add Source

add :: Duration -> Instant -> Effect Instant

Adds a duration to an instant. Throws for calendar durations.

instant <- Instant.from "2024-01-15T12:00:00Z"
oneHour <- Duration.new { hours: 1 }
later <- Instant.add oneHour instant
Console.log (Instant.toString_ later)

2024-01-15T13:00:00Z

#subtract Source

subtract :: Duration -> Instant -> Effect Instant

Subtracts a duration. Arg order: subtract duration instant.

instant <- Instant.from "2024-01-15T12:00:00Z"
oneHour <- Duration.new { hours: 1 }
earlier <- Instant.subtract oneHour instant
Console.log (Instant.toString_ earlier)

2024-01-15T11:00:00Z

#until Source

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

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

locale <- JS.Intl.Locale.new_ "en-US"
earlier <- Instant.from "2020-01-09T00:00Z"
later <- Instant.from "2020-01-09T04:00Z"
result <- Instant.until { largestUnit: TemporalUnit.Hour } later earlier
formatter <- JS.Intl.DurationFormat.new [ locale ] { style: "long" }
Console.log ("4 hours: " <> JS.Intl.DurationFormat.format formatter result)

4 hours: 4 hours

#until_ Source

until_ :: Instant -> Instant -> Effect Duration

Same as until with default options.

#since Source

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

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

locale <- JS.Intl.Locale.new_ "en-US"
earlier <- Instant.from "2020-01-09T00:00Z"
later <- Instant.from "2020-01-09T04:00Z"
elapsed <- Instant.since { largestUnit: TemporalUnit.Hour } earlier later
formatter <- JS.Intl.DurationFormat.new [ locale ] { style: "long" }
Console.log ("Elapsed: " <> JS.Intl.DurationFormat.format formatter elapsed)

Elapsed: 4 hours

#since_ Source

since_ :: Instant -> Instant -> Effect Duration

Same as since with default options.

#round Source

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

Rounds the instant to the given smallest unit. Options: smallestUnit, roundingIncrement, roundingMode.

instant <- Instant.from "2024-01-15T12:00:00.789Z"
rounded <- Instant.round
  { smallestUnit: TemporalUnit.Second
  , roundingMode: RoundingMode.HalfExpand
  }
  instant
Console.log (Instant.toString_ rounded)

2024-01-15T12:00:01Z

#fromDateTimeInstant Source

fromDateTimeInstant :: Instant -> Effect Instant

Converts a purescript-datetime Instant to a Temporal Instant.

#toDateTimeInstant Source

toDateTimeInstant :: Instant -> Maybe Instant

Converts a Temporal Instant to a purescript-datetime Instant. Returns Nothing if the value is outside the datetime Instant range.

#toZonedDateTimeISO Source

toZonedDateTimeISO :: String -> Instant -> ZonedDateTime

Converts the instant to a ZonedDateTime in the given time zone (e.g. "America/New_York").

instant <- Instant.from "2024-01-15T12:00:00Z"
zoned <- pure (Instant.toZonedDateTimeISO "America/New_York" instant)
Console.log (ZonedDateTime.toString_ zoned)

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

#toString Source

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

Serializes the instant to ISO 8601 format. Options: fractionalSecondDigits, smallestUnit, roundingMode, timeZone.

instant <- Instant.from "2024-01-15T12:00:00.789Z"
Console.log
  ( Instant.toString
      { smallestUnit: TemporalUnit.Second
      , timeZone: "UTC"
      }
      instant
  )