Dates and times with Temporal

Server-side JavaScript has the standard Temporal global for dates, times and durations. It follows the TC39 Temporal standard and uses the same date and time engine as Sessel's Temporal types. A value keeps its meaning when it passes between the two languages.

The two languages differ in one rule: JavaScript follows the standard and refuses to add years, months, weeks or days to an Instant, where Sessel counts a day as 24 hours.

When to use

Use Temporal whenever code works with calendar dates, clock times, time zones or lengths of time: a due date a month from today, the weekday of a booking, or the time until an event. Prefer it to the legacy Date object, which cannot hold a date without a time or a time without a date.

The types

Type Holds Example
Temporal.PlainDate a calendar date Temporal.PlainDate.from("2026-09-30")
Temporal.PlainTime a wall-clock time new Temporal.PlainTime(14, 30)
Temporal.PlainDateTime a date and a wall-clock time Temporal.PlainDateTime.from("2026-09-30T14:30")
Temporal.ZonedDateTime an exact moment in a named time zone Temporal.ZonedDateTime.from("2026-09-30T14:30[Europe/London]")
Temporal.Instant an exact moment, with no time zone Temporal.Instant.fromEpochMilliseconds(0)
Temporal.Duration a length of time Temporal.Duration.from({ days: 3, hours: 2 })
Temporal.PlainYearMonth a year and month new Temporal.PlainYearMonth(2026, 9)
Temporal.PlainMonthDay a month and day, such as a birthday Temporal.PlainMonthDay.from("09-30")

Temporal.Now gives the current moment: instant(), timeZoneId(), plainDateISO(), plainTimeISO(), plainDateTimeISO() and zonedDateTimeISO(). The server keeps time in UTC, so Temporal.Now.timeZoneId() is "UTC" and the …ISO() methods use UTC unless you pass a time zone.

Each type has the standard's constructor, from, toString, toJSON and toLocaleString, and each has the standard's compare, equals, add, subtract, until, since, with and conversions where the standard gives that type one. For example, Duration has no equals, Instant has no with, and PlainMonthDay has no compare or arithmetic. valueOf throws a TypeError, as the standard says, so compare values with compare or equals, not with < or ==.

Date.prototype.toTemporalInstant() turns a legacy Date into a Temporal.Instant.

Examples

A due date one month away, and its weekday:

const due = Temporal.PlainDate.from("2026-09-30").add({ months: 1 });
due.toString();  // "2026-10-30"
due.dayOfWeek;   // 5 (Friday; Monday is 1)

How long until an event, in a time zone:

const start = Temporal.ZonedDateTime.from("2026-09-30T09:00[Europe/London]");
const event = Temporal.ZonedDateTime.from("2026-10-02T18:30[Europe/London]");
start.until(event).toString();  // "PT57H30M"

A default that stores next Monday's date:

<div itemprop="default" itemscope itemtype="https://pagelove.org/JavaScript/Module">
  <script itemprop="source" type="module">
    export default () => {
      const today = Temporal.Now.plainDateISO();
      return today.add({ days: 8 - today.dayOfWeek });
    };
  </script>
</div>

Values that cross between Sessel and JavaScript

A temporal value keeps its type when it crosses between the languages:

From To Becomes
Sessel temporal value (in this, a context entry or a method argument) JavaScript the matching Temporal object
Temporal object returned or passed back Sessel the matching Sessel temporal value
Date returned or passed back Sessel the Temporal.Instant it stands for, as toTemporalInstant() gives
invalid Date (such as new Date(NaN)), or one outside the years -9999 to 9999, returned or passed back Sessel refused: the binding fails with return-type
Temporal object or Date as a search() criteria value the search the text Sessel gives the same value, such as --09-30 for a PlainMonthDay; an invalid Date, or one outside the years -9999 to 9999, throws a RangeError

A value stored in a document is written in its ISO 8601 form, such as 2026-10-30 or 2026-09-30T12:00:00Z. A PlainMonthDay is stored in the --09-30 form Sessel writes, although its toString() in JavaScript gives the standard's 09-30. Both forms read back.

