Temporal: Modern Dates and Times in JavaScript

Hi, my name is Philip Chimento. I work as a JavaScript engine developer at Igalia. I'll speak today about the temporal proposal, which adds modern date and time handling to JavaScript. I'm part of a group working on this proposal, and my participation is part of a partnership between Igalia and Bloomberg.

In this presentation, I'll give you a tour through the API and show you what you can do with temporal by means of walking you through an easy, medium, and a complicated programming task. So, if you are asking what is temporal, it's an API that's been proposed to become part of JavaScript. It'll be available in browsers soon. And it'll add a built-in library for dates and times, like many other programming languages already have.

So, when I say it's built in, I mean it's part of your browser or of your JavaScript engine. That's important because many developers include a dependency on Moment or some similar library in their app to achieve the same thing that you could with temporal. But depending on how much locale data you include, that could add a payload of anywhere from a dozen to 200 kilobytes to your app. And with built-in, you avoid that. Temporal is strongly typed. That means that for different kinds of data, such as a calendar date with or without an associated time, there are different types to represent them, instead of one type fits all.

Temporal objects are immutable, and that means that you don't have to worry about code that you don't own modifying your objects without your knowledge. And lastly, it's designed to work together with JavaScript's internationalization facilities. And it provides things that a lot of other libraries don't, such as non-Gregorian calendars.

So, a fair question for any addition to the JavaScript language is, do we really need this? Like, we already have the global date object. It's not perfect, but it's done okay for all these years. And I'm going to disagree with what I just said. We do actually have a good list of Date's deficiencies. This here is a list of problems with dates that were identified way back at the beginning that Temporal aims to solve.

I won't go into all of these. Some of them, such as the unwieldy APIs, could be fixed, but others like mutability can't be fixed without breaking the web, because there's so much code out there that already relies on the existing behavior. The original JavaScript Date was based on a Date class from Java, which Java deprecated in 1997 and replaced by something better. And a quarter century later, we're now doing the same thing in JavaScript.

So, I mentioned strong typing. For the next few slides, I'll give you a tour through these types that Temporal introduces. The first type you should know about is instant. It represents what we call an exact time, an instantaneous point on the timeline with nanosecond resolution. There's no calendar, so no months, weeks, years, or days. No time zone, so no daylight saving adjustments. Just purely an ever-increasing number.

Next, we have a family of types called the plain types. These represent a date on your wall calendar and a time on your wall clock, which we call wall time for short. These represent your local date and time independent of time zone, and so there are no daylight saving adjustments. But unlike instant, they're not exact moments in time. A wall time like November 18th, 2024 at 2.30 occurs at several different exact times around the world. So, this is just purely the numbers that you see on your wall. So, why do we have this family of plain types or wall types with progressively less information? This is so that you can correctly represent the information that you have. For example, with the old Date, if you wanted to represent a date without a time, you might use midnight in the user's local time zone. But there are actually days in certain time zones where midnight is skipped due to daylight saving time.

For example, with the old Date, if you wanted to represent a date without a time, you might use midnight in the user's local time zone. But there are actually days in certain time zones where midnight is skipped due to daylight saving time. That can cause hard-to-track down bugs when you try to put midnight for one of those days. For example, midnight on November 4th, 2018 didn't exist in Brazil. So, November 4th, 2018 is a different piece of data than November 4th, 2018 at 12 a.m.

So, here are the types that we have that don't carry all of the information. PlainDate is a day without a specific clock time, which is a very common use case. Plain time is a clock time not on any specific day. PlainYearMonth is a month without a specific day. So, you could think of using that to refer to an event that happens occasionally, like I have here the November 2024 board meeting. It also corresponds to HTML input type month. And PlainMonthDay is a calendar date but without a specific year. So, you could think of that as referring to a birthday or anniversary or something. Like I say, my birthday is December 15th.

