JavaScripts Temporal API: New era for date and time calculations

Something is happening with the Temporal API, the interface that is supposed to eliminate one of the biggest weaknesses of the JavaScript programming language: the handling of date and time. TC39, the standardization committee for JavaScript, has been working for some time on the Temporal API, which is intended to replace the Date interface. The problems of the Date interface are manifold, there are inconsistencies, susceptibility to errors and a lack of support for time zones. The Temporal API is not only intended to replace the Date API, but also to compete with established libraries such as date-fns, Day.js or Luxon.

Sebastian Springer

Sebastian Springer works as a JavaScript Engineer at MaibornWolff. In addition to developing and designing applications, his focus is on imparting knowledge. As a lecturer for JavaScript, speaker at numerous conferences and author, he tries to arouse enthusiasm for professional development with JavaScript.

Progress and browser support of the Temporal API

The TC39 itself has implemented a polyfill, i.e. a program code module written in JavaScript, which makes the interface available in various JavaScript environments such as the browser or on the server side. However, it is explicitly not intended for productive use. There are now two packages, @js-temporal/polyfill and temporal-poyfill, which can be used instead. With around 160,000 and 130,000 weekly NPM downloads respectively, their distribution cannot be compared with the 26 million of date-fns or the 22 million of Day.js. However, the situation will change in the near future.

Firefox is the first browser to deliver a complete implementation of the Temporal API – although only in the nightly build of the browser, which is the first step towards the integration of a new interface. Safari provides individual parts of the API in its Technical Preview and all other browsers are also actively working on integrating the new API.

At the moment, the interface can only be used via the polyfill packages, but it is well on the way to becoming the new JavaScript standard for working with dates and times.

Structure and goals

The Temporal API not only addresses the shortcomings of JavaScript's Date API, but also adopts numerous useful functions from the established date libraries. The interface is also based on modern architectural patterns. The main features of Temporal are

• Consistency: Temporal consists of a set of classes that provide a consistent and intuitive interface for working with date and time.
• Robustness: The interface supports time zones and various calendar systems such as the ISO 8601 calendar, the Indian calendar, the traditional Korean calendar and many more.
• Immutability: The Temporal objects are not mutable. Methods that manipulate the date or time, such as addition or subtraction, create new instances and do not change the original object. This prevents side effects that can arise from the manipulation of referenced objects.
• Precision: The API works with an accuracy of nanoseconds and not milliseconds like the Date object. It therefore supports high-precision timestamps such as those used by the Node.js performance hooks API.

The Temporal API provides a range of classes for the different use cases when processing date and time values:

• PlainMonthDay: Stands for a day and month independent of the year. This can be used for annually recurring events such as birthdays.
• PlainYearMonth: This class represents a month in a given year without a day, time or time zone. A possible use case is a monthly billing period, for example the cell phone bill for March 2025.
• PlainDate: The PlainDate stands for a specific day without a time or time zone. One use case is a person's birthday, for example 04.07.1961 (the birthday of Brendan Eich – inventor of JavaScript).
• PlainTime: Stands for a time on any given day. It has no reference to a date or a time zone. A typical case is the start of a daily recurring appointment such as the lunch break.
• PlainDateTime: Combines date and time, so stands for a time on a specific day. For example, an instance of this class can represent the time of the total solar eclipse on 11.08.1999 at 12:35 (in Munich).
• Instant: A Instant instance is a specific point in time represented as a number of nanoseconds since 1/1/1970 UTC. The time zone is therefore fixed to UTC. Objects of this class can be used, for example, to measure the time between two events.
• ZonedDateTime: This class is the easiest to configure. It includes the date, time and time zone. An example of this type is the start of a cross-time zone meeting.

Depending on the use case, there are several ways to create a new Temporal instance. Listing 1 shows these using the PlainDateTime class as an example.

const now = Temporal.Now.plainDateTimeISO();
console.log(now.toString()); // 2025-02-23T11:06:41.898

const newDateTime = new Temporal.PlainDateTime(1999, 8, 11, 12, 35);
console.log(newDateTime.toString()); // 1999-08-11T12:35:00

const newDateTime1 = Temporal.PlainDateTime.from(newDateTime);
console.log(newDateTime1.toString()); // 1999-08-11T12:35:00

const newDateTime2 = Temporal.PlainDateTime.from('1999-08-11T12:35');
console.log(newDateTime2.toString()); // 1999-08-11T12:35:00

const newDateTime3 = Temporal.PlainDateTime.from({
  year: 1999,
  month: 8,
  day: 11,
  hour: 12,
  minute: 35,
});
console.log(newDateTime3.toString()); // 1999-08-11T12:35:00

const newDate = new Date('1999-08-11T12:35');
const instant = newDate.toTemporalInstant();
const zoned = instant.toZonedDateTimeISO('Europe/Berlin');
const newDateTime4 = zoned.toPlainDateTime();
console.log(newDateTime4.toString()); // 1999-08-11T12:35:00

Listing 1: Creating new instances of the PlainDateTime class

For the current time, the Temporal API provides the Temporal.Now object with a number of methods. The plainDateTimeISO method creates a PlainDateTime object.

There are different variants for instances that represent a fixed point in time. The first is via the constructor of the PlainDateTime class, which accepts a number of parameters that represent the individual parts of the time. Of these, the year, month and day are mandatory. All other information has the value 0 by default. The static method from is much more flexible and therefore recommended. It accepts either a PlainDateTime object, of which it creates a copy, an ISO string that represents the date, or an object with the information about the date in the form of property values.

Converting a JavaScript Date object into a PlainDateTime object is somewhat more complicated, but still possible. The Date API will provide the toTemporalInstant method in the future. The Instant instance must be converted into a ZoneDateTime, which can then be converted into a PlainDateTime object. This detour also makes it possible to integrate the Temporal API into existing applications.

The creation of date objects was already possible with the previous means of JavaScript, albeit in an inconsistent manner. The really interesting

extensions are the new operations that the Temporal API enables.