Only the platform can make a Temporal object. An ordinary object made with Object.create(Temporal.PlainDate.prototype) is not a date: its getters throw a TypeError, and it is handed back as a plain map.

Where the server differs from a browser

The server uses the same engine as Sessel, and that engine does not have every part of the standard. Mostly, where it lacks something, the server leaves the member out or throws an error, rather than giving a different answer from a browser. The exceptions, which give a different answer, are listed first.

Durations are balanced

A Duration keeps its hours, minutes, seconds and sub-second fields as one length of time, so they are always balanced:

Years, months, weeks and days are kept as given. Apart from with(), the total length is always the same as a browser's.

A repeated hour

When clocks go back, an hour happens twice. ZonedDateTime.prototype.with resolves a time in that hour to the earlier offset. The standard keeps the value's own offset if it can, and so does a browser. For example, Temporal.ZonedDateTime.from("2026-10-25T01:30+00:00[Europe/London]").with({ minute: 45 }) gives 01:45+01:00 here and 01:45+00:00 in a browser. The bag's offset field is ignored, and a bag with only an offset throws a TypeError, where a browser applies it.

Locale text

toLocaleString(locales, options) formats with the ICU4X library and CLDR locale data. The standard leaves the exact text to each implementation, and this implementation differs from a browser in these ways:

A call with the type as this

The server cannot tell a function call from a construction when this is the Temporal type or a subclass of it, so Temporal.PlainDate.call(Temporal.PlainDate, 2026, 1, 2) makes a date, where a browser throws a TypeError. Any other this is refused, and new works as it should.

When the check looks up a prototype through a Proxy, an error the Proxy throws reaches your code. A browser does not make that lookup.

Reference arguments are not kept

The PlainYearMonth constructor's fourth argument, a reference day, and the PlainMonthDay constructor's fourth argument, a reference year, are checked and then dropped. So new Temporal.PlainYearMonth(2026, 2, "iso8601", 5).equals(new Temporal.PlainYearMonth(2026, 2)) is true here and false in a browser.

Durations that are equal once balanced

Duration.compare gives 0 for two durations that are equal once balanced, such as P1YT60M and P1YT1H. A browser throws a RangeError for any pair with years, months or weeks that are not field-for-field equal.

An offset without a time zone

A ZonedDateTime string with a UTC offset in hours, or in hours and minutes, or Z, and no time zone annotation, such as Temporal.ZonedDateTime.from("2026-01-01T00:00+01:00"), "2026-01-01T00:00+05", "2026-01-01T00:00+0530" or "2026-01-01T00:00Z", makes a value whose time zone is that offset, or UTC for Z. A browser throws a RangeError, because the standard needs the […] time zone. An offset with seconds, such as +05:30:00, throws a RangeError here too.

Out-of-range values are refused

from(), with() and the conversions refuse a field out of range, as the standard's overflow: "reject" does. A browser's default is to clamp it:

overflow: "reject" is accepted and overflow: "constrain" throws. add and subtract are the other way round: they clamp the day to the month, as the standard's default does, so they accept "constrain" and throw on "reject".

Ranges

Strings

Not supported

These parts of the standard are not available. Using them throws, or the member is undefined:

Error cases

What happened Error
A string that is not a valid date, time or duration, or a field out of range, such as new Temporal.PlainDate(2026, 2, 30) RangeError
An unsupported option, calendar or relativeTo, or a value outside the ranges above, as listed RangeError
An argument of the wrong type, a property bag missing a required field, or a method called on something that is not the right Temporal type TypeError
An object where an Instant is expected, including a Temporal value other than a ZonedDateTime, which is read through its primitive value, when that value is a string that is not an instant RangeError
An object where an Instant is expected whose primitive value is not a string, such as { toString() { return 5 } } TypeError
A constructor called without new TypeError
valueOf, including through <, > or + TypeError
new Temporal.Instant(1000): the epoch needs a BigInt, such as 1000n TypeError

See also