Completing the family of types is another exact time type called ZonedDateTime. Just like instant, this type represents an exact moment in time but is also coupled to a location with time zone rules because it includes a time zone. The time zone means that this type does account for daylight saving time changes and other changes in the time zone. And it also has a calendar, which means that unlike instant, it has a year, month, and day. So, it's an exact time, but it can conveniently give you a while time as well. We say that zone date time represents a calendar event that happened or will happen at a place on Earth.

Then there's one more type that's part of temporal and doesn't represent a date or a time. Duration, we use it in arithmetic with the other types and it has some methods of its own for rounding and converting between units. So, here's the relationships between all the types. This diagram is taken from the temporal documentation. You can see there are the two types on the left that know the exact time, instant and ZonedDateTime. And there are the other types on the right that know the wall time. ZonedDateTime spans both categories because it knows both the exact time and the wall time. Now that I've introduced you to the cast of characters in temporal, it's time to show how to accomplish a programming task.

Now that I've introduced you to the cast of characters in temporal, it's time to show how to accomplish a programming task. I've personally always learned better by doing. So, I hope this will show you what you can do with the API. I've picked three tasks to walk through, an easy one, a medium one, and a complicated one. First, the easy one.

The easy task is to get the current time as a time stamp in milliseconds. This is the number one top voted question for the old JavaScript Date object on Stack Overflow. So, naturally we'll want to be able to do the same thing in temporal. First, we consider what type we have to use. A time stamp represents an exact time without regard to time zones. And so, we think back to the types that I mentioned. The type that corresponds to that exact time, no time zone, is instant.

The next thing, maybe it's kind of a meta thing to consider, is do we really want a timestamp in milliseconds, or will the instant object itself work just as well? I think going forward, as temporal gets wider adoption, I'd expect that numerical time stamps are going to be mainly necessary for interoperation with non JavaScript systems, not so much for JavaScript applications where we'll just use instant. But for the sake of this example, let's say that we do actually need a numerical timestamp. So, we know what type we need. Next, we need to know how to fill it with the current time.

We do this with the functions in the Now namespace. Any of these functions will give you the current date or time or time zone in the form of an instance of one of the temporal types. The ISO in the name means that the date is in the standard ISO calendar, and I'll talk more about calendars and what that means later. But since we need the current time as an Instant, we'll use the top one from this list, Temporal.Now.instant. Next, we need to figure out how to get a number of milliseconds since the Unix epoch from the instant.

So, this is a good time to talk about how do you get date and time info from your instances of temporal types. All the types have read-only properties that we can use to get this sort of information. So, for example, year is only on types that have calendars and also not on PlainMonthDay. Offset only exists on ZonedDateTime, and the epochNanoseconds and similar properties are only on the exact time types in ZonedDateTime. So, in our case, we need the epochMilliseconds property because that's the number of milliseconds since the Unix epoch of 1970, January 1st, midnight. So, we put all the information on the previous slides together into this one-liner here. We get the result of Temporal.Now.instant and examine its epochMilliseconds property to obtain a Unix timestamp in milliseconds.

And here's a possible output, depending on when you call the method.

So, that was the easy task. Now for the medium task. The question we have to answer for the medium task is, what is the date one month from today? We already saw in the previous task how to figure out what the date is today. You just use a different function from the Now namespace. So, let's skip that for the moment, although I'll talk more about how it interacts with calendars in a moment.

How do we add one month to a date? This is a good time to take a look at how to do arithmetic with dates and times in temporal. I mentioned Duration a few slides ago, and I mentioned arithmetic methods. These are the arithmetic methods. We have add and subtract for adding or subtracting a duration from another type. And we also have since and until that determine the elapsed time as a duration between two objects of the same type. So, in our case, we use the add method. We want to take a date and add a duration of one month. We pass it a property bag, which automatically gets converted to a duration, so that we don't have to call the Duration constructor here in this line of code.

