Instant

Create and Parse

Constructor

inst = new Temporal.Instant(1553906700000000000n)

But use .fromEpochNanoseconds() instead.

From Epoch Time

Depends on the unit

.fromEpochNanoseconds()

inst = Temporal.Instant.fromEpochNanoseconds(1553906700000000000n)

.fromEpochMicroseconds()

inst = Temporal.Instant.fromEpochMicroseconds(1553906700000000n)

.fromEpochMilliseconds()

inst = Temporal.Instant.fromEpochMilliseconds(1553906700000)

.fromEpochSeconds()

inst = Temporal.Instant.fromEpochSeconds(1553906700)

From String

Must end with a Z.

inst = Temporal.Instant.from('2007-02-02T12341234Z')

From Other

Accepts a ZonedDateTime (prefer ZonedDateTime::toInstant()). Also accepts another ZonedDateTime.

inst = Temporal.Instant.from(anotherInst)
inst = Temporal.Instant.from(zdt)

Now

inst = Temporal.Now.instant()

Get Epoch Time

.epochNanoseconds

inst.epochNanoseconds // 1553906700000000000n

.epochMicroseconds

inst.epochMicroseconds // 1553906700000000n

.epochMilliseconds

inst.epochMilliseconds // 1553906700000

.epochSeconds

inst.epochSeconds // 1553906700

Math

Add and Subtract

You can only add or subtract time units. Years/months/weeks/days are not supported.

inst2 = inst.add({
  hours: 3,
  second: 30,
})

inst2 = inst.subtract({
  hours: 3,
  second: 30,
})

Round

You can round to a time unit.

inst.round('hour')
// or
inst.round({
  smallestUnit: 'hour',
  roundingIncrement: 1,
  roundingMode: 'halfExpand',
})

Learn about all the settings.

Start of Unit

Start of hour:

inst2 = inst.round({
  smallestUnit: 'hour',
  roundingMode: 'floor',
})

import { startOfHour } from 'temporal-utils'

inst2 = startOfHour(inst)

Start of minute:

inst2 = inst.round({
  smallestUnit: 'minute',
  roundingMode: 'floor',
})

import { startOfMinute } from 'temporal-utils'

inst2 = startOfMinute(inst)

Start of second:

inst2 = inst.round({
  smallestUnit: 'second',
  roundingMode: 'floor',
})

import { startOfSecond } from 'temporal-utils'

inst2 = startOfSecond(inst)

Start of millisecond:

inst2 = inst.round({
  smallestUnit: 'millisecond',
  roundingMode: 'floor',
})

import { startOfMillisecond } from 'temporal-utils'

inst2 = startOfMillisecond(inst)

Start of microsecond:

inst2 = inst.round({
  smallestUnit: 'microsecond',
  roundingMode: 'floor',
})

import { startOfMicrosecond } from 'temporal-utils'

inst2 = startOfMicrosecond(inst)

End of Unit

Explain inclusive vs exclusive.

End of hour:

inst2 = inst.round({ // sufficient for exclusive end
  smallestUnit: 'hour',
  roundingMode: 'ceil',
}).subtract({ nanoseconds: 1 }) // inclusive end

import { endOfHourExcl, endOfHourIncl } from 'temporal-utils'

inst2 = endOfHourExcl(inst)
inst2 = endOfHourIncl(inst)

End of minute:

inst2 = inst.round({ // sufficient for exclusive end
  smallestUnit: 'minute',
  roundingMode: 'ceil',
}).subtract({ nanoseconds: 1 }) // inclusive end

import { endOfMinuteExcl, endOfMinuteIncl } from 'temporal-utils'

inst2 = endOfMinuteExcl(inst)
inst2 = endOfMinuteIncl(inst)

End of second:

inst2 = inst.round({ // sufficient for exclusive end
  smallestUnit: 'second',
  roundingMode: 'ceil',
}).subtract({ nanoseconds: 1 }) // inclusive end

import { endOfSecondExcl, endOfSecondIncl } from 'temporal-utils'

inst2 = endOfSecondExcl(inst)
inst2 = endOfSecondIncl(inst)

End of millisecond:

inst2 = inst.round({ // sufficient for exclusive end
  smallestUnit: 'millisecond',
  roundingMode: 'ceil',
}).subtract({ nanoseconds: 1 }) // inclusive end

import { endOfMillisecondExcl, endOfMillisecondIncl } from 'temporal-utils'

inst2 = endOfMillisecondExcl(inst)
inst2 = endOfMillisecondIncl(inst)

End of microsecond:

inst2 = inst.round({ // sufficient for exclusive end
  smallestUnit: 'microsecond',
  roundingMode: 'ceil',
}).subtract({ nanoseconds: 1 }) // inclusive end

import { endOfMicrosecondExcl, endOfMicrosecondIncl } from 'temporal-utils'

inst2 = endOfMicrosecondExcl(inst)
inst2 = endOfMicrosecondIncl(inst)

Difference

You can use .since instead! but best to be consistent with .until!

roundingMode:

• 'halfExpand' - like Math.round() - the default
• 'trunc' - like Math.trunc()
• 'floor' - like Math.floor()
• 'ceil' - like Math.ceil()

Get it as a duration with multiple types of units.

dur = inst1.until(inst2, {
  largestUnit: 'hour',
  smallestUnit: 'millisecond',
  roundingIncrement: 1,
  roundingMode: 'halfExpand',
})

With hours:

hoursRounded = inst1.until(inst2, {
  largestUnit: 'hour',
  smallestUnit: 'hour',
  roundingMode: 'halfExpand', // or trunc/floor/ceil/etc
}).hours // 6

hoursExact = inst1.until(inst2, {
  largestUnit: 'hour',
}).total('hour') // 6.5

import { diffHours } from 'temporal-utils'

hoursRounded = diffHours(inst1, inst2, 'halfExpand')
hoursExact = diffHours(inst1, inst2)

With minutes:

minutesRounded = inst1.until(inst2, {
  largestUnit: 'hour',
  smallestUnit: 'hour',
  roundingMode: 'halfExpand', // or trunc/floor/ceil/etc
}).hours // 6

minutesExact = inst1.until(inst2, {
  largestUnit: 'hour',
}).total('hour') // 6.5

import { diffMinutes } from 'temporal-utils'

minutesRounded = diffMinutes(inst1, inst2, 'halfExpand')
minutesExact = diffMinutes(inst1, inst2)

With seconds:

secondsRounded = inst1.until(inst2, {
  largestUnit: 'second',
  smallestUnit: 'second',
  roundingMode: 'halfExpand', // or trunc/floor/ceil/etc
}).seconds // 6

secondsExact = inst1.until(inst2, {
  largestUnit: 'second',
}).total('second') // 6.5

import { diffSeconds } from 'temporal-utils'

secondsRounded = diffSeconds(inst1, inst2, 'halfExpand')
secondsExact = diffSeconds(inst1, inst2)

With milliseconds:

msRounded = inst1.until(inst2, {
  largestUnit: 'millisecond',
  smallestUnit: 'millisecond',
  roundingMode: 'halfExpand', // or trunc/floor/ceil/etc
}).milliseconds // 6

msExact = inst1.until(inst2, {
  largestUnit: 'millisecond',
}).total('millisecond') // 6.5

import { diffMilliseconds } from 'temporal-utils'

msRounded = diffMilliseconds(inst1, inst2, 'halfExpand')
msExact = diffMilliseconds(inst1, inst2)

With microseconds:

μsRounded = inst1.until(inst2, {
  largestUnit: 'microsecond',
  smallestUnit: 'microsecond',
  roundingMode: 'halfExpand', // or trunc/floor/ceil/etc
}).microseconds // 6

μsExact = inst1.until(inst2, {
  largestUnit: 'microsecond',
}).total('microsecond') // 6.5

import { diffMicroseconds } from 'temporal-utils'

μsRounded = diffMicroseconds(inst1, inst2, 'halfExpand')
μsExact = diffMicroseconds(inst1, inst2)

With nanoseconds:

nsRounded = inst1.until(inst2, {
  largestUnit: 'nanosecond',
  smallestUnit: 'nanosecond',
  roundingMode: 'halfExpand', // or trunc/floor/ceil/etc
  roundingIncrement: 10,
}).nanoseconds

nsUnrounded = inst2.epochNanoseconds - inst1.epochNanoseconds

import { diffNanoseconds } from 'temporal-utils'

nsRounded = diffNanoseconds(inst1, inst2, 'halfExpand')
nsUnrounded = diffNanoseconds(inst1, inst2)

Compare and Sort

inst1 = Temporal.Instant.from('2024-03-06T12:30Z')
inst2 = Temporal.Instant.from('2024-03-06T12:30Z')

Temporal.Instant.compare(inst1, inst2)
// -1 because inst1 < inst2

Temporal.Instant.compare(inst1, inst2)
// 1 because inst1 > inst2

Temporal.Instant.compare(inst1, inst1)
// 0 because inst1 = zdtPast

TODO: write about sorting!

Equality

epochNanoseconds must be identical.

