js-temporal / temporal-developer-education Goto Github PK

Originally from tc39/proposal-temporal#105

How does Temporal compare to date-time libraries in other programming languages, and to JavaScript date-time libraries in the ecosystem?

C#

• DateOnly
• DateTime
• DateTimeOffset
• TimeOnly
• TimeSpan
• TimeZoneInfo
• For .NET, NodaTime
• in-progress .NET equivalent to ZonedDateTime

Java

The joda-time library that resulted in JSR-310 and became part of the language in Java 8.

Comparison already done: http://widdindustries.com/ecma-temporal-vs-java-time/

JavaScript

• date-fns (docs)
• Moment.js
• Luxon
• dayjs

Brief overview of the JS libraries above: https://github.com/you-dont-need/You-Dont-Need-Momentjs#brief-comparison

PHP

• DateTime (built-in)
• Carbon
• (+ every larger PHP framework rolls their own, but not sure if relevant to include...)

Python

• datetime (built-in)
• zoneinfo (built-in, Python 3.9+)
• dateutil
• arrow

Rust

• chrono
• https://github.com/rust-lang/rust-wiki-backup/blob/master/Lib-datetime.md

Originally from tc39/proposal-temporal#861

A page with guidance for library authors could include:

• What types should my library accept as input, and in what use cases?
• What types should my library emit as output, and in what use cases?
• Be careful of implicit assumptions, especially around time zones. For example, Brazil's missing midnight after a DST transition. In a future where a date-picker library is built using Temporal, it might seem fine for it to accept and/or return a DateTime because no time zone is shown or accepted in the UI. But if the library's implementation is making assumptions that require a time zone, then using ZonedDateTime might be more appropriate for the use case.
• Serialization and deserialization, including custom formats and interop with other systems. This includes parsing and formatting guidance, but also includes guidance for how to handle limitations and incompatibility between Temporal and other platforms. For example, if your library pulls an OffsetDateTime from a Java or .NET web service, how should that value be represented in Temporal?
• How to migrate the implementation of a library from moment, date-fns, legacy Date, etc. ? What changes and problems to expect?

There's some overlap with user-facing guidance, but I suspect that some of the issues that library authors run into (e.g. how to pick types properly to minimize their users running into errors) might be unique to libraries.

Justin Grant tweeted a challenge to verify Temporal against https://yourcalendricalfallacyis.com/: https://twitter.com/justingrantjg/status/1305590409268064256

We should have a page responding to each of these fallacies explaining how Temporal meets or doesn't meet them. Not all are applicable.

Archiving the Twitter thread in case of unavailability:

@justingrantjg

The best way to get help online is to boldly claim something falsifiable, so... I assert that https://github.com/tc39/proposal-temporal will handle all of http://yourcalendricalfallacyis.com.

Think I'm wrong? Prove it at tc39/proposal-temporal#893

@devongovett

My claim was that none of the existing popular libraries handle this. I’m excited about Temporal for sure!

One thing Temporal explicitly doesn’t handle according to the readme is leap seconds. Unclear to me how that would manifest. Several of the fallacies make mention of that though.

@justingrantjg

Yeah, Temporal won't crash from leap seconds (treat 23:59:60 as 23:59:59 when parsing) but leap seconds may be better handled via building a custom TAI timezone e.g. https://github.com/ryzokuken/temporal-tai/blob/master/index.mjs

Anyone with a better idea is welcome to contribute it at https://github.com/tc39/proposal-temporal!

Originally from tc39/proposal-temporal#104

Temporal subsumes most of the functionality of Moment.js, but there's a ton of code out there using Moment, and it will take a long time to upgrade to the Temporal API. To make the transition easier, while reducing download size, it'd be great to have an implementation of most of the Moment API in terms of Temporal, if this is possible. Same for Luxon or date-fns.

Link to some experimentation with date-fns: https://github.com/ptomato/temporal-fns/commits/port-to-temporal

Originally from tc39/proposal-temporal#655

It would be useful to have a "Which Temporal type do I use" flowchart in the documentation, similar to "Which STL container do I use"

See also

• https://github.com/Reactive-Extensions/RxJS/blob/master/doc/gettingstarted/which-static.md
• https://github.com/Reactive-Extensions/RxJS/blob/master/doc/gettingstarted/which-instance.md