JS.Temporal.Instant

fromString :: String -> Effect Instant

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

exampleFromString :: Effect Unit
exampleFromString = do
  locale <- JS.Intl.Locale.new_ "en-US"
  instant <- Instant.fromString "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 :: Number -> Effect Instant

Creates an Instant from epoch milliseconds.

exampleFromEpochMilliseconds :: Effect Unit
exampleFromEpochMilliseconds = do
  instant <- Instant.fromEpochMilliseconds 1000.0
  Console.log (Instant.toString instant)

1970-01-01T00:00:01Z

fromEpochNanoseconds :: BigInt -> Effect Instant

Creates an Instant from epoch nanoseconds.

exampleFromEpochNanoseconds :: Effect Unit
exampleFromEpochNanoseconds = do
  instant <- Instant.fromEpochNanoseconds (BigInt.fromInt 1000000000)
  Console.log (Instant.toString instant)

1970-01-01T00:00:01Z

fromJSDate :: JSDate -> Effect Instant

Creates an Instant from a JavaScript Date.

exampleFromJSDate :: Effect Unit
exampleFromJSDate = do
  jsDate <- JSDate.parse "2024-01-15T12:00:00Z"
  instant <- Instant.fromJSDate jsDate
  Console.log (Instant.toString instant)

2024-01-15T12:00:00Z

epochMilliseconds :: Instant -> Number

Milliseconds since the Unix epoch.

exampleEpochMilliseconds :: Effect Unit
exampleEpochMilliseconds = do
  instant <- Instant.fromString "1970-01-01T00:00:01Z"
  Console.log ("Epoch ms: " <> show (Instant.epochMilliseconds instant))

Epoch ms: 1000.0

epochNanoseconds :: Instant -> BigInt

Nanoseconds since the Unix epoch.

exampleEpochNanoseconds :: Effect Unit
exampleEpochNanoseconds = do
  instant <- Instant.fromString "1970-01-01T00:00:01Z"
  Console.log ("Epoch ns: " <> show (Instant.epochNanoseconds instant))

Epoch ns: 1000000000

add :: Duration -> Instant -> Effect Instant

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

exampleAdd :: Effect Unit
exampleAdd = do
  instant <- Instant.fromString "2024-01-15T12:00:00Z"
  oneHour <- Duration.from { hours: 1 }
  later <- Instant.add oneHour instant
  Console.log (Instant.toString later)

2024-01-15T13:00:00Z

subtract :: Duration -> Instant -> Effect Instant

Subtracts a duration. Arg order: subtract duration instant.

exampleSubtract :: Effect Unit
exampleSubtract = do
  instant <- Instant.fromString "2024-01-15T12:00:00Z"
  oneHour <- Duration.from { hours: 1 }
  earlier <- Instant.subtract oneHour instant
  Console.log (Instant.toString earlier)

2024-01-15T11:00:00Z

untilWithOptions :: 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: untilWithOptions options other subject.

