Temporal: The 9-year journey to fix time in JavaScript (bloomberg.github.io)

Agreed. We've almost eradicated our usage of JS Date - fixing plenty of bugs along the way, and then I extracted thousands of lines of conversions and formatting from our production app (scheduling focused) into a temporal-fun package to make it Temporal more ergonomic for lots of common cases.

npmjs.com/package/temporal-fun

Technically, you're not likely to to have to fix a DST bug at 3AM any day but Sunday.

In this day and age when a natural language query can produce the most AbstractBeanFactoryFactoryBeanFactory boilerplate at the same rate as a much more concise equivalent, does verbosity matter as much?

Considering how prolific anba is, the only way we know he isn't an LLM is because he'd have to be several generations more advanced than the current SOTA. (It is possible that he might be an LLM from a few decades in the future, considering the connection to Temporal.)

anba implemented all of Temporal single-handedly, plus fixed up numerous places in the spec, plus migrated the implementation over some massive changes after other implementers discovered what a monster it all is. The original version of the spec kind of forced two separate internal implementation paths for everything, one for custom calendars and one for the built-in stuff, just to make the built-in one reasonably performant. That was a lot of work to implement, and a lot of work to remove. (I think ptomato shepherded the spec side of that?)

Fortunately, anba knows how to take a break, relaxing occasionally with minor tasks like rewriting large swathes of the JIT code generator to optimize the support on various platforms. He also gets plenty of nutrition, by ingesting entire specs and mind-melding with them.

Thank you thank you thank you.

Parsing dates with anything other than fromisoformat feels totally backwards in comparison. We were using ciso8601 until fromisoformat was in the standard library. And now things are incredibly simple and reliable.

I would characterize it more as Joda likely informed Moment.js, which better informed TC39 because it was within the JavaScript ecosystem. As we discussed in plenary today when achieving consensus, every programming language that implements or revamps its date time primitives has the benefit of all the prior art that exists at that instant. TC39 always casts a wide net to canvas what other ecosystems do, but isn't beholden to follow in their footsteps and achieves consensus on what is best for JavaScript. So my view is this more represents what the committee believes is the most complete implementation of such an API that an assembled group of JavaScript experts could design over 9 years and finalize in 2026.

Yep, JavaScript got the bad version from Java too!

https://news.ycombinator.com/item?id=42816135

This was an intentional design decision. We wanted to make sure all the temporal types could be serialize/deserializable, but as you mentioned, you couldn't implicitly go back to the object you started with as JSON.parse doesn't support that.

Instead the onus is on the developer to re-create the correct object they need on the other side. I don't believe this is problematic because if you know you're sending a Date, DateTime, MonthDay, YearMonth type from one side, then you know what type to rebuild from the ISO string on the other. Having it be automatic could be an issue if you receive unexpected values and are now dealing with the wrong types.

There is an example here in the docs of a reviver being used for Temporal.Instant https://tc39.es/proposal-temporal/docs/instant.html#toJSON

This is a real pain point and I run into the same tension in systems where data crosses serialization boundaries constantly. The prototype-stripping problem you're describing with JSON.parse/stringify is a specific case of a more general issue: rich domain objects don't survive wire transfer without a reconstitution step.

That said, I think the Temporal team made the right call here. Date-time logic is one of those domains where the "bag of data plus free functions" approach leads to subtle bugs because callers forget to pass the right context (calendar system, timezone) to the right function. Binding the operations to the object means the type system can enforce that a PlainDate never accidentally gets treated as a ZonedDateTime. date-fns is great but it can't give you that.

The serialization issue is solvable at the boundary. If you're using tRPC or similar, a thin transform layer that calls Temporal.Whatever.from() on the way in and .toString() on the way out is pretty minimal overhead. Same pattern people use with Decimal types or any value object that doesn't roundtrip through JSON natively. Annoying, sure, but the alternative is giving up the type safety that makes the API worth having in the first place.

Updating JSON.parse() to automatically create Temporal objects (from what shape of JSON value?) without a custom reviver would be a step too far, in my opinion.

This is effectively no different from Date:

  serialize: date.toJSON()
  deserialize: new Date(jsonDate)

  serialize: instant.toJSON()
  deserialize: Temporal.Instant.from(jsonDate)

