Temporal: The Curious Incident of the Wrong Nighttime

All right. Thank you, everybody. Yeah. I want to mention I almost spent the night on the street. Not really. But you'll hear about that. Thanks for the introduction, Phil. That was very nice. I'm really happy to be here. I'm visiting from Vancouver, Canada. And, yeah, my work is as a JavaScript engine developer at Igalio.

I'm going to talk about Temporal. As you know, Temporal is a proposal to add modern data and time handling to JavaScript. So not as a package or a library, but built into JavaScript everywhere in the language. I'm part of a group working on this proposal. My participation is part of a partnership between Igalio and Bloomberg. We'll be more about that later.

Here's where you can find me right now, I guess. So where do you go if you want to get something built into JavaScript? You participate in standardizing it in TC39. That's what we're doing with Temporal. We meet every two months. Some of the meetings are fully remote. Some of them are in person, remote hybrid. So I want to tell you a story specifically about one TC39 meeting a couple of years ago. We were meeting in Bergen, Norway. I was lucky enough to be able to travel there in person. Funny thing. When I booked my trip there. So I promise this is going somewhere. Of course I needed a place to stay.

So I'm at home in Vancouver. I want to book a place. I go to the website of one of Bergen's fine hotel establishments to book a stay. I put in my dates. I want to check in July 10th, check out July 14th. And then I clicked okay. And I got to the confirmation page. And I saw this.

That was not what I asked for. Yeah. I wanted to check in July 9th. I don't want to check in July 9th. I want to check in July 10th. And I want to stay until the 14th. So this cat wants to know what happened and so do I. We can't know for sure because, of course, I didn't go and do a debugging deep dive on this hotel's website.

But I've been working on Temporal for five years. I've seen a lot of the pitfalls that you can make with the old JavaScript date object. I would be willing to bet a small amount of money that I know what happened. So let's pretend we're in the front end of this website. We'll pretend it by starting a REPL in the time zone of my home city, Vancouver. I pick my check-in date from the date picker. We're kind of simulating that here.

Then the front end converts it to a timestamp in milliseconds for sending to the back end. They probably figured, ah, number of milliseconds. Easy to serialize in JSON. Let's send it. Note the minus one. Yes, months are zero based in the old JavaScript date. Everybody hates that. It's one of the things we fixed in Temporal.

Okay. We send it. All right. So now we are on the back end. We put it in another REPL and put it in Norway's time zone. We receive that number of milliseconds. Turn it into a date object. Get the year, the month, the day. Okay. Looks good so far. And then we book it. Of course, the real hotel back ends don't have a time of check, time of use bug like this, but I'm simplifying.

We serialize that date into a timestamp and send it back to the front end. And, of course, we are very conscientious about our inputs. So we make sure that there's no extraneous time of day. We set the hours, minutes, seconds, et cetera to zero. Maybe you can start to see where this is going. We're in the front end again, back in Vancouver. My time zone, West Coast of Canada, UTC minus eight, receives the number of milliseconds.

Creates a date from it. And wrong day. The problem with the old date, it assumes that you mean in the current time zone. Unless you specifically say UTC. So this midnight timestamp in Norway is three in the afternoon on the previous day in Vancouver. So that's what my browser displayed to me in the confirmation page. So the big question, did I have a place to sleep on July 13th? I emailed the hotel, and I confirmed, yes, I do not actually have to spend my last night in Norway sleeping in the airport lounge or on the street or whatever. They had the right dates on their end. So I think their booking system got it right, which is what would happen in this little back and forth that I showed you. And it was just the confirmation page in my browser that got it wrong. But if I had lived east of Norway instead of west, maybe it would have been the other way around. They would have booked the wrong date but shown me the right date in the confirmation page. So it could have been worse.

