Proposal-temporal: Document cross-language comparison

[littledan]

How does this proposal compare to date-time libraries in other programming languages, and to JavaScript date-time libraries in the ecosystem? I know many of the champions are familiar with a wide range of these things, and that the design here was based on this experience, but I don't see any documentation about that (and I'm curious).

[kaizhu256]

i would say a typical web-project has these common use-cases, listed in order of descending usage-frequency.

note:
_utcISOString_ = canonical utc-ISOString, e.g. "2017‑12‑31T09:00:00.123Z"
_localeISOString_ = canonical locale-ISOString, e.g. "2017‑12‑31T09:00:00.123+09:00"
_ISOStringDate_ = canonical ISOStringDate, e.g. "2017‑12‑31"

1. baton-passing

   • passing _utcISOString_ between workflow-components, and client <-> server <-> db

2. presentation-logic (to html, spreadsheet, pdf, logging, etc)

   • converting _utcISOString_ -> _localeISOString_
   • getting day-of-week from _ISOStringDate_
   • getting week-of-month from _ISOStringDate_

3. input-logic (from DOM-element, database, etc)

   • regexp validation-checking _localeISOString_
   • converting _localeISOString_ -> _utcISOString_

4. business-logic

   • datetime arithmetic on _utcISOString_
   • date arithmetic on _ISOStringDate_
   • getting day-of-week from _ISOStringDate_
   • getting week-of-month from _ISOStringDate_

from a web-project perspective, the current proposal is overkill as it focus too much on the [less-common] business-logic use-case. a better solution (for ease-of-use and debugging) is to use static-functions that play well with the [more-common] baton-passing use-case.

1. baton-passing

   • no static-function needed for passing _utcISOString_

2. presentation-logic (to html, spreadsheet, pdf, logging, etc)

   • _Date.toLocaleISOString_(_utcISOString_, timezoneOffset) -> _localeISOString_
   • _Date.getDayOfWeek_(_ISOStringDate_) -> number
   • _Date.getWeekOfMonth_(_ISOStringDate_) -> number

3. input-logic (from DOM-element, database, etc)

   • no static-function needed for regexp validation-checking _localeISOString_
   • _Date.toUTCISOString_(_localeISOString_) -> _utcISOString_

4. business-logic

   • _Date.addToUTCISOString_(_utcISOString_, interval) -> _utcISOString_
   • _Date.addToISOStringDate_(_ISOStringDate_, interval) -> _ISOStringDate_
   • _Date.getDayOfWeek_(_ISOStringDate_) -> number
   • _Date.getWeekOfMonth_(_ISOStringDate_) -> number

these static-functiosn are also easier to spec (and to optimize for the big-picture UX-workflow) than the current proposal.

[gilmoreorless]

@kaizhu256 that answer has nothing to do with the question asked. Please keep replies relevant instead of continually pushing your own agenda in every possible issue.

[ljharb]

@kaizhu256 that doesn’t seem to answer the OP; namely, a comparison to other libraries and other languages. It seems Iike you’re talking about the overall design of the proposal. Perhaps you want to file a separate issue for that?

[motin]

+1 I'd love to see and contribute to comparisons here. Maybe start with a list of relevant libraries and programming languages?

JS:

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

Btw 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...)

Which others?

[phueper]

there is Java which had the joda-time library that resulted in JSR-310 and became part of the language in Java 8

and there's an attempt to port that API to JS in the js-joda project (full disclosure : I'm one of the maintainers of that port)

[littledan]