The serialization thing is real but I don't think OOP vs functional is the actual issue here. JSON has no date type, period. You JSON.stringify a Date, get an ISO string, and hope whoever's parsing remembers to reconstruct it. Temporal doesn't fix that part, but at least when you do reconstruct you're saying "this is a ZonedDateTime" vs "this is an Instant" instead of everything being one ambiguous Date object.

Don’t JavaScript Date instances have the same problem? Date implements toJSON, but when parsing JSON you’ll have to manually identify which string values represent Dates and convert them back to Date instances. The exact same is true of Temporal (e.g. Instant).

And as far as I know, date-fns deals with native Date instances, not “data-only objects.”

All Temporal objects are easily (de)serializable, though. `.toString` and `Temporal.from` work great.

I'm with you on this. I worked on a big Temporal project briefly and I was really turned off by how much of the codebase was just rote mapping properties from one layer to the next.

> Especially in JavaScript where I often share a lot of code between the client and the server and therefore also transfer data between them, I like to strictly separate data from logic

Which makes me wonder how it'll look like when interfacing with WASM. Better than Date?

It should still be possible to continue using date-fns (or a similar lib) to suit your preference, right?

Converting between solar-based and lunar-based calendars is fraught with potential for ambiguity. The Buddhist calendar is a solar calendar, while the Hebrew calendar is lunar-based. So converting between dates in the Buddhist calendar and the international-standard (ISO 8601) calendar is typically easy (give or take some subtleties I won't go into for reasons of length). But converting between the Hebrew calendar and the ISO 8601 calendar, or the Buddhist calendar, involves figuring out when the new moon will be — and since the lunar cycle is 29 or 30 days, 12 lunar months add up to 354 days. So the lunar calendars, including the Hebrew calendar, typically add a "leap month" every two or three years in order to track the sidereal year.

All of which means there are many potential ambiguities in converting between calendars, and the combinatorial explosion possible means they probably only want you to convert between non-ISO8601 calendars and ISO8601. It would be too easy to get corner cases wrong otherwise and not notice, I'm sure. So to convert a date from Buddhist calender to Hebrew calender, you'd probably have to do Buddhist -> ISO8601, then ISO8601 -> Hebrew. (I haven't had time to test that for myself yet, I'll post a correction if that turns out to be wrong).

I think this is intentional design. Anyway we can convert `Temporal.PlainDate` to other calendars explicitly (I believe explicitness is good here).

  today.withCalendar('hebrew').toLocaleString("en", { calendar: "hebrew" });
  // "22 Adar 6329"

Certainly surprising

One of my favorite interview questions is asking a candidate to, piece meal, build a calendar. They start with Julian, and then write converters to and from other calendars. Any calendar can be converted to any other, by going through Julian

I got the idea from the book "calendrical calculations"

Slower to implement new features, but still implementing them, just makes it the new Firefox. IE's larger problem was how popular it had been before it stopped implementing new features. It was like if Google got bored with Chrome and decided to stop all funding on it. People would be stuck on Chrome for years after that investment stopped because of all the Chrome-specific things built around it (Electron, Puppeteer, Selenium, etc and so forth).

Right now the world needs a lot more Safari and Firefox users complaining about Chrome-only sites and tools than it does people complaining about Safari "holding the web back". Safari's problems are temporary. Chrome is the new Emperor and IE wasn't bad because it stopped, it was bad because it stopped after being the Emperor for some time. People remember how bad the time was after the Empire crumbled, but it's how IE took so many other things down with it that it is easier to remember the interregnum after IE crumbled than to remember the heyday when "IE-only websites are good enough for business" sounded like a good idea and not a cautionary tale.

2026 A.D., still no support for native date pickers in mobile Safari.

Deno has had it behind the `--untable-temporal` flag for quite a few Minor versions now and the latest Minor update (because of TC-39's Stage 4 acceptance and V8 itself also marking the API as Stable) removed the requirement for the flag and it is out of the box.

Node 26! Only a matter of time... :)

FWIW, I've been using it server-side via the js-temporal polyfill for some time, no issues.

ai;dr

I wouldn't be surprised to see the Rust ecosystem eventually move to Temporal's api, given v8 (Chrome) adopted Boa's rust implementation temporal_rs (https://docs.rs/temporal_rs/latest/temporal_rs/), see burntsushi's arguments for the need of a better datetime handling library in Rust (https://github.com/BurntSushi/jiff/blob/master/DESIGN.md#why...). I'm not sure his jiff create will be the one, i think temporal_rs has become the authoritative implementation.

Yes, please try! One of the main motivations for doing all this work is to slim down both the amount of code that has to be delivered and executed by providing everything that's needed by the platform. In addition, you're slimming the potential bug/attack surface as well, which is always nice.

An example that is hard to follow defeats the point. It's just showing what pattern is possible and you can imagine the abstraction layers and indirection that would make it happen accidentally.

That's Duration!

    const D = Temporal.PlainDate.from("2020-06-16");
    const t = Temporal.Duration.from({ day: 1 });
    const v = D.add(t) // 2020-06-17

It is called Duration.

Right, browsers own it instead of websites needing to rebuild Moment.js bundles. Additionally, most browsers pass the ownership further to the user's OS as the IANA timezone database is a useful system-level service and best updated at the cadence of OS "required" updates.

Typically time zone data is updated in IANA's time zone database. That data would need to be updated in the implementation. In this case, the browser would need to update their time zone data.

Depending on the situation, the data lives either within the browser or within the OS. Chrome releases ship versions of tzdata that correspond to the version of tzdata shipped with the ICU it uses, and they do backport updates to prior Chrome releases within a certain window. Apple has a sideband way of deploying tzdata to all devices that doesn't appear via the normal Software Update mechanism. So it all depends on which particular OS/browser combo you're interested in and the decisions those owners made.

They've been working on support for a while (years), eg this 2022 commit. https://github.com/WebKit/WebKit/commit/e6717cdeb6a841f4b1f6...

perhaps don't be hard on them, Chrome released this to stable 2 months ago.

I usually am not too harsh on Safari on implementation of new features but this is a bummer, and reflects poorly on them

And I have to support safari while dealing with all the problems that are mentioned in this article. Maybe there is a polyfill.

there's plenty of polyfills for every new JS idea on the roadmap

For recording instantaneous events, that's usually sufficient. It's often not enough for scheduling. You can always present UTC or any other zone relative to some other zone, but you need to know that zone. Maybe you're going to a conference in another region and you want to know the time of a talk in that zone because that's more important than your zone. You either need to couple the zone with the time itself, or you need to refer to it. There are good reasons either way. Having an atomic time+zone type is basically trading space for time. When its embedded, you can just use it, which can be better than assuming UTC and then looking up the zone based on, say, the location of the venue.

Storing in UTC is lossy. You've lost information about the event's original UTC offset, at the very least, and probably also its original time zone. Most backends today have good ways to round-trip offset information, and still compare dates easily (as if they were normalized to UTC). Some backends can even round-trip timezone information in addition to offsets.

It's easy not to feel that loss as a big deal, but captured offsets can be very helpful for exactly debugging things like "what time did this user think this was?" versus time zone math (and DST lookups) from UTC. It can help debug cases where the user's own machine had missed a DST jump or was briefly on a different calendar or was traveling.

But a lot of the biggest gains in Temporal are the "Plain" family for "wall clock times"/"wall calendar dates" and breaking them apart as very separate data types. Does a UTC timestamp of "2026-02-01 00:00:00Z" mean midnight specifically and exactly or where you trying to mark "2026-02-01" without a time or timezone. Similarly I've seen data like "0001-01-01 12:10:00Z" mean "12:10" on a clock without the date or timezone being meaningful, but Temporal has a PlainTime for that. You can convert a PlainDate + a PlainTime + a Time Zone to build a ZonedDateTime, but that becomes an explicit process that directly explains what you are trying to do, versus accidentally casting a `Date` intended to be just a wall-clock time and getting a garbage wall-clock date.

That generally works for timestamps (Temporal Instant). But it doesn’t work for representing calendar dates with no time information (Temporal PlainDate) unless you add an additional strict convention like “calendar dates are always represented as midnight UTC”).

The only time you need local dates is for scheduling. Stuff like “Report KPIs for each shift. Shifts start at 8:00 local time.”, or “send this report every day at 10:00 local time”, or “this recurring meeting was created by user X while they were in TimeZone Z, make sure meetings follow DST”.

Outside of scheduling UTC is the way.

It does work quite well. Sometimes you need a time zone to go with it. It might not be common, but sometimes you need to know the local time in a particular zone, which is not necessarily where the user is. I work on software that works with local times in arbitrary time zones. We submit data in a schema over which we have no control, which must include such local times that may or may not be in the time zone of the server or the current client machine.

I have a scheduling system that allows users to specify recurring events. "Every Monday at 2pm." Which needs to be understood in the native timezone of that user and needs to be capable of being displayed in that timezone for all viewers or optionally in the native timezone of the viewing user.

Temporal is a blessing.

"Just use UTC" is another, albeit more subtle, falsehood programmers believe about date/time.

It's fine for distributed logging and computer-only usage, but fails in obscure ways once humans, time zones, travel, laws, and/or daylight saving time get involved.

If you're scheduling events for humans, and can't immediately list the reasons your app is an exception to the above, store the time zone to be safe. You probably don't have big data, and nobody will notice the minuscule overhead.

why UTC and not epoch then?

Same here, this is the way

The spec hasn't even reached stage 4 yet. Chrome only added support 58 days ago. Safari already added support in their alphas.

I'd argue that `new Date()` returning the current time is a design mistake, and it should at least have been something like `DateTime.now()`. (Especially because it's called a date but it actually returns a timestamp: the footgun potential is large). C#'s date API isn't the best design (otherwise [NodaTime](https://www.nodatime.org/) wouldn't have been necessary) but it at least got some things right: you don't get the current time by doing `new DateTime()`, you get it by referencing `DateTime.UtcNow` for UTC (almost always what you want), or `DateTime.Now` for local time (which is sometimes what you want, but you should always stop and think about whether you really want UTC).

