Temporal

JavaScript's old Date object tries to do every time job alone. One Date is used for all of these:

• an exact moment, like "when this error happened"
• a calendar date, like a birthday
• a clock time, like "the shop opens at 09:00"
• text for people to read

That makes mistakes easy. A Date can be changed by mistake. Its months start at 0. It reads some date text in surprising ways. And clock changes for summer time can break its math. The Date & time lesson shows each of these problems.

Temporal is the newer way to work with dates and times in JavaScript. It gives each job its own type. A type here is a kind of value, built for one job.

Temporal is new, and browsers are adding it one by one. Today these browsers have it:

• Chrome 144 and later, and Edge 144 and later
• Firefox 139 and later
• Safari only in its preview version, and Safari on iPhone and iPad not at all

When this page opens, it checks whether your browser has Temporal. If it does, the live cards run real Temporal code. If it doesn't, they show example output instead and say so. Our tests check that example output in Node.js, using its --harmony-temporal setting, which turns Temporal on.

1const hasTemporal = typeof globalThis.Temporal !== "undefined";2if (hasTemporal) {3  Temporal.Now.plainDateISO().toString();4}

Try it now. Put each real situation with the Temporal type it needs. Read the explanation after each card.

Temporal.Now & Instant

Temporal.Now gives you the current time. It has a few methods:

• Temporal.Now.instant() gives the exact moment right now.
• Temporal.Now.plainDateISO() gives today's date.

The current time changes every second, so the examples in this lesson use fixed times instead. That way the output is always the same, and our tests can check it.

An Instant is one exact moment. It means the same moment everywhere on Earth. Use it for:

• lines in a server log
• times saved in a database
• the moment some saved data runs out

1const instant = Temporal.Instant.from("2024-03-10T06:30:00Z");2console.log(instant.toString());3console.log(instant.epochMilliseconds);

Line 1 makes an Instant from date text. Line 2 prints it as text again. The Z at the end means UTC, the world's shared base time.

Line 3 prints epochMilliseconds. That is the number of milliseconds since the start of 1970 in UTC. It is the same kind of number that the old Date.now() gives. So an Instant is an easy way to move from old Date code to Temporal.

Three types start with the word "Plain". "Plain" means the value has no time zone. A time zone is a place's clock rules, like "New York time".

• PlainDate is a date, like a birthday.
• PlainTime is a clock time, like an opening time.
• PlainDateTime is a date and a clock time together, like "January 31 at 09:30", before anyone says where.

1const date = Temporal.PlainDate.from("2024-01-31");2const time = Temporal.PlainTime.from("09:30:15");3const dateTime = Temporal.PlainDateTime.from("2024-01-31T09:30");4console.log(date.toString());5console.log(date.month);6console.log(time.toString());7console.log(dateTime.toString());

Lines 1 to 3 make one value of each type. Lines 4 to 7 print them.

Months start at 1, like on a real calendar. Temporal.PlainDate.from("2024-01-31").month is 1 for January, not 0.

Temporal values are also immutable. That means they never change after they are made. Methods like add and with don't change the date you call them on. They make a new date and give it back.

1const original = Temporal.PlainDate.from("2024-01-31");Run2const later = original.add({ months: 1 });3const firstDay = original.with({ day: 1 });4console.log(later.toString());5console.log(firstDay.toString());6console.log(original.toString());7console.log(Temporal.PlainDate.compare(original, later));8console.log(original.equals(Temporal.PlainDate.from("2024-01-31")));

January has 31 days, but February doesn't. So what should "January 31 plus one month" be? Temporal lets you choose with the overflow option:

• "constrain" (the default) moves the date back to the last real day of the month.
• "reject" stops with an error instead.

1const date = Temporal.PlainDate.from("2024-01-31");2console.log(date.add({ months: 1 }).toString());3try {4  console.log(date.add({ months: 1 }, { overflow: "reject" }).toString());5} catch (error) {6  console.log(error.name);7}

Line 2 uses the default, so it prints the last day of February 2024. Line 4 asks for reject, so add throws an error. Line 6 prints the error's name, RangeError. Use reject when a day that doesn't exist should count as a mistake in the user's input.

1const date = Temporal.PlainDate.from("2024-05-12");2const appointment = date.with({ day: 20 });3console.log(appointment.toString());4console.log(date.toString());

with makes a new date with only the part you name changed. Here it changes the day to 20. Line 4 prints the first date again, and it is still May 12.

1const dates = ["2024-05-12", "2023-12-01", "2024-01-31"]2  .map((value) => Temporal.PlainDate.from(value));3dates.sort((left, right) => Temporal.PlainDate.compare(left, right));4console.log(dates.map((date) => date.toString()).join(", "));

Lines 1 and 2 turn three date texts into PlainDate values. Line 3 sorts them. Temporal.PlainDate.compare takes two dates. It gives -1 if the first is earlier, 0 if they are the same, and 1 if the first is later. Line 3 gives sort a small arrow function that calls compare on each pair of dates. Line 4 prints the dates in order.

Date texts like these happen to sort in the right order too. But compare says clearly that you are comparing dates.

