The Future of Dates in JavaScript: Introducing Temporal

What is Temporaal?

Temporal is a proposal currently at stage 3 of the TC39 process. It's expected to revolutionize how we handle dates in JavaScript, which has always been a challenging aspect of the language.

But what does it mean that it's at stage 3 of the process?

• The specification is complete
• It has been reviewed
• It's unlikely to change significantly at this point

Key Features of Temporal

Temporal introduces a new global object with a fresh API. Here are some important things to know about Temporal:

1. All Temporal objects are immutable
2. They're represented in local calendar systems, but can be converted
3. Time values use 24-hour clocks
4. Leap seconds aren't represented

Why Do We Need Temporal?

The current Date object in JavaScript has several limitations:

• No support for time zones other than the user's local time and UTC
• Date objects can be mutated
• Unpredictable behavior
• No support for calendars other than Gregorian
• Daylight savings time issues

While some of these have workarounds, not all can be fixed with the current Date implementation.

Let's see some useful examples where Temporal will improve our lives:

Some Examples

Creating a day without a time zone is impossible using Date, it also adds time beyond the date. Temporal introduces PlainDate to overcome this.

let usingDate = new Date('2025-04-03');
// 2025-04-03T00:00:00.000Z

console.log(usingDate);
// Wed Apr 02 2025 21:00:00 GMT-0300 (Chile Summer Time)

let usingTemporal = Temporal.PlainDate.from('2025-04-03');
// PlainDate [Temporal.PlainDate] {}
console.log(usingTemporal.toString());
// 2025-04-03

But what if we want to add timezone information? Then we have ZonedDateTime for this purpose. The timezone must be added in this case, as it also allows a lot of flexibility when creating dates.

let zoned = Temporal.ZonedDateTime.from('2025-04-03T00:00Z[UTC]');
console.log(zoned.toString());

Temporal is very useful when manipulating and displaying the dates in different time zones.

let utc = Temporal.ZonedDateTime.from('2025-04-03T00:00Z[UTC]'); // Created as UTC
console.log(utc.toString());
//2025-04-03T00:00:00+00:00[UTC]

let clientZoned = zoned.withTimeZone(Temporal.Now.timeZoneId()); // Convert to the client timezone

console.log(clientZoned.toString());
// 2025-04-02T21:00:00-03:00[America/Santiago]

Let's try some more things that are currently difficult or lead to unexpected behavior using the Date object.

Operations like adding days or minutes can lead to inconsistent results. However, Temporal makes these operations easier and consistent.

let date = new Date('2025-03-09');
console.log(date); // 2025-03-09T00:00:00.000Z

// add 100 days
date.setDate(date.getDate + 100));
console.log(date); // 2025-06-17T01:00:00.000Z

const zoned = Temporal.ZonedDateTime.from('2025-03-09[UTC]');
console.log(zoned.toString()); // 2025-03-09T00:00:00+00:00[UTC]
console.log(zoned.add({days:100}).toString()); // 2025-06-17T00:00:00+00:00[UTC]

Another interesting feature of Temporal is the concept of Duration, which is the difference between two time points. We can use these durations, along with dates, for arithmetic operations involving dates and times. Note that Durations are serialized using the ISO 8601 duration format

const duration = Temporal.Duration.from({ hours: 5, minutes: 15 });
console.log(duration.toString());
// PT5H15M

const zoned = Temporal.ZonedDateTime.from('2025-03-09[UTC]');
console.log(zoned.toString()); // 2025-03-09T00:00:00+00:00[UTC]
console.log(zoned.add(duration).toString()); // 2025-03-09T00:05:15+00:00[UTC]

Temporal Objects

We've already seen some of the objects that Temporal exposes. Here's a more comprehensive list.

• Temporal
• Temporal.Duration`
• Temporal.Instant
• Temporal.Now
• Temporal.PlainDate
• Temporal.PlainDateTime
• Temporal.PlainMonthDay
• Temporal.PlainTime
• Temporal.PlainYearMonth
• Temporal.ZonedDateTime

Try Temporal Today

If you want to test Temporal now, there's a polyfill available. You can install it using:

npm install @js-temporal/polyfill

Note that this doesn't install a global Temporal object as expected in the final release, but it provides most of the Temporal implementation for testing purposes.

Conclusion

Working with dates in JavaScript has always been a bit of a mess. Between weird quirks in the Date object, juggling time zones, and trying to do simple things like “add a day,” it’s way too easy to introduce bugs.

Temporal is finally fixing that. It gives us a clear, consistent, and powerful way to work with dates and times.

If you’ve ever struggled with JavaScript dates (and who hasn’t?), Temporal is definitely worth checking out.

About the author

Ignacio Falk

Senior Software Engineer

I love to learn new things and share what I know. Mentor, Writer, Speaker Member of the local community

@flakolefluk@flakolefluk