And even with C#'s date API, I've seen errors. For example, a library that formatted datetime strings by merely writing them out and adding a "Z" to the end, assuming that they would always be receiving UTC datetimes — and elsewhere in the code, someone passing `DateTime.Now` to that library. (I'm guessing the dev who wrote that was in the UK and wrote it during winter time, otherwise he would have noticed that the timestamps were coming out wrong. If he was in the US they'd be 4-7 or 5-8 hours wrong depending on whether DST was in effect. But in the UK during winter, local time equals UTC and you might not notice that mistake).

This is another reason why Temporal's API making clear distinctions between the different types, and requiring you to call conversion functions to switch between them, is a good idea. That C# mistake would have been harder (not impossible, people can always misunderstand an API, but harder) if the library had been using Nodatime. And Temporal is based on the same design principles (not identical APIs, just simmilar principles) as Nodatime.

That’s uglier because, if you were previously doing new Date(), you almost certainly don’t want a zonedDateTime. You almost certainly want an Instant.

Firstly, I really want this also and am supportive of an opinionated decision to put something at say Temporal.DateTime() that would be logical for developers to use ‘most of the time’.

However my guess is that the spec designers saw this lack of specivity as part of the problem.

A key issue of dates and times is that we use them culturally in day to day use in very imprecise ways and much is inferred from the context of use.

