JS Temporal Reference
Temporal Objects
Temporal objects are the core part of the Temporal API
which aims to replace the old Date object.
Note
All Temporal objects are immutable, which helps prevent bugs
related to accidental modification of time values.
Temporal.Duration Methods
|
| Method | Description |
|---|
| compare() | Comparing two durations (returning -1, 0, or 1) |
| from() | Returns a new duration from an object or an ISO string |
| with() | Returns a new duration with specified field(s) modified |
| Arithmetic | |
|---|
| abs() | Returns a new duration with the absolute value of this duration |
| add() | Returns a new duration with a duration added to this duration |
| negated() | Returns a new duration with this duration negated |
| round() | Returns a new duration with this duration rounded |
| subtract() | Returns a new duration with a duration subtracted from this duration |
| Formatting | |
|---|
| total() | Returns a number representing the duration in a given unit |
| toJSON() | Returns an RFC 9557 format string for JSON serialization |
| toLocaleString() | Returns a language-sensitive representation of the time |
| toString() | Returns an RFC 9557 format string representation |
| valueOf() | Throws a TypeError (prevents temporals from being converted to primitives) |
Temporal.Duration Properties
|
| Property | Description |
|---|
| blank | Boolean true if the duration represents a zero duration |
| days | Days as an integer (1-31) |
| hours | Hours as an integer (0-23 |
| microseconds | Microseconds as an integer (0-999) |
| milliseconds | Milliseconds as an integer (0-999) |
| minutes | Minutes as an integer (0-59) |
| months | Months as an integer (1-12) |
| nanoseconds | Nanoseconds as an integer (0-999) |
| seconds | Seconds as an integer (0-59) |
| sign | 1 positive -1 negative |
| weeks | Weeks as an integer |
| years | Years as an integer |
Temporal.Now Methods
|
| Method | Description |
|---|
| instant() | Returns current time as a Temporal.Instant object |
| plainDateISO() | Returns current date as a Temporal.PlainDate object |
| plainDateTimeISO() | Returns current date and time as a Temporal.PlainDateTime object |
| plainTimeISO() | Returns current time as a Temporal.PlainTime object |
| timeZoneId | Returns system's time zone as a time zone id |
| zonedDateTimeISO() | Returns current date and time as a Temporal.ZonedDateTime object |
Temporal.Instant Methods
|
| Method | Description |
|---|
| from() | Returns a new Instant object from another object or a string |
| fromEpochMilliseconds() | Returns a new Instant object from a number of milliseconds |
| fromEpochNanoseconds() | Returns a new Instant object from a number of nanoseconds |
| toZonedDateTimeISO() | Returns a new ZonedDatetime object |
| Arithmetic | |
|---|
| add() | Returns a new Instant with a duration added |
| subtract() | Returns a new Instant with a duration subtracted |
| Comparison | |
|---|
| compare() | Returns -1, 0, or 1 from comparing two dates |
| equals() | Returns true if two Instant objects are identical |
| since() | Returns the difference since another date |
| until() | Returns the difference until another date |
| Formatting | |
|---|
| toJSON() | Returns an RFC 9557 format string for JSON serialization |
| toLocaleString() | Returns a language-sensitive representation of the date |
| toString() | Returns an RFC 9557 format string representation |
| valueOf() | Throws a TypeError (prevents temporals from being converted to primitives) |
Temporal ZonedDateTime Methods
|
| Method | Description |
|---|
| from() | Returns a new ZonedDateTime object from an object or a string |
getTimeZone
Transition() | Returns a ZonedDateTime object representing the closest
instant after or before this instant |
| startOfDay() | Returns a ZonedDateTime object representing the first instant of this date |
| toInstant() | Returns a new Instant object representing this date-time |
| toPlainDate() | Returns a new PlainDate object representing this date-time |
| toPlainDateTime() | Returns a new PlainDateTime object representing this date-time |
| toPlainTime() | Returns a new PlainTime object representing this date-time |
| with() | Returns a new ZonedDateTime with specified fields modified |
| withCalendar() | Returns a new ZonedDateTime with a different calendar system |
| withPlainTime() | Returns a new ZonedDateTime the time part replaced by a new time |
| withTimeZone() | Returns a new ZonedDateTime object representing this date-time in the new time zone |
| Arithmetic | |
|---|
| add() | Returns a new ZonedDateTime with a duration added |
| subtract() | Returns a new ZonedDateTime with a duration subtracted |
| round() | Returns a new ZonedDateTime rounded to a given unit |
| Comparison | |
|---|
| compare() | Returns -1, 0, or 1 from comparing two dates |
| equals() | Returns true if two ZonedDateTime objects are identical |
| since() | Returns the difference from another date |
| until() | Returns the difference until another date |
| Formatting | |
|---|
| toString() | Returns an ISO 8601 string representation |
| toJSON() | Returns an ISO 8601 string for JSON serialization |
| toLocaleString() | Returns a language-sensitive representation of the date |
| valueOf() | Throws a TypeError (prevents temporals from being converted to primitives) |
Temporal ZonedDateTime Properties
|
| Property | Description |
| calendarID | Calendar system identifier ("iso8601") |
| day | The day as an integer (1-31) |
| dayOfWeek | The day of the week as an integer (1 = Monday) |
| dayOfYear | The ordinal day of the year |
| daysInMonth | The total number of days in that month |
| daysInWeek | The total number of days in that week |
| daysInYear | The total number of days in that year |
| epochMilliseconds | Number of milliseconds since Unix epoch |
| epochNanoseconds | Number of nanoseconds since Unix epoch |
| era | The era name of the calendar, if applicable ("gregory") |
| eraYear | The year within the era, if applicable |
| hour | The hour as an integer (0-23) |
| hoursInDay | Hours in this day in this time zone(0-25) |
| inLeapYear | A boolean indicating if the date falls in a leap year |
| microsecond | The microsecond as an integer (0-999) |
| millisecond | The millisecond as an integer (0-999) |
| minute | The minute as an integer (0-59) |
| month | The month as an integer (1-12) |
| monthCode | A calendar-specific string code for the month ("M01") |
| monthsInYear | The total number of months in that year |
| nanosecond | The nanosecond as an integer (0-999) |
| offset | Offset used to interpret this instant (+HH:mm:ss.sssssssss) |
| offsetNanoseconds | Offset used to interpret this instant in nanoseconds |
| second | The second as an integer (0-59) |
| timeZoneId | Time zone identifier used to interpret this instant |
| weekOfYear | The week number within the year |
| year | The year as an integer |
| yearOfWeek | The year that the week belongs to |
Temporal Plain Objects
|
| Object | Description |
|---|
| Temporal.PlainDate | Calendar date only (2026-05-21) |
| Temporal.PlainTime | Time of day only (14:30:00) |
| Temporal.PlainMonthDay | Month and day only (05-01) |
| Temporal.PlainYearMonth | Year and month only (2026-05) |
Temporal.PlainDate Methods
|
| Method | Description |
|---|
| from() | Returns a new PlainDate object from another object or a string |
| toPlainDateTime() | Returns a new PlainDateTime object |
| toPlainMonthDay() | Returns a new PlainMonthDay object |
| toPlainYearMonth() | Returns a new PlainYearMonth object |
| toPlainMonthDay() | Returns a new PlainMonthDay object |
| toZonedDateTime() | Returns a new ZonedDatetime object |
| Arithmetic | |
|---|
| add() | Returns a new PlainDate with a duration added |
| subtract() | Returns a new PlainDate with a duration subtracted |
| with() | Returns a new PlainDate with specified fields modified |
| withCalendar() | Returns a new PlainDate with a different calendar system |
| Comparison | |
|---|
| compare() | Returns -1, 0, or 1 from comparing two dates |
| equals() | Returns true if two PlainDate objects are identical |
| since() | Returns the difference since another date |
| until() | Returns the difference until another date |
| Formatting | |
|---|
| toString() | Returns an RFC 9557 format string representation |
| toJSON() | Returns an RFC 9557 format string for JSON serialization |
| toLocaleString() | Returns a language-sensitive representation of the date |
| valueOf() | Throws a TypeError (prevents temporals from being converted to primitives) |
Temporal.PlainDate Properties
|
| Property | Description |
|---|
| calendarID | Calendar system identifier ("iso8601") |
| day | The day as an integer (1-31) |
| dayOfWeek | The day of the week as an integer (1 = Monday) |
| dayOfYear | The ordinal day of the year |
| daysInMonth | The total number of days in that month |
| daysInWeek | The total number of days in that week |
| daysInYear | The total number of days in that year |
| era | The era name of the calendar, if applicable |
| eraYear | The year within the era, if applicable |
| inLeapYear | A boolean indicating if the year is a leap year |
| month | The month as an integer (1-12) |
| monthCode | A string code for the month ("M01") |
| monthsInYear | The total number of months in that year |
| weekOfYear | The week number within the year |
| year | The year as an integer |
| yearOfWeek | The year that the week belongs to |
The Temporal.PlainYearMonth Object
The Temporal.PlainYearMonth has 10 properties of calendar date information.
|
| Property | Description |
| calendarID | Calendar system identifier ("iso8601") |
| daysInMonth | The total number of days in that month |
| daysInYear | The total number of days in that year |
| era | The era name of the calendar, if applicable ("gregory") |
| eraYear | The year within the era, if applicable |
| inLeapYear | A boolean indicating if the date falls in a leap year |
| month | The month as an integer (1-12) |
| monthCode | A calendar-specific string code for the month ("M01") |
| monthsInYear | The total number of months in that year |
| year | The year as an integer |
The Temporal.PlainMonthDay Object
The Temporal.PlainMonthDay has 3 properties of calendar date information.
|
| Property | Description |
| calendarID | Calendar system identifier ("iso8601") |
| day | The day as an integer (1-31) |
| monthCode | A calendar-specific string code for the month ("M01") |
Note
The Temporal.PlainMonthDay object does not have a month property.
Temporal PlainTime Methods
|
| Method | Description |
|---|
| from() | Returns a new PlainTime object from another object or a string |
| Arithmetic | |
|---|
| add() | Returns a new PlainTime with a duration added |
| subtract() | Returns a new PlainTime with a duration subtracted |
| round() | Returns a new PlainTime rounded to a given unit |
| with() | Returns a new PlainTime with specified fields modified |
| Comparison | |
|---|
| compare() | Returns -1, 0, or 1 from comparing two times |
| equals() | Returns true if two PlainTime objects are identical |
| since() | Returns the difference since another time |
| until() | Returns the difference until another time |
| Formatting | |
|---|
| toString() | Returns an RFC 9557 format string representation |
| toJSON() | Returns an RFC 9557 format string for JSON serialization |
| toLocaleString() | Returns a language-sensitive representation of the time |
| valueOf() | Throws a TypeError (prevents temporals from being converted to primitives) |
Temporal.PlainTime Properties
|
| Property | Description |
|---|
| hour | The hour as an integer (0-23 |
| microsecond | The microsecond as an integer (0-999) |
| millisecond | The millisecond as an integer (0-999) |
| minute | The minute as an integer (0-59) |
| nanosecond | The nanosecond as an integer (0-999) |
| second | The second as an integer (0-59) |
Temporal.PlainDateTime Methods
|
| Method | Description |
|---|
| from() | Returns a new PlainDateTime object from another object or a string |
| toPlainDate() | Returns a new PlainDate object |
| toPlainTime() | Returns a new PlainTime object |
| toZonedDateTime() | Returns a new ZonedDatetime object |
| with() | Returns a new PlainDateTime with specified fields modified |
| withCalendar() | Returns a new PlainDateTime with a different calendar system |
| withPlainTime() | Returns a new PlainDateTime the time part replaced by a new time |
| Arithmetic | |
|---|
| add() | Returns a new PlainDateTime with a duration added |
| subtract() | Returns a new PlainDateTime with a duration subtracted |
| round() | Returns a new PlainDateTime rounded to a given unit |
| Comparison | |
|---|
| compare() | Returns -1, 0, or 1 from comparing two dates |
| equals() | Returns true if two PlainDateTime objects are identical |
| since() | Returns the difference from another date |
| until() | Returns the difference until another date |
| Formatting | |
|---|
| toString() | Returns an RFC 9557 format string representation |
| toJSON() | Returns an RFC 9557 format string for JSON serialization |
| toLocaleString() | Returns a language-sensitive representation of the date |
| valueOf() | Throws a TypeError (prevents temporals from being converted to primitives) |
Temporal.PlainDateTime Properties
|
| Property | Description |
| calendarID | Calendar system identifier ("iso8601") |
| day | The day as an integer (1-31) |
| dayOfWeek | The day of the week as an integer (1 = Monday) |
| dayOfYear | The ordinal day of the year |
| daysInMonth | The total number of days in that month |
| daysInWeek | The total number of days in that week |
| daysInYear | The total number of days in that year |
| era | The era name of the calendar, if applicable ("gregory") |
| eraYear | The year within the era, if applicable |
| hour | The hour as an integer (0-23 |
| inLeapYear | A boolean indicating if the date falls in a leap year |
| microsecond | The microsecond as an integer (0-999) |
| millisecond | The millisecond as an integer (0-999) |
| minute | The minute as an integer (0-59) |
| month | The month as an integer (1-12) |
| monthCode | A calendar-specific string code for the month ("M01") |
| monthsInYear | The total number of months in that year |
| nanosecond | The nanosecond as an integer (0-999) |
| second | The second as an integer (0-59) |
| weekOfYear | The week number within the year |
| year | The year as an integer |
| yearOfWeek | The year that the week belongs to |
Temporal Arithmetic
|
| Method | Returns |
|---|
| temporal.add() |
New temporal representing a date moved forward by a duration |
| temporal.subtract() |
New temporal representing a date moved backward by a duration |
| temporal.round() |
New temporal rounded down to specified unit |
Temporal Comparison
| Method | Description |
|---|
| temporal.compare() |
Static method useful for sorting arrays of dates (returns -1, 0, or 1) |
| temporal.equals() |
Returns true if two dates (and their calendars) are identical |
| temporal.since() |
The duration between two temporal objects |
| temporal.until() |
The duration between two temporal objects |
