npmjs.com/package/temporal-fun
Some countries start on a Friday or Saturday and until 2022 Iran could start any day of the week although never at 3AM.
Ramadan is observed from one visual sighting of a crescent moon to the next.
Cloud conditions may prevent sighting and thereby alter the official start of Ramadan for an individual location, and from time-to-time, the start of a country's change in timezone.
It's worth highlighting that André is actually a volunteer contributor who managed to implement the whole thing by themselves.
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.
[1] https://groups.google.com/g/comp.lang.python/c/Q2w4R89Nq1w
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.
This is not the case for Temporal objects. Also, the temporal objects have functions on them, which, granted, makes it convenient to use, but a pain to pass it over the wire.
I'd clearly prefer a set of pure functions, into which I can pass data-only temporal objects, quite a bit like date-fns did it.
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
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.
No-one seems to like this style, but I find it much simpler than converting on db read/write and passing datetime objects around.
The real drawback of the functional approach is UX, because it's harder to code and you don't get nice auto-complete.
But I'd easily pay that price.
This is effectively no different from Date:
serialize: date.toJSON()
deserialize: new Date(jsonDate)
serialize: instant.toJSON()
deserialize: Temporal.Instant.from(jsonDate)And as far as I know, date-fns deals with native Date instances, not “data-only objects.”
For example `JSON.parse(JSON.stringify(Temporal.PlainYearMonth.from({year:2026,month:1}))).subtract({ years: 1})` won't work, because it misses the prototype and is no longer an instance of Temporal.PlainYearMonth.
This is problematic if you use tRPC for example.
This is known as the "primitive obsession" anti-pattern.
Which makes me wonder how it'll look like when interfacing with WASM. Better than Date?
Given that the article refers to the "radical proposal" to bring these features to JavaScript came in 2018, surely Java's own solutions had some influence?
It’s not identical. The names of the “Plain” objects make a bit more sense to me than the “Local” names Java chose.
But overall easy to use and a fantastic improvement. I can’t wait to get to use it.
Congrats to all the champions who worked super hard on this for so long! It's been fun working on temporal_rs for the last couple years :)
Safari confirmed as IE Spiritual successor in 2020+.
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.
Safari is also pretty popular on iPhones, in fact it has a full 100% market share. With browser updates tied to the OS, that means millions of devices have those "temporary" problems baked in forever.
There wouldn't be Chrome-only sites and tools if Safari wasn't holding the web back (no "quotes" needed, as that's precisely what they're doing).
> Safari's problems are temporary.
What are you talking about? They've been woefully behind for like a decade. Here's an excellent article on the topic: https://infrequently.org/2023/02/safari-16-4-is-an-admission...
And an entire series: https://infrequently.org/series/browser-choice-must-matter/
This is funny to me; Java's util.Date was almost certainly a port of C's time.h API!
const today = Temporal.PlainDate.from("2569-03-11[u-ca=buddhist]");
today.toLocaleString("en", { calendar: "hebrew" });
> Uncaught RangeError: calendars "buddhist" and "hebrew" aren't compatibleAll 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).
today.withCalendar('hebrew').toLocaleString("en", { calendar: "hebrew" });
// "22 Adar 6329"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"
https://tc39.es/proposal-temporal/docs/cookbook.html
For example, calc days until a future date: https://tc39.es/proposal-temporal/docs/cookbook.html#how-man...
...or, compare meeting times across timezones: https://tc39.es/proposal-temporal/docs/cookbook.html#book-a-...
I wonder if it has a chance to replace chrono and jiff in the rust ecosystem.
That being said, the library is designed to be specification conformant and with EcmaScript implementations in mind. There are some specific API choices made specifically for those clients.
That being said, we are always looking for feedback regarding the native Rust API. So feel free to try temporal_rs out and provide whatever feedback you'd like :)
From the link, we can see Temporal does have separate Date/Time/Datetime types. ("PlainDate" etc)
I get HFT, but I have a hard time comprehending a need for a Bloomberg Terminal to be talking in picoseconds, as in fractions of a billionth of a second.
const D = new Temporal()
const t = new Interval({minutes:5})
const v = D.add(t) const D = Temporal.PlainDate.from("2020-06-16");
const t = Temporal.Duration.from({ day: 1 });
const v = D.add(t) // 2020-06-17
Period (https://docs.oracle.com/en/java/javase/21/docs/api/java.base...) is a date-based measure of time. 2 years, 3 months, and 4 days.
Interval (https://www.threeten.org/threeten-extra/apidocs/org.threeten...) isn't built into java.time, however, it is in the popular threeten-extra library. The docs say "An interval represents the time on the time-line between two Instants." The main difference being that Interval is anchored to the timeline while Duration and Period are not.
What I keep thinking about with Temporal is the adoption timeline question isn't really 'is it specced?' anymore, it's 'what minimum runtime version do I need?' Node.js, Deno, Bun all need to ship it stably, and then the practical floor for usage is wherever most prod environments are. The polyfill situation (@js-temporal/polyfill and others) doesn't really collapse until that happens.
So the speccing is done but I think we're still a couple of LTS cycles away from it being genuinely boring to reach for Temporal.
It's weird that they picked example code that is extremely non-accidentally doing this.
- new Date() equivalent in Temporal is `const now = Temporal.Now.zonedDateTimeISO();`.
- Date.now() equivalent is `Temporal.Now.instant().epochMilliseconds`
- It’s PascalCase, where JS is mostly snakeCase.
- nanoseconds per default. who needs that except Bloomberg? It should have been an option
It’s definitely great all the efforts put in place, but it’s not going to be a replacement to Date which such a complicated design.
But, still, let's look at your first couple of complaints.
To make #1 more explicit: If you want the equivalent of "new Date()", then as you observe you need to say something that's longer because it's more specific about what it's giving you. Why can't it just do the obvious simple thing, like Date does?
To make #2 more explicit: If you want the equivalent of "Date.now()", then as you observe you again need to say something that's longer because it's more specific about what it's giving you. Why can't it just do the obvious simple thing, like Date does?
Well, because as those two examples show there isn't actually an obvious simple thing. Two operations both of which one might expect to do the obvious simple thing do different things, and if there's some obvious way for someone who doesn't already happen to have the specs of Date memorized to know which one is "new Date()" and which one is "Date.now()", I don't know what it is.
So, to me, those first two examples look like pretty convincing evidence that Temporal is a better design and one that's less likely to lead non-experts to make serious mistakes.
... And then your other two complaints aren't actually about the API being "too complicated" at all! PascalCase isn't more complicated than snakeCase. Nanoseconds aren't more complicated than milliseconds.
(Also: "zonedDateTimeISO" and "epochMilliseconds" are in fact both snakeCase, and a quick look at the Temporal documentation suggests that this is the norm. Method names are snakeCase, class names are PascalCase. I am not a Javascript expert but isn't that pretty normal?)
I didn't spot how Temporal fixes this. What happens when "now" changes? Does the library get updated and pushed out rapidly via browsers?
Date is out, Temporal is in
perhaps don't be hard on them, Chrome released this to stable 2 months ago.
Not as bad as IE of old, but still seems to similarly be the odd one out always lagging half a year or more behind.
Har har.
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.
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.
Temporal is a blessing.
Outside of scheduling UTC is the way.
To represent this you probably don't want a local date. Plain times [1] and plain date/times [2] are a better fit.
[1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe...
[2]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe...
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.
A lesson I learned pretty early on is always use the date-time datatypes and libraries your language or platform gives you. Think very carefully before you roll your own with integer timestamps.
const now = new Date();
const now = Temporal.Now.zonedDateTimeISO();
I mean, I guess it's two steps forward and one step back ... but couldn't they have come up with something that was just two steps forward, and none back ... instead of making us write this nightmare all over the place?
Why not?
const now = DateTime();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.
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.
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.
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, ...
It's like witnessing a meteor shower!
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)
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.
You can read 150 comments in https://github.com/tc39/proposal-temporal/issues/707 if you want to understand the arguments made on all sides of this issue.
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.
Anyway, I hope this background is useful context.
It will take years until this can be widely used as intended.