The concepts of zoned time and “wall clock” time are irreducable and it’s likely much code will be improved by forcing the developer to be explicit with the form of time they want to use and need for their particular use case.

I think this is why it’s so explicitly specified right now.

But I agree; I’ve often struggled with how verbose js can be.

Maybe with time (pun intended), more syntactic sugar and shorter conventions can be added to expand what has been an incredible effort to fix deep rooted issues.

I think that it's nice it's explicit that the method returns the current instant, rather than some other zero value.

There's also other methods that return other types, like

    const now = Temporal.Now.instant()

One could argue that the ugliness of the API intentionally reveals the ugliness of datetime. It forces you to really think about what you mean when you want "the current date time," which I think is one of the goals of the API.

I also find it super more complicated and messy than what you can find in another language without proper justification.

Like the Temporal.Instant with the only difference that is now but in nanosecond. Would have been better to be Now with a suffix to indicate that it is more precise. Or even better, it is just the function you use or parameter that give the precision.

And why Now as the name space? I would expect the opposite, like python, you have something like Temporal.Date, and from there you get a date of now or a specific time, with or without timezone info, ...

Or const now = new Temporal();

If you give me your background I'll explain in longer terms but in short it's about making the intent clear and anyone who understands s modicum of PL theory understands why what's a constant is so and what's a function is so.

Yep. You can learn more about why we created this new blog here:

  https://bloomberg.github.io/js-blog/post/intro/

