Temporal.Instant Objects

A Temporal.Instant object is an Object referencing a fixed point in time with nanoseconds precision.

The Temporal.Instant Constructor

The Temporal.Instant constructor:

Temporal.Instant ( _epochNanoseconds_ )

This function performs the following steps when called:

1. If NewTarget is *undefined*, then 1. Throw a *TypeError* exception. 1. Let _epochNanoseconds_ be ? ToBigInt(_epochNanoseconds_). 1. If IsValidEpochNanoseconds(_epochNanoseconds_) is *false*, throw a *RangeError* exception. 1. Return ? CreateTemporalInstant(_epochNanoseconds_, NewTarget).

Properties of the Temporal.Instant Constructor

The value of the [[Prototype]] internal slot of the Temporal.Instant constructor is the intrinsic object %Function.prototype%.

The Temporal.Instant constructor has the following properties:

Temporal.Instant.prototype

The initial value of `Temporal.Instant.prototype` is %Temporal.Instant.prototype%.

This property has the attributes { [[Writable]]: *false*, [[Enumerable]]: *false*, [[Configurable]]: *false* }.

Temporal.Instant.from ( _item_ )

This function performs the following steps when called:

1. Return ? ToTemporalInstant(_item_).

Temporal.Instant.fromEpochMilliseconds ( _epochMilliseconds_ )

This function performs the following steps when called:

1. Set _epochMilliseconds_ to ? ToNumber(_epochMilliseconds_). 1. Set _epochMilliseconds_ to ? NumberToBigInt(_epochMilliseconds_). 1. Let _epochNanoseconds_ be _epochMilliseconds_ × ℤ(106). 1. If IsValidEpochNanoseconds(_epochNanoseconds_) is *false*, throw a *RangeError* exception. 1. Return ! CreateTemporalInstant(_epochNanoseconds_).

Temporal.Instant.fromEpochNanoseconds ( _epochNanoseconds_ )

This function performs the following steps when called:

1. Set _epochNanoseconds_ to ? ToBigInt(_epochNanoseconds_). 1. If IsValidEpochNanoseconds(_epochNanoseconds_) is *false*, throw a *RangeError* exception. 1. Return ! CreateTemporalInstant(_epochNanoseconds_).

Temporal.Instant.compare ( _one_, _two_ )

This function performs the following steps when called:

1. Set _one_ to ? ToTemporalInstant(_one_). 1. Set _two_ to ? ToTemporalInstant(_two_). 1. Return 𝔽(CompareEpochNanoseconds(_one_.[[EpochNanoseconds]], _two_.[[EpochNanoseconds]])).

Properties of the Temporal.Instant Prototype Object

The Temporal.Instant prototype object

Temporal.Instant.prototype.constructor

The initial value of `Temporal.Instant.prototype.constructor` is %Temporal.Instant%.

Temporal.Instant.prototype[ %Symbol.toStringTag% ]

The initial value of the %Symbol.toStringTag% property is the String value *"Temporal.Instant"*.

This property has the attributes { [[Writable]]: *false*, [[Enumerable]]: *false*, [[Configurable]]: *true* }.

get Temporal.Instant.prototype.epochMilliseconds

`Temporal.Instant.prototype.epochMilliseconds` is an accessor property whose set accessor function is *undefined*. Its get accessor function performs the following steps:

1. Let _instant_ be the *this* value. 1. Perform ? RequireInternalSlot(_instant_, [[InitializedTemporalInstant]]). 1. Let _ns_ be _instant_.[[EpochNanoseconds]]. 1. Let _ms_ be floor(ℝ(_ns_) / 106). 1. Return 𝔽(_ms_).

get Temporal.Instant.prototype.epochNanoseconds

`Temporal.Instant.prototype.epochNanoseconds` is an accessor property whose set accessor function is *undefined*. Its get accessor function performs the following steps:

1. Let _instant_ be the *this* value. 1. Perform ? RequireInternalSlot(_instant_, [[InitializedTemporalInstant]]). 1. Return _instant_.[[EpochNanoseconds]].

Temporal.Instant.prototype.add ( _temporalDurationLike_ )

This method performs the following steps when called:

1. Let _instant_ be the *this* value. 1. Perform ? RequireInternalSlot(_instant_, [[InitializedTemporalInstant]]). 1. Return ? AddDurationToInstant(~add~, _instant_, _temporalDurationLike_).

Temporal.Instant.prototype.subtract ( _temporalDurationLike_ )

