I'm one of the volunteer open-source folks (called "proposal champions" in TC39 parlance) who designed the Temporal API. Sorry for the late reply, as you can imagine it's been a busy week for us.
You raise a very important question: why is `Temporal.Now.zonedDateTimeISO()` so verbose? After 10 years of work on Temporal, you can assume that every API design and naming decision has been argued about, often many times. I'll try to summarize the reasoning and history below to explain how we got there.
There's really five questions here. There's no perfect order to answer them because the answers overlap somewhat, so you may want to read to the end until disagreeing. :-) I will have to split this response up into two posts because it's long.
1. Why do we need `Temporal.Now.`? Why not just `Temporal.`?
The TC39 members working on security required us to have a forward-compatible way to override and/or prevent access to information about the local machine. With the current design, a hosting environment can monkey-patch or remove `Temporal.Now`, and regardless of what Temporal changes in the future that local-machine info will still be blocked or overridden. But if we'd spread methods across each Temporal type (e.g. `Temporal.PlainDate.today()`, `Temporal.Instant.now()`) then a new Temporal type added in the future could allow jailbreaking to get local machine info.
This isn't just a security concern. Environments like jest may want to control the local time that tests see. Hosters of JS code like https://convex.dev/ might want to override the local time so that transactions can be re-run deterministically on another node. And so on.
2. Why a `Temporal.*` namespace? Why not just `ZonedDateTime`, `PlainTime`, etc. in the global namespace?
If `Date` didn't exist, we'd probably have done exactly this, and argued harder about (1) above, and we maybe could have won that argument!
But we were worried about the confusion between `Date` and another type named `PlainDate` (or whatever we could have called the date-only type). By putting all Temporal types in a namespace, it was much harder to be confused.
A secondary benefit of a namespace was to expose developers (via autocomplete in editors and browser dev tools) to the full set of types available, so that developers would pick the right type for their use case. But the `Date` conflict was the main reason.
We could have made the types TemporalDate, TemporalTime, etc. but that shaves only one character and violates (1) so there was no chance that would move forward. So we went with a namespace.
3. Why is it `Temporal.Now.zonedDateTimeISO()` not `Temporal.now()`?
As @rmunn and others discuss below, one of the core tenets of Temporal (following in the footsteps of Java, Noda time, Rust, and many others) was that developers must figure out up-front what kind of date/time data they want, and then pick the appropriate Temporal type for that data.
For a canonical example of why this is needed, just think of the thousands (millions?) of times that JS developers or end users have ended up with off-by-one-day errors because `new Date()` reports a different date depending on which time zone you're in, even if all you care about is displaying a date where the time zone is not relevant.
It's a reasonable argument that because `Temporal.ZonedDateTime` represents the superset of all Temporal types, it should occupy a privileged position and should be the default Temporal type for something like `Temporal.now()`. Given that I proposed the initial design of the ZonedDateTime type (https://github.com/tc39/proposal-temporal/pull/700) I'm understandably sympathetic to that point of view!
But there are performance concerns. Accessing the system time zone and calendar not free, nor is the extra 2+ bytes to store them in a `Temporal.ZonedDateTime` implementation compared to a cheaper type like `Temporal.Instant`. This also would have popularized a pattern of calling `Temporal.now().toPlainTime()` which creates two objects vs. just creating the desired type in one call via `Temporal.Now.plainTime()`.
4. Why is it `Temporal.ZonedDateTime` not `Temporal.DateTime`?
This is a fun story. Originally there was no `Temporal.ZonedDateTime`, and the type now called `Temporal.PlainDateTime` was called `Temporal.DateTime`. When we added a Temporal type with a datetime + time zone (its placeholder name was LocalDateTime), we needed to figure out naming for the date+time types so that developers would pick the right one: if they knew the time zone then they should pick one, and if they didn't know the time zone then they should pick the other.
The biggest danger was this: if the zoneless type had been named `Temporal.DateTime`, then developers new to JS would almost certainly use it because it sounds like it should be the default. This exposes programs to subtle time zone bugs that only manifest 2x per year when time zones switch from DST/"Summer Time" to standard time and back again.
I'd seen my previous company take two years (!!!) and thousands of hours of developer time to fix exactly this bug because many years before that our 23-year-old founders didn't realize that `DATETIME` in SQL Server was a zoneless type that would skip or lose an hour twice per year.
I was determined to reduce the chance of the same mistake with Temporal by ensuring that the zoneless type would not (like in SQL Server) look like the default type that everyone should use for date/time data.
Naming is hard! My preference was to use "DateTime" for the zoned type, and an something obviously non-default like "ZonelessDateTime" for the other one. Other champions felt the opposite: that because we were adding a time zone then its name should be longer. Eventually we settled on "Plain*" for all zoneless types and "ZonedDateTime" for the DST-safe one.
5. Why is it `Temporal.Now.zonedDateTimeISO()` not `Temporal.Now.zonedDateTime()`?
I tried. The presence of "ISO" in method names (of `Temporal.Now` and a few other Temporal methods) is my biggest regret in the 6 years I spent working on this proposal. That said, it could have been even worse. Here's some history.
"ISO" in this context refers to the ISO 8601 calendar, as opposed to the Chinese calendar, the Hebrew Calendar, the Coptic calendar, the Persian calendar, one of several Islamic calendars, and of course the Gregorian calendar which is effectively the same as ISO 8601 except the former uses BC/AD eras.
One of the features of Temporal is to support both Gregorian and non-Gregorian calendars. Most of the world's population uses a non-Gregorian calendar for some purposes, like determining holidays or for official government documents. So it's convenient that user can write code like this:
// What's the date of the next Chinese new year?
Temporal.Now.zonedDateTimeISO()
.withCalendar('chinese')
.add({ years: 1 })
.with({ month: 1, day: 1})
.toPlainDate()
.withCalendar('gregory')
.toLocaleString()
// => '2/6/2027'
In 10 years of working on Temporal, the argument that took more hours and frustration was whether we should default to the ISO calendar in Temporal APIs.
One side of this argument was this: in localization, you never want a default locale because then developers won't write or test their code to work in other locales. For languages this is exactly the right approach because there is no default language worldwide that everyone knows. Therefore, we should not have a default calendar in Temporal.
The other side of that argument was this: the Gregorian calendar is used in almost every country in the world for almost all use cases that software will need to handle. Exceptions prove the rule, because the most common use of non-Gregorian calendars in software is building apps that correlate Gregorian with another calendar so that multi-calendar users can see both dates side-by-side. Therefore, we should make era-less Gregorian (called the ISO 8601 calendar in JS) the default calendar in Temporal.
After many hours of discussion, it was clear that neither side could convince the other. So we made a painful compromise: we'd have two variations of APIs. Methods like `Temporal.Now.zonedDateTimeISO()` would use the ISO 8601 calendar by default, and methods like `Temporal.Now.zonedDateTime()` would require the user to provide a calendar or would throw a `RangeError`.
This compromise was not ideal because it would confuse developers who'd call the shorter ISO-less methods and end up with exceptions at runtime. In 2023 we had an opportunity to improve it somewhat, because Temporal had to trim about a third of the surface area of the the proposal (IIRC, about 100 properties and methods!) to address concerns from browser implementers about the RAM and download size impact of so much new code on devices like Apple Watch and low-end Android phones.
As part of that trimming exercise, we decided to remove one of the ISO-default vs. calendar-required method pairs. Thankfully, the ISO-default variant was retained. I lobbied to remove "ISO" from the method names, now that differentiating them from their calendar-required counterparts was not required anymore. This lobbying didn't succeed. See https://github.com/tc39/proposal-temporal/issues/2846 for details.
I'm not happy with the extra `ISO` that millions of developers and AI agents will have to be typing in the decades to come. But in the grand scheme of things this is a small price to pay for a dramatically improved date/time/timezone/calendar API. Building standards is inherently a team sport, and if you're winning every argument then it's probably an unhealthy team. Overall I'm quite happy where we ended up with Temporal, even if some of the decisions didn't match what I thought would be best.
This is a big milestone to getting Temporal shipped in Chrome (unflagged), which will have huge positive on JS developers around the world. Thank you all for your hard work to get this built and over the finish line.
Yep. That said, for end users it's a fairly good story because consumer OSs have gotten very good at automatically adjusting clients' time zone based on geo-location. Just like when you fly to another country and the first thing that happens when you connect your laptop to the internet is you're offered to change your time zone to the local time zone. I assume that the same thing happens when you're in a place whose IANA time zone changes like your America/Punta_Arenas case or many others like it.
> https://github.com/tc39/proposal-canonical-tz - appropriately to these comments, a proposal to handle tzdb changes, built on top of JS Temporal, includes some great examples of all the ways this can happen
Thanks! I was the co-champion of that proposal. Parts of it were merged into Temporal last year, and other parts are already part of the JS Internationalization (ECMA-402) specification here: https://tc39.es/ecma402/#sec-use-of-iana-time-zone-database
There's no geographic adjustment but at least there is some choice for users about which Islamic calendar variation should be used. For example, "islamic-rgsa" in JS is the Hijri calendar, Saudi Arabia sighting.
Temporal has built-in support for non-Gregorian calendars, including parsing, arithmetic, etc. so you can do things like this:
function chineseNewYears() {
const dt = Temporal.Now.plainDateISO().withCalendar('chinese');
const current = Temporal.PlainDate.from({year: dt.year, month: 1, day: 1, calendar: 'chinese'})
const next = current.add({years: 1})
return { current, next }
}
`The next Chinese New Year is ${chineseNewYears().next.withCalendar('gregory').toLocaleString('en-UK')}`
// => 'The next Chinese New Year is 17/02/2026'
Temporal includes `equals` methods on every type. String comparison sometimes works, but there are enough cases where it doesn't (especially when comparing strings that refer to the same data but were generated by different libraries so formatting is different for things like trailing zeroes of decimals, time zone aliases, etc.) that it's usually best to use a library function for comparison instead of just using string comparison.
You raise a very important question: why is `Temporal.Now.zonedDateTimeISO()` so verbose? After 10 years of work on Temporal, you can assume that every API design and naming decision has been argued about, often many times. I'll try to summarize the reasoning and history below to explain how we got there.
There's really five questions here. There's no perfect order to answer them because the answers overlap somewhat, so you may want to read to the end until disagreeing. :-) I will have to split this response up into two posts because it's long.
1. Why do we need `Temporal.Now.`? Why not just `Temporal.`?
The TC39 members working on security required us to have a forward-compatible way to override and/or prevent access to information about the local machine. With the current design, a hosting environment can monkey-patch or remove `Temporal.Now`, and regardless of what Temporal changes in the future that local-machine info will still be blocked or overridden. But if we'd spread methods across each Temporal type (e.g. `Temporal.PlainDate.today()`, `Temporal.Instant.now()`) then a new Temporal type added in the future could allow jailbreaking to get local machine info.
This isn't just a security concern. Environments like jest may want to control the local time that tests see. Hosters of JS code like https://convex.dev/ might want to override the local time so that transactions can be re-run deterministically on another node. And so on.
2. Why a `Temporal.*` namespace? Why not just `ZonedDateTime`, `PlainTime`, etc. in the global namespace?
If `Date` didn't exist, we'd probably have done exactly this, and argued harder about (1) above, and we maybe could have won that argument!
But we were worried about the confusion between `Date` and another type named `PlainDate` (or whatever we could have called the date-only type). By putting all Temporal types in a namespace, it was much harder to be confused.
A secondary benefit of a namespace was to expose developers (via autocomplete in editors and browser dev tools) to the full set of types available, so that developers would pick the right type for their use case. But the `Date` conflict was the main reason.
We could have made the types TemporalDate, TemporalTime, etc. but that shaves only one character and violates (1) so there was no chance that would move forward. So we went with a namespace.
3. Why is it `Temporal.Now.zonedDateTimeISO()` not `Temporal.now()`?
As @rmunn and others discuss below, one of the core tenets of Temporal (following in the footsteps of Java, Noda time, Rust, and many others) was that developers must figure out up-front what kind of date/time data they want, and then pick the appropriate Temporal type for that data.
For a canonical example of why this is needed, just think of the thousands (millions?) of times that JS developers or end users have ended up with off-by-one-day errors because `new Date()` reports a different date depending on which time zone you're in, even if all you care about is displaying a date where the time zone is not relevant.
It's a reasonable argument that because `Temporal.ZonedDateTime` represents the superset of all Temporal types, it should occupy a privileged position and should be the default Temporal type for something like `Temporal.now()`. Given that I proposed the initial design of the ZonedDateTime type (https://github.com/tc39/proposal-temporal/pull/700) I'm understandably sympathetic to that point of view!
But there are performance concerns. Accessing the system time zone and calendar not free, nor is the extra 2+ bytes to store them in a `Temporal.ZonedDateTime` implementation compared to a cheaper type like `Temporal.Instant`. This also would have popularized a pattern of calling `Temporal.now().toPlainTime()` which creates two objects vs. just creating the desired type in one call via `Temporal.Now.plainTime()`.
(cont'd in next post)