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:
Temporal.Duration.from({ minutes: 90 })isPT1H30M, where a browser keepsPT90M- its
minutesis30, where a browser gives90 Temporal.Duration.from({ milliseconds: 5000 }).millisecondsis0, where a browser gives5000. Both write the value asPT5SInstant.prototype.untilandsinceanswer in hours, minutes and seconds, such asPT3H30M, where a browser answers in seconds, such asPT12600Swith()starts from the balanced value, soTemporal.Duration.from({ minutes: 90 }).with({ minutes: 45 })isPT1H45M, where a browser givesPT45M
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:
- without a
dateStyleortimeStyle, it uses the medium style, such asMar 23, 2026, where a browser gives3/23/2026 dateStyleandtimeStyleare the only options; any other option throws aRangeError"full"is treated as"long"- when both are given,
timeStyleis ignored and the time is written with seconds - a
dateStyleon aPlainTime, or atimeStyleon aPlainDate, is ignored, where a browser throws aTypeError - a
ZonedDateTimeis written without its time zone name - a
PlainYearMonthis written as the first day of its month and aPlainMonthDayin the year 2000, where a browser throws aRangeError - a
Durationgives its ISO 8601 form, such asPT1H, where a browser gives1 hr - with no locale, it uses
en-US - spacing can differ, such as the narrow space before
PM
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:
Temporal.PlainDate.from({ year: 2026, month: 2, day: 30 })throws, where a browser gives2026-02-28ZonedDateTime.prototype.with({ millisecond: 5000 })throws, where a browser gives.999Temporal.PlainMonthDay.from("02-29").toPlainDate({ year: 2027 })throws, where a browser gives2027-02-28PlainMonthDayfromandwithcheck the day against ayearin the bag, and throw where a browser clamps
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
- Years run from -9999 to 9999. The standard allows about 271,821 years either side of 1970, so a value past 9999 throws here. That includes a returned
Datemore than 9999 years after year 0, which fails withreturn-type. - A
PlainMonthDaybag'syearmay be any whole number up to 2⁵³ - 1 in size. It only decides whether 29 February exists, as in a browser. - A duration's years, months, weeks and days must each be between -2,147,483,648 and 2,147,483,647, a signed 32-bit integer. The standard allows up to 4,294,967,295 for years, months and weeks, and as many days as fit under its 2⁵³-second limit, about 104,249,991,374. So
Temporal.Duration.from({ years: 2 ** 31 })andTemporal.Duration.from({ days: 2 ** 31 })throw here. - A duration's days and time together must be under 2⁵³ seconds, as the standard requires.
- A duration field passed from JavaScript must be a whole number. Other fields are truncated toward zero, as the standard does, so
new Temporal.PlainDate(2026.9, 1, 2)is2026-01-02. - Every field passed from JavaScript must be no larger than 2⁵³ - 1. A browser accepts larger ones, so
Temporal.Duration.from({ nanoseconds: 2 ** 53 })throws here.
Strings
- A duration may have a fraction only in its seconds:
PT1.5Hthrows, where a browser reads it asPT1H30M. - A time zone argument must be a name, such as
Europe/LondonorUTC. An offset given as a time zone, as intoZonedDateTime("+05:00"), throws, where a browser accepts it. An offset in a string's[…]time zone annotation, such as[+05:30], is accepted. - A string that names a calendar other than ISO 8601, with
[u-ca=…], throws. So does a property-bagcalendarother than"iso8601", any ISO 8601 date or time string, or a Temporal value that has a calendar. Acalendarthat is not a string or a Temporal value that has a calendar, such as5or aTemporal.Duration, throws aTypeError. Only the first[u-ca=…]annotation counts, as in a browser. AnInstantorPlainTimestring ignores a calendar annotation, as in a browser, because neither type has a calendar.
Not supported
These parts of the standard are not available. Using them throws, or the member is undefined:
- calendars other than ISO 8601: a calendar other than ISO 8601 throws a
RangeError(see Strings for what a property bag accepts), and there is nowithCalendar,eraoreraYear - rounding: there is no
roundmethod, and thesmallestUnit,largestUnit,roundingIncrement,roundingModeandfractionalSecondDigitsoptions throw aRangeError - the
toStringoptionscalendarName,offset,timeZoneNameandtimeZonethrow aRangeError - the
disambiguationandoffsetoptions throw aRangeError Duration.prototype.totalandDuration.comparewithrelativeTothrow aRangeError, so neither can resolve years, months or weeks, except that equal durations always compare equal- a
ZonedDateTimeproperty bag throws aTypeErrorwherever the server reads one: infrom,compare,equals,untilandsince. Pass a string or aZonedDateTimeinstead ZonedDateTimehas nohoursInDay,offsetNanoseconds,startOfDay,withPlainTimeorgetTimeZoneTransitionPlainDateTimehas nowithPlainTimeReflect.constructwith a new target that is not the Temporal type or a subclass of it throws aTypeError
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 |