This method performs the following steps when called:

1. Let _instant_ be the *this* value. 1. Perform ? RequireInternalSlot(_instant_, [[InitializedTemporalInstant]]). 1. Return ? AddDurationToInstant(~subtract~, _instant_, _temporalDurationLike_).

Temporal.Instant.prototype.until ( _other_ [ , _options_ ] )

This method performs the following steps when called:

1. Let _instant_ be the *this* value. 1. Perform ? RequireInternalSlot(_instant_, [[InitializedTemporalInstant]]). 1. Return ? DifferenceTemporalInstant(~until~, _instant_, _other_, _options_).

Temporal.Instant.prototype.since ( _other_ [ , _options_ ] )

This method performs the following steps when called:

1. Let _instant_ be the *this* value. 1. Perform ? RequireInternalSlot(_instant_, [[InitializedTemporalInstant]]). 1. Return ? DifferenceTemporalInstant(~since~, _instant_, _other_, _options_).

Temporal.Instant.prototype.round ( _roundTo_ )

This method performs the following steps when called:

1. Let _instant_ be the *this* value. 1. Perform ? RequireInternalSlot(_instant_, [[InitializedTemporalInstant]]). 1. If _roundTo_ is *undefined*, then 1. Throw a *TypeError* exception. 1. If _roundTo_ is a String, then 1. Let _paramString_ be _roundTo_. 1. Set _roundTo_ to OrdinaryObjectCreate(*null*). 1. Perform ! CreateDataPropertyOrThrow(_roundTo_, *"smallestUnit"*, _paramString_). 1. Else, 1. Set _roundTo_ to ? GetOptionsObject(_roundTo_). 1. NOTE: The following steps read options and perform independent validation in alphabetical order (GetRoundingIncrementOption reads *"roundingIncrement"* and GetRoundingModeOption reads *"roundingMode"*). 1. Let _roundingIncrement_ be ? GetRoundingIncrementOption(_roundTo_). 1. Let _roundingMode_ be ? GetRoundingModeOption(_roundTo_, ~half-expand~). 1. Let _smallestUnit_ be ? GetTemporalUnitValuedOption(_roundTo_, *"smallestUnit"*, ~time~, ~required~). 1. If _smallestUnit_ is ~hour~, then 1. Let _maximum_ be HoursPerDay. 1. Else if _smallestUnit_ is ~minute~, then 1. Let _maximum_ be MinutesPerHour × HoursPerDay. 1. Else if _smallestUnit_ is ~second~, then 1. Let _maximum_ be SecondsPerMinute × MinutesPerHour × HoursPerDay. 1. Else if _smallestUnit_ is ~millisecond~, then 1. Let _maximum_ be ℝ(msPerDay). 1. Else if _smallestUnit_ is ~microsecond~, then 1. Let _maximum_ be 103 × ℝ(msPerDay). 1. Else, 1. Assert: _smallestUnit_ is ~nanosecond~. 1. Let _maximum_ be nsPerDay. 1. Perform ? ValidateTemporalRoundingIncrement(_roundingIncrement_, _maximum_, *true*). 1. Let _roundedNs_ be RoundTemporalInstant(_instant_.[[EpochNanoseconds]], _roundingIncrement_, _smallestUnit_, _roundingMode_). 1. Return ! CreateTemporalInstant(_roundedNs_).

Temporal.Instant.prototype.equals ( _other_ )

This method performs the following steps when called:

1. Let _instant_ be the *this* value. 1. Perform ? RequireInternalSlot(_instant_, [[InitializedTemporalInstant]]). 1. Set _other_ to ? ToTemporalInstant(_other_). 1. If _instant_.[[EpochNanoseconds]] ≠ _other_.[[EpochNanoseconds]], return *false*. 1. Return *true*.

Temporal.Instant.prototype.toString ( [ _options_ ] )

This method performs the following steps when called:

1. Let _instant_ be the *this* value. 1. Perform ? RequireInternalSlot(_instant_, [[InitializedTemporalInstant]]). 1. Let _resolvedOptions_ be ? GetOptionsObject(_options_). 1. NOTE: The following steps read options and perform independent validation in alphabetical order (GetTemporalFractionalSecondDigitsOption reads *"fractionalSecondDigits"* and GetRoundingModeOption reads *"roundingMode"*). 1. Let _digits_ be ? GetTemporalFractionalSecondDigitsOption(_resolvedOptions_). 1. Let _roundingMode_ be ? GetRoundingModeOption(_resolvedOptions_, ~trunc~). 1. Let _smallestUnit_ be ? GetTemporalUnitValuedOption(_resolvedOptions_, *"smallestUnit"*, ~time~, ~unset~). 1. If _smallestUnit_ is ~hour~, throw a *RangeError* exception. 1. Let _timeZone_ be ? Get(_resolvedOptions_, *"timeZone"*). 1. If _timeZone_ is not *undefined*, then 1. Set _timeZone_ to ? ToTemporalTimeZoneIdentifier(_timeZone_). 1. Let _precision_ be ToSecondsStringPrecisionRecord(_smallestUnit_, _digits_). 1. Let _roundedNs_ be RoundTemporalInstant(_instant_.[[EpochNanoseconds]], _precision_.[[Increment]], _precision_.[[Unit]], _roundingMode_). 1. Let _roundedInstant_ be ! CreateTemporalInstant(_roundedNs_). 1. Return TemporalInstantToString(_roundedInstant_, _timeZone_, _precision_.[[Precision]]).

Temporal.Instant.prototype.toLocaleString ( [ _locales_ [ , _options_ ] ] )

An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement this method as specified in the ECMA-402 specification. If an ECMAScript implementation does not include the ECMA-402 API the following specification of this method is used.

The meanings of the optional parameters to this method are defined in the ECMA-402 specification; implementations that do not include ECMA-402 support must not use those parameter positions for anything else.

This method performs the following steps when called:

1. Let _instant_ be the *this* value. 1. Perform ? RequireInternalSlot(_instant_, [[InitializedTemporalInstant]]). 1. Return TemporalInstantToString(_instant_, *undefined*, ~auto~).

Temporal.Instant.prototype.toJSON ( )

This method performs the following steps when called:

1. Let _instant_ be the *this* value. 1. Perform ? RequireInternalSlot(_instant_, [[InitializedTemporalInstant]]). 1. Return TemporalInstantToString(_instant_, *undefined*, ~auto~).

Temporal.Instant.prototype.valueOf ( )

This method performs the following steps when called:

1. Throw a *TypeError* exception.

This method always throws, because in the absence of `valueOf()`, expressions with arithmetic operators such as `instant1 > instant2` would fall back to being equivalent to `instant1.toString() > instant2.toString()`. Lexicographical comparison of serialized strings might not seem obviously wrong, because the result would sometimes be correct. Implementations are encouraged to phrase the error message to point users to `Temporal.Instant.compare()`, `Temporal.Instant.prototype.equals()`, and/or `Temporal.Instant.prototype.toString()`.

Temporal.Instant.prototype.toZonedDateTimeISO ( _timeZone_ )

This method performs the following steps when called:

1. Let _instant_ be the *this* value. 1. Perform ? RequireInternalSlot(_instant_, [[InitializedTemporalInstant]]). 1. Set _timeZone_ to ? ToTemporalTimeZoneIdentifier(_timeZone_). 1. Return ! CreateTemporalZonedDateTime(_instant_.[[EpochNanoseconds]], _timeZone_, *"iso8601"*).

Properties of Temporal.Instant Instances

Temporal.Instant instances are ordinary objects that inherit properties from the %Temporal.Instant.prototype% intrinsic object. Temporal.Instant instances are initially created with the internal slots described in .

Internal Slot Description
[[InitializedTemporalInstant]] The only specified use of this slot is for distinguishing Temporal.Instant instances from other objects.
[[EpochNanoseconds]] A BigInt value representing the number of nanoseconds since the epoch.

Temporal.Instant range

The [[EpochNanoseconds]] internal slot of a Temporal.Instant object supports a range of exactly -100,000,000 to 100,000,000 days relative to midnight at the beginning of 1 January 1970 UTC, as in .

The exact moment of midnight at the beginning of 1 January 1970 UTC is represented by the value *0*ℤ.

The maximum value is ℤ(nsMaxInstant), where

nsMaxInstant = 108 × nsPerDay = 8.64 × 1021

where the number of nanoseconds per day is

nsPerDay = 106 × ℝ(msPerDay) = 8.64 × 1013

The minimum value is ℤ(nsMinInstant), where

nsMinInstant = -nsMaxInstant = -8.64 × 1021

Abstract Operations

IsValidEpochNanoseconds ( _epochNanoseconds_: a BigInt, ): a Boolean

