> Markdown version of [/magazine/544-the-temporal-api-how-javascript-dates-might-actually-be-getting-fixed](https://www.wearedevelopers.com/magazine/544-the-temporal-api-how-javascript-dates-might-actually-be-getting-fixed). Every page supports `.md` or `Accept: text/markdown`. Links point to the HTML versions so they work for humans too. Agent guide: [/agents.md](https://www.wearedevelopers.com/agents.md).

---

# The Temporal API: How JavaScript Dates Might Actually Be Getting Fixed

**By:** [Daniel Cranney](https://www.wearedevelopers.com/@daniel-cranney)

**Published:** February 4, 2025

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](https://www.npmjs.com/package/date-fns), [moment.js](https://momentjs.com/timezone/) or [day.js](https://www.npmjs.com/package/dayjs) to help ease the pain.

Well, [things might be about to change](https://developer.mozilla.org/en-US/blog/javascript-temporal-is-coming/).

[The Temporal API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal) 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.

## More on this Topic

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](/videos/1291-using-all-the-html-running-state-of-the-browser-and-modern-is-rubbish), who has been diving deep into the API.



## Related Articles

- [Is HTMX Worth Learning in 2025?](https://www.wearedevelopers.com/magazine/537-is-htmx-worth-learning-in-2025)
- [3 JavaScript-Free Techniques for Accordions, Dialogs, and Table of Contents](https://www.wearedevelopers.com/magazine/684-3-javascript-free-techniques-for-accordions-dialogs-and-table-of-contents)
- [Dev Digest 101 - the XXX edition](https://www.wearedevelopers.com/magazine/382-dev-digest-101-the-xxx-edition)
- [Dev Digest 136 - No JS(on) of mine](https://www.wearedevelopers.com/magazine/482-dev-digest-136-no-js-on-of-mine)

## Related Videos

- [WeAreDevelopers LIVE – You Don’t Need JavaScript, Modern CSS and More](https://www.wearedevelopers.com/videos/1788-wearedevelopers-live-you-don-t-need-javascript-modern-css-and-more)
- [Using all the HTML, Running State of the Browser and "Modern" is Rubbish](https://www.wearedevelopers.com/videos/1291-using-all-the-html-running-state-of-the-browser-and-modern-is-rubbish)
- [Exploring Durable Execution with Python](https://www.wearedevelopers.com/videos/1234-exploring-durable-execution-with-python)
- [The Time Paradox: Building Timezone-Safe Python/Django Applications](https://www.wearedevelopers.com/videos/1915-the-time-paradox-building-timezone-safe-python-django-applications)

## Related Jobs

- [Senior Software Engineer, Angular (B2C Web Platform)](https://www.wearedevelopers.com/jobs/ext/1927757-senior-software-engineer-angular-b2c-web-platform) at **Bitpanda**
- [Senior Software Engineer, React (Investing & Trading)](https://www.wearedevelopers.com/jobs/ext/1937625-senior-software-engineer-react-investing-trading) at **Bitpanda**
- [Technical Support Engineer 2](https://www.wearedevelopers.com/jobs/ext/171621-technical-support-engineer-2) at **Twilio**
- [Senior Software Engineer, React (Websites & Martech)](https://www.wearedevelopers.com/jobs/ext/1605272-senior-software-engineer-react-websites-martech) at **Bitpanda**
- [Principal Software Engineer](https://www.wearedevelopers.com/jobs/ext/267591-principal-software-engineer) at **Twilio**
- [Software Engineer](https://www.wearedevelopers.com/jobs/ext/1377585-software-engineer) at **Bitpanda**