Anyway, why am I talking about the old date if I'm building Temporal? So we're building Temporal. It's available in some browsers already, more about that later. It's coming to others soon. It's a built-in library. One of our design goals was to make it difficult to write bugs like this. You should have a type that does what you want to be able to do with that type but no more. Like, if you have a date and you don't care what time it is, you shouldn't run into bugs where it's accidentally 3 o'clock on the previous afternoon. So we had to design things around the understanding like a calendar date with no time is conceptually a different object than a timestamp in milliseconds. So if I were writing this hotel's website with Temporal, I'd use a plain date object. You get this data from your date picker, you create a plain date object, you can serialize it to send it to the backend with two JSON or maybe two string depending on your serialization needs, get it back from the backend, deserialize it, and you get another object that is equal to the first object. And there's no nonsense about this. It's true anywhere in the world. What else is good about it? I said it's built in. So many of you probably include in your various bundles or have included at some point Moment or Luxon or some library like that to achieve the same things that Temporal does. And you can do that, but depending on whether you include the locale data, it could be anywhere from a dozen extra kilobytes to hundreds of extra kilobytes. That's why we want this built into the language. It's immutable and there's strong support for internationalization.

I'm not going to zero in on those right now because we have a short amount of time. Those are other good things about it. I'll give you a little tour of the different types that we have available in Temporal. So I talked a bit about our design philosophy is only be able to do the stuff that you need to be able to do with that type. So you should be able to do more with Temporal than you could with the old date, but with each individual object that you have as part of Temporal, you should be able to do less. You shouldn't be able to do weird things like turning a date without a time into a number of milliseconds. And we're hoping that that makes some of these common mistakes difficult to do by accident.

If you really need to do it, you can figure out how to do it, but it's not right there at your fingertips. So the first type you should know about is Instant. It's an exact moment in time. We sometimes call it an exact time. It's an instantaneous point on the timeline, nanosecond resolution. There's no calendar, no months, weeks, years, or days. No time zone, no daylight saving summer or winter time adjustments, just a mostly increasing number.

Then we have a family of types called the Plain Types. So these represent a date on your wall calendar and a time on the clock on your wall. So sometimes we call them wall time, plain time, wall time. So they represent the date and time where you are independent of the time zone. So there are no winter and summer time adjustments, but unlike Instant, they're not exact moments in time. So a wall time, like you can say November 18th, 2024 at half past 2, that could occur at several different instants, depending on where you are in the world. And then we have a whole family of Plain Types with progressively less information. And so that's so that you can correctly represent the information that you have. So we have Plain Date, you saw that already in my example. This is a very common use case used for not booking the wrong dates in hotels. You have Plain Time, that's a clock time without any specific day.

So you can say, you know, Philips Q&A for temporal starts at 525 p.m. or 1725 if you use a 24-hour clock. We have Plain Year Months, that represents something that, it's a month without a specific day and you could refer to an event that happens occasionally like the June 2025 board meeting. We also specifically have that because it corresponds to an HTML input type, months. That's mainly what people use it for.

Oh yeah, Plain Months Day, it's a calendar date without a year. You can say my birthday is December 15th, which it is, but, you know, I won't tell you how old I am. So you can just celebrate my birthday on December 15th. You don't need to know the year I was born. We have one more exact time type, Zone Date Time. This is just like Instant, it represents an exact moment in time, but it does have a location and a time zone and it does have a calendar. So there are weeks, months, years. It automatically accounts for summer and winter time adjustments. So it has, basically, it's an exact time that has all the information needed to also give you a wall time.

Then there's a duration type. I won't go into that, but, you know, it's used with the other types, arithmetic methods like add and subtract. So you're all here, probably most of you are practicing developers, you want to see the code. I want to write some code. Don't know if I had enough time to do it live, so I prepared it in the slides, but, you know, since it is available in Firefox, maybe if I don't run out of time, we'll go and do it there. I've got a little worked example. I got this from a conference website. It's not the JS Nation website because actually the JS Nation website is really good about time zones and shows you, you know, the local time zone in Amsterdam. And also if you're on the remote track, it shows you your local time zone in your browser. So two thumbs up for whoever did that website. But you know, this was just a static image on this conference's website. So I want to answer the question, you know, okay, there's all these sessions where that I want to attend. Which ones can I attend, you know? Which ones are not while I'm asleep? You know, I live in one of these. I live in the Americas. Do I know when the Australian Eastern Standard Time, 10 o'clock is? I have no idea. You know, I could find it out.

