TheTemporal.Instant object represents a unique point in time, with nanosecond precision. It is fundamentally represented as the number of nanoseconds since the Unix epoch (midnight at the beginning of January 1, 1970, UTC), without any time zone or calendar system.

Description

Temporal.Instant is semantically the same asDate. They both encapsulate a single point in time, butTemporal.Instant is more precise because it stores nanoseconds rather than milliseconds.Temporal.Instant also avoids pitfalls ofDate because it does not assume any calendar or time zone information—if you want to read any date or time information such as year or month, you need to convert it to aTemporal.ZonedDateTime first, usingtoZonedDateTimeISO().

You can convert fromDate toTemporal.Instant using theDate.prototype.toTemporalInstant() method, which should be preferred over other methods such asTemporal.Instant.fromEpochMilliseconds() because the former involves less user code and may be more optimized. You can also convert fromTemporal.Instant toDate using its epoch milliseconds, such asnew Date(instant.epochMilliseconds).

RFC 9557 format

Instant objects can be serialized and parsed using theRFC 9557 format, an extension to theISO 8601 / RFC 3339 format. The string has the following form (spaces are only for readability and should not be present in the actual string):

YYYY-MM-DD T HH:mm:ss.sssssssss Z/±HH:mm

YYYY

Either a four-digit number, or a six-digit number with a+ or- sign.

MM

A two-digit number from01 to12.

DD

A two-digit number from01 to31. TheYYYY,MM, andDD components can be separated by- or nothing.

T

The date-time separator, which can beT,t, or a space.

HH

A two-digit number from00 to23.

mmOptional

A two-digit number from00 to59. Defaults to00.

ss.sssssssssOptional

A two-digit number from00 to59. May optionally be followed by a. or, and one to nine digits. Defaults to00. TheHH,mm, andss components can be separated by: or nothing. You can omit either justss or bothss andmm, so the time can be one of three forms:HH,HH:mm, orHH:mm:ss.sssssssss.

Z/±HH:mm

Either the UTC designatorZ orz, or an offset from UTC in the form+ or- followed by the same format as the time component. Note that subminute precision (:ss.sssssssss) may be unsupported by other systems, and is accepted but never output. If an offset is provided, the time is interpreted in the specified offset.

As an input, you may optionally include the time zone identifier and calendar, in the same format asZonedDateTime, but they will be ignored. Other annotations in the[key=value] format are also ignored, and they must not have the critical flag.

When serializing, you can configure the fractional second digits and offset.

Constructor

Temporal.Instant()Experimental

Creates a newTemporal.Instant object by directly supplying the underlying data.

Static methods

Temporal.Instant.compare()

Returns a number (-1, 0, or 1) indicating whether the first instant comes before, is the same as, or comes after the second instant. Equivalent to comparing theepochNanoseconds of the two instants.

Temporal.Instant.from()

Creates a newTemporal.Instant object from anotherTemporal.Instant object, or anRFC 9557 string.

Temporal.Instant.fromEpochMilliseconds()

Creates a newTemporal.Instant object from the number of milliseconds since the Unix epoch (midnight at the beginning of January 1, 1970, UTC).

Temporal.Instant.fromEpochNanoseconds()

Creates a newTemporal.Instant object from the number of nanoseconds since the Unix epoch (midnight at the beginning of January 1, 1970, UTC).

Instance properties

These properties are defined onTemporal.Instant.prototype and shared by allTemporal.Instant instances.

Temporal.Instant.prototype.constructor

The constructor function that created the instance object. ForTemporal.Instant instances, the initial value is theTemporal.Instant() constructor.

Temporal.Instant.prototype.epochMilliseconds

Returns an integer representing the number of milliseconds elapsed since the Unix epoch (midnight at the beginning of January 1, 1970, UTC) to this instant. Equivalent to dividingepochNanoseconds by1e6 and flooring it.

Temporal.Instant.prototype.epochNanoseconds

Returns aBigInt representing the number of nanoseconds since the Unix epoch (midnight at the beginning of January 1, 1970, UTC) to this instant.

Temporal.Instant.prototype[Symbol.toStringTag]

The initial value of the[Symbol.toStringTag] property is the string"Temporal.Instant". This property is used inObject.prototype.toString().

Instance methods

Temporal.Instant.prototype.add()

Returns a newTemporal.Instant object representing this instant moved forward by a given duration (in a form convertible byTemporal.Duration.from()).

Temporal.Instant.prototype.equals()

Returnstrue if this instant is equivalent in value to another instant (in a form convertible byTemporal.Instant.from()), andfalse otherwise. They are compared by their epoch nanoseconds. Equivalent toTemporal.Instant.compare(this, other) === 0.

Temporal.Instant.prototype.round()

Returns a newTemporal.Instant object representing this instant rounded to the given unit.

Temporal.Instant.prototype.since()

Returns a newTemporal.Duration object representing the duration from another instant (in a form convertible byTemporal.Instant.from()) to this instant. The duration is positive if the other instant is before this instant, and negative if after.

Temporal.Instant.prototype.subtract()

Returns a newTemporal.Instant object representing this instant moved backward by a given duration (in a form convertible byTemporal.Duration.from()).

Temporal.Instant.prototype.toJSON()

Returns a string representing this instant in the sameRFC 9557 format as callingtoString(). Intended to be implicitly called byJSON.stringify().

Temporal.Instant.prototype.toLocaleString()

Returns a string with a language-sensitive representation of this instant. In implementations withIntl.DateTimeFormat API support, this method delegates toIntl.DateTimeFormat.

Temporal.Instant.prototype.toString()

Returns a string representing this instant in theRFC 9557 format using the specified time zone.

Temporal.Instant.prototype.toZonedDateTimeISO()

Returns a newTemporal.ZonedDateTime object representing this instant in the specified time zone using the ISO 8601 calendar system.

Temporal.Instant.prototype.until()

Returns a newTemporal.Duration object representing the duration from this instant to another instant (in a form convertible byTemporal.Instant.from()). The duration is positive if the other instant is after this instant, and negative if before.

Temporal.Instant.prototype.valueOf()

Throws aTypeError, which preventsTemporal.Instant instances from beingimplicitly converted to primitives when used in arithmetic or comparison operations.

Specifications

Browser compatibility

See also

• Temporal
• Temporal.Duration
• Temporal.ZonedDateTime