@motin That would be great! Maybe you can start with a PR to the README with an initial comparison. I might add Java, Python and .NET date libraries (I have heard they settled on a similar design to this proposal, but don't know the details). From my perspective, the more data the better, especially if you can include some information about people's experience using the various interfaces, common pitfalls, etc., and draw some high level summaries/conclusions.

@kaizhu256 A comparison/upgrade guide for Date would be great as well, even if it's not what I was originally suggesting. It's important that we explain why the proposal here is to make a new set of types, rather than go with a date-fns-like approach.

[kaizhu256]

its been 7 years, but iirc as a python programmer, there was little use for python's _date_ and _time_ objects. i exclusively used _datetime_ in python-programming (mostly financial programs).

currently contracted to work on a finance-related .net web-project with c# backend. from what i can tell about project:

1. so far, there's no need for date business-logic in c# itself

   • all server-side date business-logic reside in sql-queries

2. so far, the only date business-logic in javascript/frontend is sorting utcISOString's

3. input-logic consists of creating timestamps and converting localISOString -> utcISOString

4. presentation-logic consists of converting sql-queried utcISOString -> localISOString

5. common use-case is baton-passing data-in-transit utcISOString between client <-> server <-> db

[maggiepint]

Absolutely happy to take a PR on this one. The most relevant comparisons are JodaTime, JS Date, Moment, C# DateTime and Python.

[Pauan]

Also possibly relevant: https://crates.io/crates/chrono

[littledan]

Btw some other interesting points of comparison would be the Windows datetime APIs, the POSIX/Linux/macOS ones, and the ICU Calendar/Date interfaces. Many JavaScript implementations will base their Temporal proposal on one or more of these, so it would be handy to lay out how it translates.

[rbuckton]

@maggiepint: For C#/.NET, don't forget DateTimeOffset, TimeSpan, and TimeZoneInfo

[kaizhu256]

currently contracted to work on a finance-related .net web-project with c# backend.

i finished and shipped the project and guess what? aside from sorting ISOStrings, it had no other javascript/c# business-logic involving Date/temporals. business-logic in real-world javascript/c#/etc web-programming generally has lower priority/use-case than _presentation-logic and user-input-logic_.

the former use-case is mostly done by database. and the latter use-cases are easier to do by manipulating [JSON-serializable] canonical-ISOStrings rather than classes.

[hawkrives]

@kaizhu256 that's your experience, and that's fine.

On the other hand, my applications are typically entirely serverless, such as my course scheduling preview tool for my college, and I find it much easier to work with _objects_ (via Moment, in my case) than with ISO-strings.

[kaizhu256]

for me, serverless means using IndexedDb or external service-provider to handle brunt of business-logic (google-maps, facebook-login, etc). the former is a db, and the latter, again rely on [in-house] db's for most business-logic needs.

in this case, javascript is simply a tool for baton-passing [JSON] data between ui/browser-dom <-> IndexedDb/service-provider.

[ryzokuken]

@littledan I think this is already been heavily discussed? Anyway, I don’t see anything actionable here for now, so I’m leaning towards closing this, but please feel free to reopen if you think something needs to be addressed.

[sffc]

139 is feedback relating to a C++ library.

I don't know of anything else actionable on this issue unless we wanted to solicit feedback from more library authors in other languages.

[ryzokuken]

@sffc #144 is feedback from the author of the Java library and #103 is from Elm so I’d say we’re good?

[littledan]

I'm not sure why this was closed; I think it'd be good to write up a document comparing Temporal to other date APIs. I don't see any such document.

[jasonwilliams]

When Rust was in its early days and people started thinking what a dateTime library would look like they put together some research (including comparison with other languages), the document still exists and may be useful here:
https://github.com/rust-lang/rust-wiki-backup/blob/master/Lib-datetime.md

[henryw374]

Hey folks, I have done a comparison with java.time on my blog: http://widdindustries.com/ecma-temporal-vs-java-time/

It's not totally comprehensive, but should be a decent starting point for users of java.time or JSJoda. I'd welcome any feedback or corrections you have (including if If people feel there's potential for a PR in there).

[ptomato]

@henryw374: This is fantastic, thanks very much for doing it. We would welcome any PR on this topic that you think would be appropriate!

Some notes that occurred to me while reading it:

• Temporal indeed doesn't have the equivalent of java.time.DateTimeFormatter, but I believe Intl.DateTimeFormat fulfills this role.
• I wasn't aware of the distinction between java.time.Period and java.time.Duration. There is extensive discussion of how we solve this in Temporal in #759. The short explanation is that there is an RFC about it (RFC 5545) which we decided to follow.
• The "find out that the day starts at 1 AM" example in Temporal: Temporal.DateTime.from('2015-10-18T00:00').toAbsolute('America/Sao_Paulo').toDateTime('America/Sao_Paulo'). This is quite un-obvious and would be a motivation to add some start-of-day type of method to our zoned date-time type when it lands. (#737)
• In #802 we are considering to stop treating days as 24 hours in the context of Temporal.Absolute.

[henryw374]

Thanks for the feedback & links! I'll update the post with the relevant bits.

Re: Intl.DateTimeFormatter - As far as I can see it doesn't have a function to parse string patterns of user's making into Temporal objects, in the same way that java.time.DateTimeFormatter does. I may be wrong though? mentioned this in https://github.com/tc39/proposal-temporal/issues/796

[ryzokuken]

Parsing is something we are considering in Temporal, Intl.DateTimeFormat is expect to be (and remain) a locale-aware formatter.

[ptomato]

Ah, I did not realize that java.time.DateTimeFormatter worked in both directions. Thanks for the correction.

[sffc]

java.time.DateTimeFormatter doesn't always do the right thing for i18n; internally at Google we have our own alternative that we recommend for first party products, and it may be proposed publicly.

I wasn't aware of the distinction between java.time.Period and java.time.Duration

@justingrant has brought this up before in the context of our Duration discussions. We settled on 5545 instead of separate types.