Temporal is the new JavaScript standard for date manipulations. It has a long, difficult journey that I want to share with you. Is it ready for production or not? Let's find out!

Introduction

On May 13, 2017, the first commit of the Temporal Proposal was made, heralding a new API for date manipulation, inspired by popular libraries like moment.js and luxon.

Temporal aims to correct many of the pain points associated with the existing Date object in JavaScript, providing a better, more reliable framework for handling dates and times. Over the years, Temporal has evolved significantly, incorporating numerous features and improvements.

Key Differences from Date

Temporal introduces several significant improvements over the traditional Date object:

1. Correct Time Zone Handling: Temporal is designed with thoughtful time zone management, allowing developers to handle cross-time zone scenarios seamlessly.
2. Immutable API: The API is immutable, ensuring that date objects aren't accidentally modified and every operation returns a new object.
3. Duration Handling: Temporal includes robust support for intervals through the Duration object, making it easier to work with time durations.

Here's an example to demonstrate the ease of use:

const start = Temporal.PlainDateTime.from('2024-01-01T10:00');
const duration = Temporal.Duration.from({ hours: 3, minutes: 15 });
const end = start.add(duration);

console.log(start.toString()); // 2024-01-01T10:00
console.log(end.toString()); // 2024-01-01T13:15
console.log(duration.toString()); // PT3H15M

And another example:

const date1 = Temporal.PlainDate.from('2024-01-01');

const date2 = Temporal.PlainDate.from('2024-12-31');

const difference = date1.until(date2);

console.log(difference.toString()); // P11M30D (11 months and 30 days)

Comprehensive Entity Model

Temporal's design incorporates a comprehensive model for date and time entities:

• PlainDate: Represents a date without a time zone.
• PlainTime: Represents a time of day without a date or time zone.
• PlainDateTime: Represents a combination of date and time without a time zone.
• ZonedDateTime: Represents a date and time in a specific time zone.
• Duration: Represents a time interval.
• Instant: Represents an exact moment in time.

You can read more about the schematic of key entities here.

Active Development and Polyfill

In 2020, there was intensive work on the polyfill. Igalia played a crucial role, investing significant effort into the development process. They wrote extensive tests, ensured type safety, and added numerous runtime assertions—adhering to best practices meticulously.

I personally used this polyfill for a year while developing a Node.js project and was extremely satisfied. I didn't encounter any bugs and even submitted a PR to improve typings. It's gratifying to make even a small contribution to such a major project.

Why Temporal?

By 2021, I considered the Temporal proposal and its polyfill the most well-thought-out tool for date manipulation, and I still hold this view. However, the polyfill weighs 200 kB (50 kB gzip), making it somewhat heavy for front-end use. Nonetheless, it's worth noting that once Temporal is natively supported in browsers, you can simply remove the polyfill without altering your code—a luxury not available with other date libraries from NPM.

However, I couldn't afford to drag such a heavy library into every web application, and I forgot about Temporal for a while. Three years have passed since I used a well-crafted polyfill, so why hasn't it been shipped to all browsers yet?

Roadblocks to Becoming a Standard

A key feature of the new API is sophisticated time zone management. However, this couldn't be implemented fully due to inadequacies in the existing time zone standard. Ujjwal, an Igalia employee and the primary developer of Temporal, proposed extending the internet's date-time standard to allow for additional information. For instance, while Hawaiian law mandates a single standard time, locals often follow a different time zone. This issue isn't theoretical; it was an actual problem for my friend, a developer. The proposed extension permits specifying not just the time zone but also the specific "calendar", accommodating such nuances.

The proposal's acceptance was a significant milestone. As of October 23, 2023, the proposal was approved!

Platform Support

It's hard to predict when Temporal will become a standard and be available in all browsers, but there's progress. For instance, the V8 implementation of Temporal now occupies over 2.6% of the binary, and you can already use it in Deno.

Current Status and Future Outlook

Development on Temporal continues, with seemingly no remaining major blockers. You can track the current status here: GitHub Issues - Proposal Temporal.

For example, recently (May 2024), a method was removed - an intriguing change for a proposal on its way to becoming a standard. Does this mean Temporal is not ready yet? No, I think for a long time we can imagine Temporal as a mature date library that evolves and develops smoothly, just like any other NPM library.

So, what's better — a library with specific APIs without feature, or Temporal - a well-done, comprehensive date framework with ongoing improvements?

Polyfill

The only complexity with Temporal is the size of the polyfill. However, an alternative polyfill has been in development for some time now — temporal-polyfill by FullCalendar. Its size is much more appealing: 60.7 kB to 21.7 kB (gzip). And I plan to use it in my next project! How about you?