TC39 has had a Temporal API proposal in the works since 2017. It's currently at stage 3 (of 4). So this begs an obvious question... If Brendan Eich can invent all of JavaScript in 10 days, why has it taken eight years to replace the Date API?

Lets back up a bit and answer three important questions.

  • What is the Temporal API?
  • Why do we need it?
  • Why has it taken almost a decade to arrive?

What is the Temporal API?

JavaScript is getting a long overdue replacement for the venerable Date API. This new API is called Temporal and I'm hopeful we'll see it shipping in browsers this year.

Why replace the Date API?

Java and JavaScript are very different languages, but both were born in the second half of 1995. Brendan Eich, the creator of JavaScript, took a few shortcuts during this mother of all sprints. One of which was to copy the nascent java.util.Date API verbatim into JavaScript.

💬
“I’m not proud, but I’m happy that I chose Scheme-ish first-class functions and Self-ish (albeit singular) prototypes as the main ingredients. The Java influences, especially y2k Date bugs but also the primitive vs. object distinction (e.g., string vs. String), were unfortunate.”
— Brendan Eich

The Java world quickly realised the limitations of their Date API and deprecated it. Replacing it with a more sophisticated set of Date and Time packages. JavaScript though, has lumbered on with the same API for the last 30 years.

JavaScript fortunately, is a very malleable language. In time, libraries emerged to fill the various holes in the native Date API. For example, every operating system has timezone and localisation data. But without a native web API, that same data must be sent over the wire, every time it's needed. As a result, some of these libraries grew notoriously large.

The JavaScript Date API limits itself entirely to managing the component parts of timestamps. It has no formal support for durations, intervals and so on. The Date API therefor is both underpowered and inconsistent. The proposal for Temporal is more accurately a namespace for a variety of related date/time functionality. It will greatly expand the temporal capabilities in the browser, by natively managing timestamps, durations, intervals and timezones.

So why has Temporal taken so long?

If Brendan Eich can create JavaScript in ten days, why then has Temporal taken eight years just to get to stage 3?

The naive answer is that Temporal is trying to plug several very big holes. But the scope of this new functionality is not actually the primary reason for the delay. A key part of Temporal is its interoperability with the modern web and computing standards of the last 30 years. The standards space is much more evolved than it was in 1995. For example:

  • Temporal timezone strings are derived from the long established IANA Time Zone Database.
  • Temporal timestamp strings come from RFC9557 which is a very recent update to the RFC3339 standard.
  • Temporal duration strings come from the ISO-8601 standard.
  • and so on...

TC39, the committee responsible for driving the ECMAScript standard, has a process for surfacing new features. Temporal is currently at Stage 3 (of 4) and has been for some years. Ironically the main cause of the delay has been this interoperability with the other standards.

One such example is the Internet Engineering Task Force. The long standing IETF standard RFC3339 defines timestamps for Date and Time on the Internet. This spec derives its valid formats from a subset (or "profile") of ISO-8601. Temporal required an extension to RFC3339. This extension permits timestamps to also include timezone and calendar string serialisation formats. The IETF raised this as RFC9557 and it was finally approved in April 2024.

Outside of Temporal, ECMA has a broader Internationalisation API Specification defined in ECMA-402. This drives the modern Intl Web API which includes localised string formatting for Dates and Times. The Intl.DateTimeFormat and Intl.RelativeTimeFormat APIs both derive their data from the Unicode CLDR project. This data now ships with the browser, further reducing the need for large JavaScript datetime libraries.

The working group is well aware of how long Temporal has taken. In June 2024, in a pragmatic effort to ship something, the scope of Temporal was reduced. Custom calendars and timezones were removed from the spec. Given how long we've waited, it felt sensible to me. This extensibility is quite niche but may not be lost forever. If you have a burning need for it (and a lot of time on your hands) there is a stage 0 proposal for Temporal v2 on the drawing board.

So, after many years the spec has stabilised and browsers are beginning to implement it. Firefox were first to ship an implementation. Deno supports it behind a flag and you can track Chrome's implementation here. When it will finally ship is still unclear. As Phil Chimento commented in 2023:

💬
"It depends on when the browsers prioritize the work of implementing it, because one of the entrance requirements for stage 4 is 'Two compatible implementations which pass the acceptance tests', and there are other nontrivial requirements as well."
— Phil Chimento

In the latest update from TC39 we were told Temporal shipped in Firefox 139 (May 27th). Chrome V8 has started their integration of the Rust library temporal_rs and now has a partial implementation of Temporal.Instant. Work progresses on the Safari JavaScriptCore implementation. So, If you want to play with it now, your choices are Firefox or the Temporal polyfill.

With Google shifting its focus from browsers to AI, we may have to wait a little bit longer before we see the magical "two compatible implementations". But if you asked me to put my hat in the ring, I still think it'll ship this year.