Most people, if you're like me, you probably plugged that into a search engine and hope that they guess correctly what you want, but, you know, temporal strongly typed approach is perfect for solving this. All right. So here's what we know. We know the two calendar dates that the sessions occur on. We know the start times of the sessions. We know their time zones. We know my time zone. And we know the hours in my local time at which I'm willing to be at my computer. I'm obviously not getting up at, you know, 3 in the morning to go to a conference.

And so here's a bit of pseudocode for each session date for each session. Calculate the exact time of the session start and end on that date. Turn it into my local time in my time zone, and if it's within the hours that I want to be online, then I'll print it out and add it to my calendar. So I think maybe I can, like, unfullscreen this and switch to the browser console. Can you see this? I think it's really small. All right. Here we go. Yeah. Like I said, I wasn't sure how much time I have, so I input it beforehand.

But, you know, we've got our dates of the conference. We create temporal plane dates. We got our sessions. You might ask, like, how on earth do I get from an abbreviation like AEST to this identifier Australia slash Brisbane? You know, AEST is ambiguous. It could mean any number of time zones. These are unambiguous, and you can usually get them from Wikipedia. But yeah. Oh. What'd I do? Oh, no. All right. I'll stick to the code that I put in the presentation so that that doesn't happen again. Cool.

Sorry, everyone. Okay. All right. So this is what you saw in my browser console, basically. You know, we create those identifiers. We create a duration for the session length, and we get my time zone. There's an API to get it from the browser. You know, here's a little function I wrote. You know, I'll get up and be at my computer at maybe 8 o'clock, and I want to turn off my computer by 11 o'clock at night. And so I wrote a little function here to say, oh, I can be online between those times, and we use a compare method.

I won't go into all of the details of the API. I'll show you how it works. Put it all together. I had two loops of that pseudocode. You can see the two loops here with foreach. Calculate the session start in the conference time zone, calculate it in my time zone, check if I can be online at my session start and my session end. And if I can, then print it out. And we get something neat. Put the conference in your calendar at these times.

I wish I could have shown you in Firefox, but such are the vagaries of live demoing. Thanks. All right. So when everybody, of course, wants to know when can I use it. You know, you can already use it in Firefox. It's on caniuse.com and other sites that show you when APIs are available. So Firefox shipped it like just two weeks ago. So that's really cool. Safari has some of it available behind the flag in tech preview. If you want to get it shipped in Chrome and V8 and then from there in Node and stuff, there's actually an opportunity for you to get involved because Chrome is kind of doing their implementation together with the Boa JS engine. And they have a Rust crate called Temporal RS that's accepting contributions.

So if you like writing Rust code and you want to help two JavaScript engines get up to full implementation of Temporal, it's a great low friction opportunity to contribute. Just go here. GitHub slash Boa dash dev slash Temporal. If you want to learn more, it's fully documented on MDN, the website we all know and love. And I helped write a Temporal cookbook with common recipes that you might want to do using Temporal for all sorts of common tasks. And then I said at the very beginning I was going to come back about what a partnership with Igalia means. So we do a lot of stuff in standards, like trying to get good stuff into JavaScript and the web platform. We love open standards and the web. A lot of this work we do through collaborations with other companies. So if you're interested in collaborating with us on improving the state of the web platform, come talk to me or one of my colleagues. So if you do this sort of stuff, we're one of the maintainers of the Servo Browser, if you heard of that.

So yeah, come up and talk to us. And I see despite the tech hiccup, I'm here ready for questions with a minute to go. Thanks very much, Philip. Cool. So we have some questions come in. The first one, I think, is a really useful one. For people who want to use it right now, do you know a Temporal polyfill that you would use right now? Yeah, there are two that I think are ready to use. One I was involved in so I'll mention that one last. The other one is from Full Calendar. So I think it's called Full Calendar slash Temporal dash polyfill on GitHub. I've talked to one of the people who maintains it. And actually, he helped us find some bugs in the proposal. So that's really cool. The other one I've been involved in and some of the other people involved in the proposal. And we have that up at js dash Temporal slash polyfill, I believe. On GitHub? Yeah, both of those are on GitHub and on NPM. Nice. Nice. Awesome.

And I guess they're probably ESNs. You can sort of import them only if you need to. If you're running Firefox, you don't need to. That kind of... Right. Yeah. Right. Nice.