And if it seems like a surprise, you can blame me for not publicising this kind of content earlier given how long we've been working in this area. Thankfully Jon Kuperman and Thomas Chetwin (plus others) found the time and energy to put this platform together.

Bloomberg has a pretty large software engineering department, including a lot of offshore contractors. Similar to Walmart Labs that does cool stuff as well, despite being part of a retail chain (retail industry typically sees SWEs a cost, not asset).

What surprises you? Terminal UI is written in JS using Chromium. It’s not just plain Chromium, but it’s still funny that it’s pretty much same approach as universally (according to HN and Reddit) hated Electron.

https://youtu.be/uqehwCWKVVw?is=wBijGwdD2k2jIOu7

More like a copy of Java’s JSR310, which in turn took many years to get right.

The worst are methods that both mutate and return values.

I know this gets into a complex land of computer science that I don’t understand well, but I wish I could define in TypeScript “any object passed into this function is now typed _never_. You’ve destroyed it and can’t use it after this.” Because I sometimes want to mutate something in a function and return it for convenience and performance reasons, but I want you to have to reason about the returned type and never again touch the original type, even if they are the same object.

These LLM spambots are getting so good they're at the top of many discussions now, and people are none the wiser. Sad, but it was predictable.

Please look into its comment history and flag this. Not that it will solve anything.

> The other half come from the implicit local timezone conversion in the Date constructor.

Outlook at that issue even in their old C++ (I think) version.

You're in London, you save your friend's birthday as March 11th.

You're now in SF. When is your friend's birthday? It's still all-day March 11th, not March 10th, starting at 5PM, and ending March 11th at 5PM.

Immutability is underrated in general. It's a sore point every time I have to handle non-clojure code.

Yeah... I pretty early in my career firmly cemented on a couple things with date-times. It's either a date-time + zone/location detail or always seconds from unix epoc or UTC in iso-8601 style (later JSON's adopted default) across the wire. Since most systems and JS convert pretty easily between UTC and local.

Same for storage details. I started using the 8601 style mostly in file/log naming so they always sorted correctly, this kind of carried over into my code use pre-dating JSON spec.

Doing the above saves a lot of headaches... I'd also by convention use a few utility scripts for common formatting and date changes (I use date-fns now mostly), that would always start with dtm = new Date(dtm); before manipulation, returning the cloned dtm.

It is not just in time keeping that mutable shared state is an issue, I have seen problems arising from it elsewhere as well in Python especially, but also in C and C++. Probably because Python is pass by reference implicitly, while C and C++ makes pointers/references more explicit, thus reducing the risk of such errors in the code.

There a few schools of thought about what should be done about it. One is to make (almost) everything immutable and hope it gets optimised away/is fast enough anyway. This is the approach taken by functional languages (and functional style programming in general).

Another approach is what Rust does: make state mutable xor shared. So you can either have mutable state that you own exclusively, or you can have read only state that is shared.

Both approaches are valid and helpful in my experience. As someone working with low level performance critical code, I personally prefer the Rust approach here.

One of the first things I learnt to appreciate in C++ already during its C++ARM days was the ability to model mutability.

Naturally there are other languages that do it much better.

The problem is that it still isn't widespread enough.

When I write JavaScript, I make as many things immutable as I can. Sometimes it adds verbosity and leads to less efficient computational patterns, but overall I believe I run into far fewer bugs that are hard to make sense of. There are things about the design of Temporal I don't really like, but immutability was a solid move.

What I don't understand is why they had to make string formatting so rigid. Maybe it has to do with internationalization? I'd have liked if it included a sort of templating system to make the construction of rendered date-time strings much easier.

They seem to have taken it from Joda time that revolutionized time in java 10+ years ago. Sadly no mention of Joda.

I think that actually may be the MOST appreciated design decision in Temporal ;) either way, I'm also a big fan

Flagged because account is bot operated (posted again 2h40m later with same general comment)

Your bot messed up and posted twice in the same thread.

Assuming this isn’t an LLM bot, I don’t see how you ship that bug multiple times. The docs for JS time are pretty minimal and it’s clear it only stores UTC epoch, so why would you assume it can handle “wall clock time” with no other context?

It doesn’t matter if it’s python or tsql or JS or perl — you read the docs on the date time impl every time.