This date variable, where does that come from? We already need to know we need to use one of the Now methods, specifically Now.plainDateISO. And here's where I said the ISO thing was going to come back. So, a little bit about calendars. The ISO calendar can be thought of as the machine calendar. The way it works is standardized. It has no regional or language dependence. It's suitable for computation. The Gregorian calendar is a human calendar that's used in a large part of the world with minor variations, but it's what the ISO calendar is based on. They're similar enough that you can mentally switch between the two without having to do mental calculations. However, a large part of the world uses the Gregorian calendar, but that doesn't mean that the whole world uses it. Some regions don't, and in some regions, people use the Gregorian calendar for business purposes and another calendar for religious purposes. So, already without temporal, you can print an old JavaScript date object in a non-Gregorian calendar if the user wants it. So, that's good enough for some applications, but it's not good for answering this question, because how long one month is depends on which month you're talking about in which calendar. I can illustrate that.

Here's an example of how it could go wrong using the old date. Let's say today's date in the Gregorian calendar is October 9th. One month later is November 9th. In the Hebrew calendar, these two dates are not one month apart this year. They're one month and one day apart because the months are different lengths than in the Gregorian calendar. So, it's not enough just to add an ISO calendar month and print the dates in another calendar. You have to actually consider the calendar when performing the addition.

The takeaway here is when you're working with dates that the user will see, use the user's preferred calendar, not the machine ISO calendar. So, if we put that all together, the way to get the date one month from today is first of all, you have to define exactly what month you mean by choosing the calendar. You can get the calendar from the user's preferences in your app, for example, or from their locale using the resolvedOptions method of Intl.DateTimeFormat. Although that's a good approximation, but it doesn't always correspond to what the user actually wants. And then you can get today's date in that calendar using Now.plainDateISO, put the calendar in it using the withCalendar method. Then you can add one month to it using the add method, and then you can format it for the user with the toLocaleString method.

For the complicated task, we need to answer the question using the information on this conference website. What times do these sessions happen for me? Which sessions can I attend when I'm not asleep? Funny thing, I would have loved to use the JS Nation US website for this, but it conveniently already puts the sessions in your browser's local time zone. So, well done on that. I had to pick a different conference website that didn't do that. But let's pretend these are JS Nation US sessions. This question turns out to be surprisingly hard to answer if we don't use a computer because it requires a lot of mental gymnastics with time zones and subtracting or adding hours. The strongly typed approach that we have in Temporal is perfect for solving this problem, because you can determine the type based on what data you have, and then you can determine what type to convert it to based on what data you need. Here are the facts that we know. We know from the website the two calendar dates of the conference, July 23rd and 30th. I got the screenshot from a past conference, but let's say for this example, the dates are in 2025. Then there are three sessions on each conference day.

So, most people, myself included, if we want to know what time 11 o'clock AEST is in my time zone, I'll just put it into a search engine and hope that the search engine correctly guesses what I want. But the strongly typed approach that we have in Temporal is perfect for solving this problem, because you can determine the type based on what data you have, and then you can determine what type to convert it to based on what data you need.

So, here are the facts that we know. We know from the website the two calendar dates of the conference, July 23rd and 30th. I got the screenshot from a past conference, but let's say for this example, the dates are in 2025. Then there are three sessions on each conference day. We know the local start times of each of the three sessions and what time zones those local start times are given in. So, it's 11 a.m. AEST, noon BST, and 1 p.m. EDT. Then I also know my time zone, and I know the hours in my local time zone during which I'm willing to be online watching a conference.

Here's a pseudocode expression of what we need to do. For each date and each session, we know the wall time and the time zone, which allows us to figure out the exact time that the session starts and ends. Then we need to go from that exact time back to wall time in my local time zone to check whether I'm awake or not. If I'm awake, then we print out that session. Here's the first part of the code where we set things up. We have the calendar dates, the session time zones, and the start hours. We have the length of the sessions, and we have my time zone. So, my time zone we get from another now method. Session length is a duration. And the dates are plain dates. So, for this calculation, it's okay to use the ISO calendar for the dates because I'm reckoning my awake times in the ISO calendar as well. Now, there are a few things to explain here. One of them is how I determine these time zone names. I was mentioning the abbreviations like AEST and BST in the previous slide. On the website, we had the full names, Australia Eastern Standard Time, British Summer Time, and Eastern Daylight Time with North America implied in the last one. Those are human names, not machine identifiers. These strings with the slashes here on this slide, like Australia slash Brisbane, those are the official identifiers of the IANA time zone database. That's how you refer to time zones in Temporal. If you don't know the identifier for a particular time zone, you can usually find it out on Wikipedia or you consult the database.