PlainYearMonth & PlainMonthDay

Some dates are missing a part on purpose:

• A credit card's end date has a year and a month, but no day.
• A yearly birthday reminder has a month and a day, but no year.

Temporal has a type for each. So you don't have to make up a fake day or a fake year to fill a full date.

1const expiry = Temporal.PlainYearMonth.from("2024-02");2const leapBirthday = Temporal.PlainMonthDay.from("--02-29");3console.log(expiry.toString());4console.log(leapBirthday.toString());

Line 1 makes February 2024. Line 2 makes February 29 with no year. The two dashes in "--02-29" stand where the year would be.

An offset is how far a clock is from UTC, like -05:00 (five hours behind UTC). A time zone is more than one offset. It is a named set of rules, like America/New_York. The rules say:

• which offset the place uses on each day
• when the clocks move for summer time
• how those rules changed in past years

Many places move their clocks forward one hour in spring and back one hour in autumn. This is called daylight saving time, or DST.

A ZonedDateTime keeps three things together:

• one exact moment
• the date and clock time people see in that place
• the time zone's rules

1const beforeSpringForward = Temporal.ZonedDateTime.from(Run2  "2024-03-10T01:30-05:00[America/New_York]",3);4console.log(beforeSpringForward.toString());5console.log(beforeSpringForward.add({ hours: 24 }).toString());6console.log(beforeSpringForward.add({ days: 1 }).toString());

In New York on March 10, 2024, the clocks jumped from 01:59:59 straight to 03:00:00. India doesn't use DST today. But an Indian app with users abroad still has to handle clock changes like this one.

Because of the jump, adding { hours: 24 } and adding { days: 1 } give different clock times in the example:

• { hours: 24 } adds 24 real hours.
• { days: 1 } moves to the same clock time on the next day.

In autumn, the clocks go back one hour. On November 3, 2024, New York saw 01:30 twice: once before the clocks went back, and once after. So "01:30 on November 3" could mean two different moments.

Disambiguation is how Temporal picks one. You tell it with the disambiguation option:

• "earlier" picks the first 01:30.
• "later" picks the second 01:30.
• "reject" throws an error, so your app can ask the user to choose.

1const localMeeting = "2024-11-03T01:30[America/New_York]";2const earlier = Temporal.ZonedDateTime.from(localMeeting, {3  disambiguation: "earlier",4});5const later = Temporal.ZonedDateTime.from(localMeeting, {6  disambiguation: "later",7});8console.log(earlier.toString());9console.log(later.toString());

Line 1 is the meeting as text: the date, the clock time, and the time zone name in square brackets. This text format is a standard called RFC 9557. Lines 2 to 7 read the text twice, once with each choice:

• The first output picks the earlier 01:30, with offset -04:00.
• The second output picks the later 01:30, with offset -05:00.

Both show 01:30 on the clock. But they are two different moments, one hour apart.

1const date = Temporal.PlainDate.from("2024-05-12");2const time = Temporal.PlainTime.from("09:30");3const meeting = date.toPlainDateTime(time).toZonedDateTime("America/New_York");4console.log(meeting.toString());5console.log(meeting.toInstant().toString());

A form can ask for a date and a time without a place. Lines 1 and 2 hold those two answers. When the user picks a place, line 3 joins the date and time and adds the time zone with toZonedDateTime. Line 5 calls toInstant to get the exact moment, ready to save or send.

A Duration is a length of time, like "3 days" or "1 hour 30 minutes". It is not a point in time. You can get one in two ways:

• Measure between two values with until or since.
• Build one yourself with Temporal.Duration.from.

You can also round a Duration, or turn it into one unit, like "90 minutes". You tell Temporal which unit you want.

1const start = Temporal.PlainDate.from("2024-02-28");2const end = Temporal.PlainDate.from("2024-03-02");3const between = start.until(end);4const timer = Temporal.Duration.from({ hours: 1, minutes: 30 });5console.log(between.toString());6console.log(between.days);7console.log(timer.toString());8console.log(timer.total({ unit: "minutes" }));

1const start = Temporal.PlainDate.from("2024-02-28");Run2const end = Temporal.PlainDate.from("2024-03-02");3const between = start.until(end);4const timer = Temporal.Duration.from({ hours: 1, minutes: 30 });5console.log(between.toString());6console.log(between.days);7console.log(timer.toString());8console.log(timer.total({ unit: "minutes" }));

1const duration = Temporal.Duration.from({ minutes: 95 });2console.log(duration.round({3  largestUnit: "hours",4  smallestUnit: "hours",5  roundingMode: "halfExpand",6}).toString());7const time = Temporal.PlainTime.from("09:40");8console.log(time.round({ smallestUnit: "hour", roundingMode: "halfExpand" }).toString());

Lines 2 to 6 round 95 minutes to whole hours. halfExpand is the rounding you learned at school: halfway or more rounds up. So 95 minutes (1 hour 35 minutes) becomes 2 hours, printed as PT2H. Line 8 uses the same rule on the clock time 09:40, which becomes 10:00. This helps when you show times in one-hour slots.