description
It returns *true* if its argument is within the allowed range of nanoseconds since the epoch for a Temporal.Instant and Temporal.ZonedDateTime, and *false* otherwise.
1. If ℝ(_epochNanoseconds_) < nsMinInstant or ℝ(_epochNanoseconds_) > nsMaxInstant, then 1. Return *false*. 1. Return *true*.

CreateTemporalInstant ( _epochNanoseconds_: a BigInt, optional _newTarget_: a constructor, ): either a normal completion containing a Temporal.Instant or a throw completion

description
It creates a Temporal.Instant instance and fills the internal slots with valid values.
1. Assert: IsValidEpochNanoseconds(_epochNanoseconds_) is *true*. 1. If _newTarget_ is not present, set _newTarget_ to %Temporal.Instant%. 1. Let _object_ be ? OrdinaryCreateFromConstructor(_newTarget_, *"%Temporal.Instant.prototype%"*, « [[InitializedTemporalInstant]], [[EpochNanoseconds]] »). 1. Set _object_.[[EpochNanoseconds]] to _epochNanoseconds_. 1. Return _object_.

ToTemporalInstant ( _item_: an ECMAScript language value, ): either a normal completion containing a Temporal.Instant or a throw completion

description
Converts _item_ to a new Temporal.Instant instance if possible, and throws otherwise.
1. If _item_ is an Object, then 1. If _item_ has an [[InitializedTemporalInstant]] or [[InitializedTemporalZonedDateTime]] internal slot, then 1. Return ! CreateTemporalInstant(_item_.[[EpochNanoseconds]]). 1. NOTE: This use of ToPrimitive allows Instant-like objects to be converted. 1. Set _item_ to ? ToPrimitive(_item_, ~string~). 1. If _item_ is not a String, throw a *TypeError* exception. 1. Let _parsed_ be ? ParseISODateTime(_item_, « |TemporalInstantString| »). 1. Assert: Either _parsed_.[[TimeZone]].[[OffsetString]] is not ~empty~ or _parsed_.[[TimeZone]].[[Z]] is *true*, but not both. 1. If _parsed_.[[TimeZone]].[[Z]] is *true*, let _offsetNanoseconds_ be 0; otherwise, let _offsetNanoseconds_ be ! ParseDateTimeUTCOffset(_parsed_.[[TimeZone]].[[OffsetString]]). 1. If _parsed_.[[Time]] is ~start-of-day~, let _time_ be MidnightTimeRecord(); else let _time_ be _parsed_.[[Time]]. 1. Let _balanced_ be BalanceISODateTime(_parsed_.[[Year]], _parsed_.[[Month]], _parsed_.[[Day]], _time_.[[Hour]], _time_.[[Minute]], _time_.[[Second]], _time_.[[Millisecond]], _time_.[[Microsecond]], _time_.[[Nanosecond]] - _offsetNanoseconds_). 1. Perform ? CheckISODaysRange(_balanced_.[[ISODate]]). 1. Let _epochNanoseconds_ be GetUTCEpochNanoseconds(_balanced_). 1. If IsValidEpochNanoseconds(_epochNanoseconds_) is *false*, throw a *RangeError* exception. 1. Return ! CreateTemporalInstant(_epochNanoseconds_).

CompareEpochNanoseconds ( _epochNanosecondsOne_: a BigInt, _epochNanosecondsTwo_: a BigInt, ): either -1, 0, or 1

description
1. If _epochNanosecondsOne_ > _epochNanosecondsTwo_, return 1. 1. If _epochNanosecondsOne_ < _epochNanosecondsTwo_, return -1. 1. Return 0.

AddInstant ( _epochNanoseconds_: a BigInt value, _timeDuration_: a time duration, ): either a normal completion containing a BigInt or a throw completion

description
It adds a duration to a number of nanoseconds since the epoch.
1. Let _result_ be AddTimeDurationToEpochNanoseconds(_timeDuration_, _epochNanoseconds_). 1. If IsValidEpochNanoseconds(_result_) is *false*, throw a *RangeError* exception. 1. Return _result_.

DifferenceInstant ( _ns1_: a BigInt, _ns2_: a BigInt, _roundingIncrement_: a positive integer, _smallestUnit_: a time unit, _roundingMode_: a rounding mode, ): an Internal Duration Record