inst1 = Temporal.Instant.from('2024-03-06T12:30Z')
inst2 = Temporal.Instant.from('2024-03-06T12:30Z')

inst1.equals(inst2) // false
inst1.equals(inst1) // true (of course it's equal to self)

Stringfy

inst.toString() // '2024-03-06T12:30Z'

For options, consult the spec.

ISO String

Localized String

For options, consult Intl.DateTimeFormat options.

Use the timeZone option!

It's possible to call directly on the object:

// current locale
inst.toLocaleString() // '3/6/2024, 3:58:45 PM EST'

// specific locale
inst.toLocaleString('fr') // '06/03/2024 15:59:31 UTC−5'

// specific locale + options
inst.toLocaleString('fr', { // 'mercredi 6 mars 2024'
  dateStyle: 'full',
})

However, it's much more performant to reuse a format:

dtf = new Intl.DateTimeFormat('fr', {
  dateStyle: 'full'
})

dtf.format(inst) // 'mercredi 6 mars 2024'

Convert

Legacy Date

Instant -> Date

legacyDate = new Date(inst.epochMilliseconds)

Date -> Instant

inst = legacyDate.toTemporalInstant()

ZonedDateTime

ZonedDateTime -> Instant

inst = zdt.toInstant()

PlainDateTime

Instant -> PlainDateTime

tzId = Temporal.Now.timeZoneId() // system time zone
tzId = 'America/Chicago' // OR a specific time zone

// ISO calendar
pdt = inst
  .toZonedDateTimeISO(tzId)
  .toPlainDateTime()

// specific calendar
pdt = inst
  .toZonedDateTime({ timeZone: tzId, calendar: 'gregory' })
  .toPlainDateTime()

PlainDateTime -> Instant

tzId = Temporal.Now.timeZoneId() // system time zone
tzId = 'America/Chicago' // OR a specific time zone

inst = pdt.toZonedDateTime(tzId).toInstant()

PlainDate

Instant -> PlainDate

tzId = Temporal.Now.timeZoneId() // system time zone
tzId = 'America/Chicago' // OR a specific time zone

// ISO calendar
pd = inst.toZonedDateTimeISO(tzId)
  .toPlainDate()

// specific calendar
pd = inst.toZonedDateTime({ timeZone: tzId, calendar: 'gregory' })
  .toPlainDate()

PlainDate -> Instant

tzId = Temporal.Now.timeZoneId() // system time zone
tzId = 'America/Chicago' // OR a specific time zone

inst = pd.toZonedDateTime({ timeZone: tzId })
  .toInstant()

PlainTime

Instant -> PlainTime

tzId = Temporal.Now.timeZoneId() // system time zone
tzId = 'America/Chicago' // OR a specific time zone

pt = inst.toZonedDateTimeISO(tzId).toPlainTime()

PlainTime -> Instant

tzId = Temporal.Now.timeZoneId() // system time zone
tzId = 'America/Chicago' // OR specific time zone

pdStr = '2022-02-01' // ISO calendar
pdStr = '2022-02-01[u-ca=gregory]' // OR specific calendar

inst = pt.toZonedDateTime({ plainDate: pdStr, timeZone: tzId })
  .toInstant()

PlainYearMonth

Instant -> PlainYearMonth

tzId = Temporal.Now.timeZoneId() // system time zone
tzId = 'America/Chicago' // OR a specific time zone

// ISO calendar
pym = inst.toZonedDateTimeISO(tzId)
  .toPlainYearMonth()

// specific calendar
pym = inst.toZonedDateTime({ timeZone: tzId, calendar: 'gregory' })
  .toPlainYearMonth()

PlainYearMonth -> Instant

tzId = Temporal.Now.timeZoneId() // system time zone
tzId = 'America/Chicago' // OR a specific time zone

pym.toPlainDate({ day: 13 }).toZonedDateTime({
  timeZone: tzId,
  plainTime: '04:00' // optional, defaults to 00:00
}).toInstant()

PlainMonthDay

Instant -> PlainMonthDay

tzId = Temporal.Now.timeZoneId() // current time zone
tzId = 'America/Chicago' // OR specific time zone

// ISO calendar
pmd = inst.toZonedDateTimeISO(tzId)
  .toPlainMonthDay()

// OR specific calendar
pmd = inst.toZonedDateTime({ timeZone: tzId, calendar: 'gregory' })
  .toPlainMonthDay()

PlainMonthDay -> Instant

tzId = Temporal.Now.timeZoneId() // system time zone
tzId = 'America/Chicago' // OR a specific time zone

inst = pmd.toPlainDate({ year: 2014 })
  .toZonedDateTime({ timeZone: tzId })
  .toInstant()