Sometimes, the human abbreviations are ambiguous. But the identifiers are always precise. So, the next question is, why are we using from to create these objects? This is a good time to talk about how to create a Temporal object. You might expect you could also use a constructor to create an instance of a Temporal type. The constructors are intended for low-level use where you have all the data in exactly the right format, like in these examples. Then, on the other hand, there are these factory methods named from. They're high-level. They accept many more kinds of data and convert it.

In particular, they're often more readable. Like a property bag with year 2019, month 6, that's I find that more readable than just a string of numbers. So, in most cases, I'd recommend using from to create a Temporal object. But if you have the exact data in the exact right format, you can use the constructor. The other piece of data I mentioned we know is what times I'm willing to be online for a conference. I want to write a little function that takes a wall clock time and returns true if the time is within my online hours.

So, for that, we have to do comparisons. Each type has a compare static method that we use for this. It's a static method, so that you don't need an instance. You can use it as an argument to the sort method of arrays. If instead, you just want the common case of checking whether two objects are equal, use the equals method. So, back to writing code. Here's the function that tells you whether I can be online. We're using PlainTime.compare to implement it. Here I am taking advantage of the fact that my online hours don't cross midnight. We'd have to be slightly more complicated to support the case where they did. But this is enough for this example. Now, this code is how the actual calculation works. I previously outlined it in pseudocode. We loop through each conference date and the info for each session, and we convert it to the exact time named session start as a zone date time. Then we use the with time zone method to get a new zone date time object for the start of the session in my time zone instead of the conference session's time zone. Then we add the session length using the add method that we're familiar with to get the end of the session in my time zone.

These we pass to our comparison function, and if they're during my online times, we print out the start and the end of the session using formatRange. If you're watching a recording of this talk, feel free to pause it to examine the code in more detail if you want.

So, conversion. The toZonedDateTime method that we saw is an example of one of the methods for conversion between types. To convert from one type to another, you either need to add information or drop information. If you drop information like the year when you go from PlainDate to PlainMonthDay, the method doesn't take any argument. If you need to add information like the clock time, the method will take the required information as an argument. In our case, we converted from PlainDate to ZonedDateTime, so we had to add both a time zone and a time, which the toZonedDateTime method takes in a property bag.

The other new method you saw was withTimeZone, so this is a good time to get into how to modify a temporal object. Technically, you can't modify them. They're immutable, like we talked about at the beginning of the presentation, but you can get a new object of the same type with one or more components replaced, and this is what the with method is for. That takes a property bag with one or more components to replace and returns a new object. And then we have separate methods for withCalendar, that you saw already earlier during the medium task, and withTimeZone, which you saw in this task, because those two can't be provided at the same time as any other properties because it would be ambiguous which property you have to replace first.

So, take that code, put it all together, run it, and here's the nicely formatted answer. This is the answer in my time zone with my locale's formatting with date style full and time style short, and your answer will likely be different if you live in a different time zone or have a different locale. So, this is a seemingly simple question answered in more lines of code than you might expect, but seriously, I wouldn't have even wanted to try to write this code with the old Date object. It would have been possible by carefully making sure the dates were all in UTC and converting accordingly by manually adding or subtracting the right number of hours, but it would be really susceptible to bugs. And with this one, I'm pretty confident I got the right answer. So, I hope you found this a useful tour of Temporal, and if you have the old Date object in your code base, I hope you're excited to replace it with Temporal. You can check out the documentation at this link here, and at some point the documentation will graduate and you'll be able to find it on MDN instead, along with the rest of JavaScript's built-ins. Thanks for your attention.