description
It computes the difference between two exact times _ns1_ and _ns2_ expressed in nanoseconds since the epoch, and rounds the result according to the parameters _roundingIncrement_, _smallestUnit_, and _roundingMode_.
1. Let _timeDuration_ be TimeDurationFromEpochNanosecondsDifference(_ns2_, _ns1_). 1. Set _timeDuration_ to ! RoundTimeDuration(_timeDuration_, _roundingIncrement_, _smallestUnit_, _roundingMode_). 1. Return CombineDateAndTimeDuration(ZeroDateDuration(), _timeDuration_).

RoundTemporalInstant ( _ns_: a BigInt, _increment_: a positive integer, _unit_: a time unit, _roundingMode_: a rounding mode, ): a BigInt

description
It rounds a number of nanoseconds _ns_ since the epoch to the given rounding increment.
1. Let _unitLength_ be the value in the "Length in Nanoseconds" column of the row of whose "Value" column contains _unit_. 1. Let _incrementNs_ be _increment_ × _unitLength_. 1. Return ℤ(RoundNumberToIncrementAsIfPositive(ℝ(_ns_), _incrementNs_, _roundingMode_)).

TemporalInstantToString ( _instant_: a Temporal.Instant, _timeZone_: an available time zone identifier or *undefined*, _precision_: an integer in the inclusive interval from 0 to 9, ~minute~, or ~auto~, ): a String

description
It formats _instant_ as an ISO 8601 / RFC 9557 string, to the precision specified by _precision_, using the UTC offset of _timeZone_, or `Z` if _timeZone_ is *undefined*.
1. Let _outputTimeZone_ be _timeZone_. 1. If _outputTimeZone_ is *undefined*, set _outputTimeZone_ to *"UTC"*. 1. Let _epochNs_ be _instant_.[[EpochNanoseconds]]. 1. Let _isoDateTime_ be GetISODateTimeFor(_outputTimeZone_, _epochNs_). 1. Let _dateTimeString_ be ISODateTimeToString(_isoDateTime_, *"iso8601"*, _precision_, ~never~). 1. If _timeZone_ is *undefined*, then 1. Let _timeZoneString_ be *"Z"*. 1. Else, 1. Let _offsetNanoseconds_ be GetOffsetNanosecondsFor(_outputTimeZone_, _epochNs_). 1. Let _timeZoneString_ be FormatDateTimeUTCOffsetRounded(_offsetNanoseconds_). 1. Return the string-concatenation of _dateTimeString_ and _timeZoneString_.

DifferenceTemporalInstant ( _operation_: ~since~ or ~until~, _instant_: a Temporal.Instant, _other_: an ECMAScript language value, _options_: an ECMAScript language value, ): either a normal completion containing a Temporal.Duration or a throw completion

description
It computes the difference between the two times represented by _instant_ and _other_, optionally rounds it, and returns it as a Temporal.Duration object.
1. Set _other_ to ? ToTemporalInstant(_other_). 1. Let _resolvedOptions_ be ? GetOptionsObject(_options_). 1. Let _settings_ be ? GetDifferenceSettings(_operation_, _resolvedOptions_, ~time~, « », ~nanosecond~, ~second~). 1. Let _internalDuration_ be DifferenceInstant(_instant_.[[EpochNanoseconds]], _other_.[[EpochNanoseconds]], _settings_.[[RoundingIncrement]], _settings_.[[SmallestUnit]], _settings_.[[RoundingMode]]). 1. Let _result_ be ! TemporalDurationFromInternal(_internalDuration_, _settings_.[[LargestUnit]]). 1. If _operation_ is ~since~, set _result_ to CreateNegatedTemporalDuration(_result_). 1. Return _result_.

AddDurationToInstant ( _operation_: ~add~ or ~subtract~, _instant_: a Temporal.Instant, _temporalDurationLike_: an ECMAScript language value, ): either a normal completion containing a Temporal.Instant or a throw completion

description
It adds/subtracts _temporalDurationLike_ to/from _instant_.
1. Let _duration_ be ? ToTemporalDuration(_temporalDurationLike_). 1. If _operation_ is ~subtract~, set _duration_ to CreateNegatedTemporalDuration(_duration_). 1. Let _largestUnit_ be DefaultTemporalLargestUnit(_duration_). 1. If TemporalUnitCategory(_largestUnit_) is ~date~, throw a *RangeError* exception. 1. Let _internalDuration_ be ToInternalDurationRecordWith24HourDays(_duration_). 1. Let _ns_ be ? AddInstant(_instant_.[[EpochNanoseconds]], _internalDuration_.[[Time]]). 1. Return ! CreateTemporalInstant(_ns_).