exampleUntilWithOptions :: Effect Unit
exampleUntilWithOptions = do
  locale <- JS.Intl.Locale.new_ "en-US"
  earlier <- Instant.fromString "2020-01-09T00:00Z"
  later <- Instant.fromString "2020-01-09T04:00Z"
  result <- Instant.untilWithOptions { 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 :: Instant -> Instant -> Effect Duration

Same as untilWithOptions with default options.

exampleUntil :: Effect Unit
exampleUntil = do
  earlier <- Instant.fromString "2020-01-09T00:00Z"
  later <- Instant.fromString "2020-01-09T04:00Z"
  result <- Instant.until later earlier
  Console.log (Duration.toString result)

PT14400S

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

Duration from other to subject (inverse of untilWithOptions). Arg order: sinceWithOptions options other subject.

exampleSinceWithOptions :: Effect Unit
exampleSinceWithOptions = do
  locale <- JS.Intl.Locale.new_ "en-US"
  earlier <- Instant.fromString "2020-01-09T00:00Z"
  later <- Instant.fromString "2020-01-09T04:00Z"
  elapsed <- Instant.sinceWithOptions { 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 :: Instant -> Instant -> Effect Duration

Same as sinceWithOptions with default options.

exampleSince :: Effect Unit
exampleSince = do
  earlier <- Instant.fromString "2020-01-09T00:00Z"
  later <- Instant.fromString "2020-01-09T04:00Z"
  elapsed <- Instant.since earlier later
  Console.log (Duration.toString elapsed)

PT14400S

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.

exampleRound :: Effect Unit
exampleRound = do
  instant <- Instant.fromString "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 :: Instant -> Effect Instant

Converts a purescript-datetime Instant to a Temporal Instant.

exampleFromDateTimeInstant :: Effect Unit
exampleFromDateTimeInstant = do
  let dtInstant = DateTime.Instant.fromDateTime bottom
  instant <- Instant.fromDateTimeInstant dtInstant
  Console.log (Instant.toString instant)

-271820-01-01T00:00:00Z

toDateTimeInstant :: Instant -> Maybe Instant

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

exampleToDateTimeInstant :: Effect Unit
exampleToDateTimeInstant = do
  instant <- Instant.fromString "2024-01-15T12:00:00Z"
  case Instant.toDateTimeInstant instant of
    Just dtInstant -> Console.log (show dtInstant)
    Nothing -> Console.log "Out of range"

(Instant (Milliseconds 1705320000000.0))

toZonedDateTimeISO :: String -> Instant -> ZonedDateTime

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

exampleToZonedDateTimeISO :: Effect Unit
exampleToZonedDateTimeISO = do
  instant <- Instant.fromString "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]

toStringWithOptions :: 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.

exampleToStringWithOptions :: Effect Unit
exampleToStringWithOptions = do
  instant <- Instant.fromString "2024-01-15T12:00:00.789Z"
  Console.log
    ( Instant.toStringWithOptions
        { smallestUnit: TemporalUnit.Second
        , timeZone: "UTC"
        }
        instant
    )

2024-01-15T12:00:00+00:00

toString :: Instant -> String

Same as toStringWithOptions with default options.

exampleToString :: Effect Unit
exampleToString = do
  instant <- Instant.fromString "2024-01-15T12:00:00.789Z"
  Console.log (Instant.toString instant)

2024-01-15T12:00:00.789Z

data ToDifferenceOptions

Instances

• ConvertOption ToDifferenceOptions "largestUnit" TemporalUnit String
• ConvertOption ToDifferenceOptions "largestUnit" String String
• ConvertOption ToDifferenceOptions "smallestUnit" TemporalUnit String
• ConvertOption ToDifferenceOptions "smallestUnit" String String
• ConvertOption ToDifferenceOptions "roundingIncrement" Int Int
• ConvertOption ToDifferenceOptions "roundingMode" RoundingMode String
• ConvertOption ToDifferenceOptions "roundingMode" String String

data ToRoundOptions

Instances

• ConvertOption ToRoundOptions "smallestUnit" TemporalUnit String
• ConvertOption ToRoundOptions "smallestUnit" String String
• ConvertOption ToRoundOptions "roundingIncrement" Int Int
• ConvertOption ToRoundOptions "roundingMode" RoundingMode String
• ConvertOption ToRoundOptions "roundingMode" String String

data ToToStringOptions

Instances

• ConvertOption ToToStringOptions "fractionalSecondDigits" Int Foreign
• ConvertOption ToToStringOptions "fractionalSecondDigits" String Foreign
• ConvertOption ToToStringOptions "smallestUnit" TemporalUnit String
• ConvertOption ToToStringOptions "smallestUnit" String String
• ConvertOption ToToStringOptions "roundingMode" RoundingMode String
• ConvertOption ToToStringOptions "roundingMode" String String
• ConvertOption ToToStringOptions "timeZone" String String

data Instant

A point in time (opaque type).

Instances

• Eq Instant
• Ord Instant
• Show Instant
• DateTimeLike Instant