1const start = Temporal.PlainDate.from("2024-01-31");2const end = Temporal.PlainDate.from("2024-03-31");3console.log(start.until(end, { largestUnit: "days" }).toString());4console.log(start.until(end, { largestUnit: "months" }).toString());5console.log(end.since(start, { largestUnit: "months" }).toString());

largestUnit sets the biggest unit the answer may use. The same two dates give two answers:

• With "days", line 3 prints P60D: 60 days.
• With "months", line 4 prints P2M: 2 months.

Line 5 uses since, which measures from the other end, and also prints P2M. Pick the unit your app shows to its users.

Calendars

A calendar is a system for naming days: which year, which month, which day. Most of the world uses the Gregorian calendar. Others include the Hebrew and Japanese calendars.

Temporal uses the ISO calendar by default. That is the Gregorian calendar, written the way computers usually write it, like 2024-05-01. But a Temporal date can also use another calendar. The day stays the same; only its name changes.

1const isoDate = Temporal.PlainDate.from("2024-05-01");2const japaneseDate = isoDate.withCalendar("japanese");3console.log(japaneseDate.toString());

Line 2 switches the date to the Japanese calendar. Line 3 prints it. The text in square brackets, [u-ca=japanese], is a note that says which calendar the date uses.

Japanese era names, and how dates look in other languages, depend on data inside each browser. So this lesson only shows the output our tests check: the date with its calendar note.

A calendar and a time zone answer different questions:

• A calendar answers: "Which year, month, and day is this?"
• A time zone answers: "What does the clock show in this place at this moment?"

Switching to the Japanese calendar doesn't move the moment, and it doesn't change the time zone.

To move old Date code to Temporal, first ask: "What kind of time do I really have?"

• An exact moment? Turn it into an Instant.
• A date from a form? Read it as a PlainDate.
• A flight or a meeting in a place? Use a type with a time zone, ZonedDateTime.

In the table, each row is one common Date habit. Read across to see what to use instead, and why.

1const legacyDate = new Date("2024-03-10T06:30:00.000Z");2const instant = Temporal.Instant.fromEpochMilliseconds(legacyDate.getTime());3console.log(instant.toString());4console.log(instant.epochMilliseconds);

1const dueDate = Temporal.PlainDate.from("2024-05-12");2console.log(JSON.stringify(dueDate));3console.log(dueDate.toString({ calendarName: "never" }));

Before you save or send a value, you turn it into text. Line 2 does this with JSON.stringify and prints "2024-05-12", a date with no time added. Line 3 gets the same date text with toString. The option { calendarName: "never" } says: don't add a calendar note.

Save the value just as it is. Add a time zone later, only when you really have a place and a clock time.

A practical scheduling decision

When you build a form or a database field, don't start from "Which date method do I know?". Start from "What did the user actually type in?"

• A birthday reminder needs a month and a day that come back every year.
• A card's end date needs a year and a month.
• A meeting invitation needs a clock time and a named time zone.
• A server log needs one exact moment.

In the table, find what your app receives in the first column. The second column is the type to use.

Keeping the types apart also helps when you save them:

• Save an Instant as date text or as its milliseconds number.
• Save a PlainDate as date-only text.
• Save a future meeting with its time zone name next to it.

Don't turn every value into "midnight UTC" just to fit one old database field.

1const date = Temporal.PlainDate.from("2024-05-12");2const time = Temporal.PlainTime.from("09:30");3console.log(date.toLocaleString("en-GB"));4console.log(time.toLocaleString("en-GB"));

A locale is a language and region code, like "en-GB" for British English. It decides how dates look, for example day first or month first. Lines 3 and 4 pass "en-GB", so the date shows day first.

toLocaleString makes text for people to read. Don't save that text. Keep the Temporal value, and turn it into display text again whenever you need it.

Common misconceptions

1const first = Temporal.PlainDate.from("2024-05-12");2const second = Temporal.PlainDate.from("2024-05-12");3console.log(first === second);4console.log(first.equals(second));5const due = first.add({ days: 1 });6console.log(first.toString());7console.log(due.toString());

Line 3 asks, "Are these the same object?" They aren't, so === prints false. Line 4 asks, "Are these the same date?" They are, so equals prints true. Line 5 keeps the new date from add in due. Line 6 shows that first didn't change. Line 7 prints the new date.

Some Temporal types sound alike. Each row of the table is one type: what it holds, and when to use it.

For each question, first ask: "What kind of time is this: an exact moment, a plain date or time, a time in a place, or a length of time?" Each answer explains why it is right or wrong.

Key takeaways

• Temporal is a toolbox: one type for each time job, instead of one Date object for everything.
• An Instant is one exact moment. The Plain types are dates or clock times with no time zone.
• A ZonedDateTime knows its place's clock rules, so on a clock-change day, 24 hours and 1 day can be different.
• A Duration is a length of time. You can round it, or turn it into one unit like minutes.
• Temporal values never change. To move from Date, start by turning its milliseconds number into an Instant.

Up next: Number & Math in depth.