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:
- All Temporal objects are immutable
- They're represented in local calendar systems, but can be converted
- Time values use 24-hour clocks
- 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.