How much did the Java Temporal API influence this JavaScript one? I would say not directly as in we didn't look at the methods and say, oh, we need to have that method. Because that's how we got the original JavaScript data object. But this is actually a really interesting question.

Because Java actually pioneered a way of serializing time zone identifiers in strings that was not standard. They kind of tacked it on to this string format that everybody understands. And it kind of got out there and people started using it. And we wanted to use it in Temporal as well.

And we wanted to use it in Temporal as well. Because it's really useful for serializing the time zone that your event is in. And so because they pioneered it, we were actually able to go to the IETF and standardize that string format. And that was a whole journey. I could give a whole separate talk on that and I won't. Is that the Australia slash Brisbane format? Not quite. Yeah, those already existed separately. But you can what Java did was kind of like take that and put it in square brackets after your date and time. And so we did that too. And now it's been standardized. Nice. Nice. I do think it is funny to know that, yeah, the history of JavaScript dates were based on the original Java date function, right? And then all 30 years ago, right? And then Java went, oh, no, that was a mistake and changed it like a year later. And 30 years later, we're finally catching up. Yeah, we're catching up.

OK, so a question about the existing libraries for dates and stuff. Do you feel that Luxon, Date.js have a place now or are they obsolete? What's going on there? Does temporal wipe out a need for all of these? I mean, I wouldn't say that you need to delete them from your code immediately. Doing the job, yeah. The moment maintainers have said, moment, we consider it basically done. And if you want more, go use temporal. I think there's definitely also room for libraries to take tasks that were maybe too niche to be standardized in the language but still might be relatively common and build those on top of temporal. And I expect there's probably some stuff in things like Date.fns that falls into that category. Yeah, that makes sense.

I guess they don't just provide the fixes for the existing date format but also give a nicer way to use it as well. And if you liked that interface, you could probably build it over the top of temporal much easier. Or less code, probably. I'm actually hoping that somebody from the JavaScript developer community will take a look at Date.fns and write a temporal.fns to see what's missing and see what people want to use. If you're out there and you want to learn how temporal works, just rewrite Date.fns for temporal. Do it. Cool, there is a question about errors with string parsing.

What happens if there's explicit or invalid objects that you try and pass into temporal? Ah, well, string parsing is its whole... Like either the string is valid or it's not. And the string format has very clear rules on what's valid. So like day 32 of a month is not allowed. We throw on that. You can create temporal objects from property bags. And for those, we give you a bit more control over what's accepted. So you can ask for an exception to be thrown in the case of invalid data, or you can ask for it to be clamped to the right value. Nice. Nice.

So there's some extra bits in there to actually help out in the case of invalid stuff. Cool. And this is a great question, and it kind of speaks to a lot of what we see in getting new stuff into JavaScript, which is what's the most difficult aspects of getting the temporal proposal implemented? And I'll just add on to that. Like it does seem like it's taking quite a long time. And obviously, it's a complicated bit of code to write. But was some of that part of getting the proposal done as well? Yeah, I would say most of it is getting the proposal done. All the work is not code. As for writing the code, once you know what you have to write, it's fairly straightforward code. Not doing any wizardry here.

The hard part is figuring out what people actually want to achieve with their date and time. And yeah, we have kind of discussions, talking to users, talking amongst the people championing the proposal. That takes a lot of the time. And because there are so many tasks that people want to achieve with dates and times, it's the largest proposal that's ever been tried to merge into ECMAScript. It's going to change our lives. It's going to change our lives so much for the better when it gets there. And it's so cool. So there was a lot to discuss. Yeah. Yes. Cool.

I'm going to go with one last question, because I think we're right at the edge here. And I just... Yeah, I'm going to use this one. What's the advantage of temporal being immutable? That's not what we have with date right now, right? You can change those objects. So what does the immutability give us in temporal? The immutability just basically gives you the certainty that some library function won't modify your date object without you realizing it. Because maybe a library function will say, oh, this returns the object, but also mutates the original object. And you don't realize it, and you think you still have your old object somewhere. And then someone's sleeping on the streets. Yeah. And then you wake up again. Awesome.

Well, thank you so much, Philip. Let's give it one more round of applause for Philip. Excellent talk on that. Thank you. Thank you. Thanks so much.