JavaScript developers have long struggled with the limitations of the built-in Date object.
The Date API, inherited from Java’s java.util.Date, has fundamental design flaws that make handling date and time cumbersome and error-prone, meaning most JS developers use libraries like date-fns, moment.js or day.js to help ease the pain.
Well, things might be about to change.
The Temporal API is a new built-in API designed to replace Date entirely, providing a robust and comprehensive solution for managing time, dates, and time zones in JavaScript applications.
It’s worth saying that the Temporal API does not have widespread support, and is - at present - limited to being an experimental in Firefox’s Nightly browser (aimed at Developers). However, it promises to solve some big issues, so we thought we’d take a closer look in the hope that it gets widespread support sometime soon.
So, let’s dig into it and take a closer look at Temporal, and see whether it could fix JS’s date issues once and for all.
Why Temporal?
Problems with the Date Object
The Date object in JavaScript serves two purposes:
- As a timestamp, representing milliseconds since the UNIX epoch (January 1, 1970).
- As a combination of date and time components (year, month, day, hour, etc.), which must be interpreted relative to a time zone (easier said than done, right?).
The issue with the Date API is that it has a number of issues that have never really been solved:
Firstly, timezones are implicit. Dates are always interpreted in either UTC or the system’s local time, with no way to specify an arbitrary time zone.
Secondly, it’s a mutable API, with methods modifying objects instead of returning new ones, which gives us unwanted side-effects.
Calendar-wise, you might not have even realised that the Date object only supports the Gregorian calendar, making it far-from-ideal for international applications that might use other calendars.
Finaly, handling date strings across different locales is difficult and often results in inconsistencies throughout the application due to a lack of a clear best-practice.
How Temporal Fixes These Issues
The Temporal API is designed to resolve these flaws in the following ways:
Firstly, the Temporal API is immutable so data cannot be modified, meaning that instead new objects are created instead. This means our application will behave in a more predictable way, which is a great start.
Time zones and calendar-support is built in, meaning its easy to apply your calendar of choice and convert arbitrary values into timezone-specific ones in a readable way.
The API is clearer and more logical, compared to the Date API, meaning that the code itself is easier to understand, as you’ll see down below. Finally, Temporal is precise down to the nanosecond, instead of just(!) milliseconds, which is a really nice touch.
The Basics of Temporal’s API
Temporal’s Core Concepts
Unlike the Date object, Temporal is a namespace, similar to Math. It provides various classes, each designed for specific date and time operations, and each one is readable and concise, too. Here’s a few to get you started:
1. Representing Time Durations
Temporal.Duration: Represents the difference between two points in time (e.g., “3 hours, 45 minutes”).
2. Representing Points in Time
Temporal.Instant: Represents a precise moment in history, independent of time zones.
Temporal.ZonedDateTime: Represents a specific date and time in a particular time zone.
3. Working with Date and Time Components
Temporal provides several classes for handling different aspects of date and time:
Temporal.PlainDateTime: Combines date and time without time zone.
Temporal.PlainDate: Represents only a date (year, month, day).
Temporal.PlainYearMonth: Represents only a year and a month.
Temporal.PlainMonthDay: Represents only a month and a day.
Temporal.PlainTime: Represents only time (hour, minute, second, etc.).
4. Accessing the Current Time
Temporal.Now: Provides utility functions to get the current date and time in various formats.
Using Temporal: Practical Examples
Creating Temporal Objects
Unlike Date, you cannot instantiate Temporal objects using the new keyword. Instead, use static methods like .from():
const instant = Temporal.Instant.from("2023-10-01T12:00:00Z");
console.log(instant.toString()); // "2023-10-01T12:00:00Z"
Creating a plain date:
const date = Temporal.PlainDate.from("2023-10-01");
console.log(date.toString()); // "2023-10-01"
Working with Time Zones
With Temporal, you can explicitly specify time zones:
const zonedDateTime = Temporal.ZonedDateTime.from({
year: 2023,
month: 10,
day: 1,
hour: 12,
minute: 0,
second: 0,
timeZone: "America/New_York",
});
console.log(zonedDateTime.toString());
Performing Arithmetic Operations
Since Temporal objects are immutable, operations return new instances:
const date1 = Temporal.PlainDate.from("2023-10-01");
const date2 = date1.add({ days: 7 });
console.log(date2.toString()); // "2023-10-08"
Comparing Dates
Comparing dates is straightforward with equals():
const dateA = Temporal.PlainDate.from("2023-10-01");
const dateB = Temporal.PlainDate.from("2023-10-01");
console.log(dateA.equals(dateB)); // true
Conclusion
The Temporal API looks like it’s a game-changer for JavaScript developers, and even in its current form it promises a much more straight-forward to any developer dealing with dates in their application.
We hope it gets widespread support soon, and we’ll keep you updated as the API develops.
In the meantime, if you’d like to hear more about this topic, check out our episode of The Weekly Developer Show with MDN documentation maintainer Dave Letorey, who has been diving deep into the API.
