Proposal-temporal: API name of Temporal.Date and Temporal.Time

[hax]

The original intention of Civil prefix (I believe) is to avoid the name conflict with old Date API name. Though Civil prefix is controversial and I'm glad that it be dropped, we return to the original situation of name conflict of Temporal.Date with old Date.

We may need to educate the programmers always use the full name Temporal.Date and do not write:

const {Date} = Temporal
...
...
...
... // many lines of code
...
// similar API usage, hard to recognize whether it's Temporal.Date or old Date
const d = new Date(2020, 1, 1) 
console.log(d.toLocaleString())

Such code is very bad for code review.

Unfortunately in the scale of JavaScript ecosystem, education normally don't really solve the problem. Of coz we can introduce new linter rule to disallow the naive alias of Temporal.Date to Date, but I always think linter as a last resort because it always has a big community cost if u consider all the procedures of introducing new linter rules.

---

Here is an idea:

Consider we also have the API Temporal.YearMonth and Temporal.MonthDay with Temporal.Date, and all three classes have a very consistent API, could we rename Date to YearMonthDay ?

I know it break the relation between DateTime, Time and Date, but to be honest, if we check Date and Time names separately, both Date and Time names are vague in daily communication (not only in English but also in many other languages). If we change Date to more specific YearMonthDay, we could also change Time to ClockTime to make it much clear.

[pipobscure]

This was discussed previously and we concluded this to be a really bad idea.

We also believe in the intellect of JavaScript programmers. Educating users not to do const { Date } = Temporal; while possible, is also not a good thing.

In fact we should educate people to delete window.Date; 😄

[hax]

@pipobscure Where can I find previous discussion?

[gilmoreorless]

This was discussed previously

@pipobscure Would that be the discussion in #144 where you directly agreed with the premise of confusion raised by this issue? (ref: https://github.com/tc39/proposal-temporal/pull/144#issuecomment-529083322) 😉

[pipobscure]

Over the last ~3years this discussion has been had a dozen times (the one you found being only one). We’ve adapted to different outcomes every time, yet have never managed to please even a slender majority.

The real conclusion on this is that there is no way to please everyone. Thus the choice became one of:

• give up and go home
• just pick one and stick with it

I’ve opted for the second. So while I understand the frustrations and contradicting views, this is one of those things that won’t change. In the end there will be a learning curve for any feature and we’ll just have to assume that JavaScript developers have enough cycles to process the API.

[littledan]

@hax opened the thread with a good point, that this pattern would be confusing. Let's be consistent in our code samples and documentation to refer to the full name, Temporal.Date, and not use this destructuring pattern. Ultimately, I think referring to it as Temporal.Date is the semantically most meaningful/intuitive name we could choose, and Temporal.YearMonthDay would add more confusion than it would save.

[hax]

@pipobscure

Over the last ~3years this discussion has been had a dozen times (the one you found being only one).

To be clear, I was asking for the previous discussion of Date vs YearMonthDay "was discussed previously and we concluded this to be a really bad idea." A simple search of "YearMonthDay" show there was no discussion in this repo.

We’ve adapted to different outcomes every time, yet have never managed to please even a slender majority.

Well this is why it's a bikeshed issue 😂

But I think we at least made some progress that we have the conclusion that there is no prefix solution can get consensus. I create issue based on this conclusion and try to revisit the original issue of name conflict.

[littledan]

What I remember for YearMonthDay is discussing it in person; I am not sure if we talked about it in an issue. Maybe there is some broader frustration with the length of the CivilDate bikeshed. I thought Temporal.Date could be a good resolution since it already does form an easy-to-remember prefix. If we went with YearMonthDay, I imagine that Temporal.DateTime would be Temporal.YearMonthDayTime, which is just a mess. "Date" is simply the word in English that describes this concept.

[hax]

@littledan

I don't think Temporal is an "easy-to-remember" prefix. "Temporal" is not in the vocabulary of most simple english / basic english. (To be honest, "temporal" may be better than "coercion" case --- I found myself can't spell "coercion" correctly many times, thank to god, I can spell "temporal" right!)

Note I don't want to suggest any new word to replace "temporal" (because I can't find any better word 😂), my point is "YearMonthDay" is free of name conflict and may be easy to understand, remember, input than "Temporal.Date" for many people. Of coz we may have different points, this is why I think it should at least be discussed publicly.

I imagine that Temporal.DateTime would be Temporal.YearMonthDayTime, which is just a mess.

My proposal is using "YearMonthDay", "ClockTime" which is much clear. Both "Date" and "Time" is very general words, no programmer can tell the exact semantic without reading the doc, but I believe most programmers can guess what "YearMonthDay" and "ClockTime" semantic.

But I still want "DateTime" because:

1. Obviously "YearMonthDayClockTime" is too lengthy and look weird --- I agree it's a mess.
2. "DateTime" is not a so general word (I believe) and I believe most people will understand it as "calendar date" + "clock time". And many other programming languages use "DateTime".

Of coz, "DateTime" still have a small issue that it's not clear whether it's zoned or unzoned. (On the contrary, it's obviously that "YearMonthDay" and "ClockTime" is unzoned.) So I would a little prefer "UnzonedDateTime" though I also accept "DateTime".

"Date" is simply the word in English that describes this concept.

This is not true. The old "Date" api is just the proof. 😂

[hax]

Note I don't want to suggest any new word to replace "temporal" (because I can't find any better word 😂)

I suddenly realize that there IS a better choice:

Time

• Time.Absolute
• Time.Zone
• Time.UnzonedDateTime
• Time.ClockTime
• Time.YearMonthDay
• Time.YearMonth
• Time.MonthDay
• Time.Duration
• Time.getAbsolute()
• Time.getZone()
• Time.getUnzonedDateTime()
• Time.getClockTime()
• Time.getYearMonthDay()
• Time.getYearMonth()
• Time.getMonthDay()

[ljharb]

Time doesn’t really work on eg YearMonth, where to me it implies a time component that doesn’t exist; “Temporal” implies only that it has to do with time. I think it’s the optimal name.

[hax]

@ljharb I am not sure what "Time doesn’t really work on eg YearMonth" mean, actually Java also have java.time.YearMonth 😉

Of coz "Time" in "Temporal.Time" and "Time.xxx" have different meaning.

I feel "Time" is not a good API name lonely. You need prefix or u need to list all "Date, Time, DateTime" to make it more clear what "Time" really mean. In some languages Time means the similar thing of old Date in JS 😝.

But it seems ok to use "Time" as a namespace, which means the APIs relate to "Time" (as the meaning in "“Temporal” implies only that it has to do with time").

Precedents:

• java.time package
• golang time package
• NodaTime .NET library

[littledan]

Temporal isn't a normal English word to use in this context, but it's a brand name that seems to have stuck when discussing this proposal. So I hope it is easy to learn, not easy to guess out of thin air.

I am confused why you would use Time.UnzonedDateTime and not Time.UnzonedYearMonthDayTime, in your above listing.

[hax]

@littledan

So I hope it is easy to learn

My experience is many Chinese programmers don't know what "temporal" mean, every time I introduced temporal proposal (I did three times in last year) I need to first explain the meaning of "temporal".

It's hard to say how "easy" to learn this word, actually programmers are forced to learn the word if it was the part of API. Especially in this case we may force the programmers always use the fully qualified name "Temporal.Date". The only thing I can tell is "Time" is definitely easier to learn, read and write than "Temporal".

I am confused why you would use Time.UnzonedDateTime and not Time.UnzonedYearMonthDayTime

@littledan I think my previous comment https://github.com/tc39/proposal-temporal/issues/212#issuecomment-548439731 already gave the reason. But I am happy to summarize it again:

My suggestion is "YearMonthDay" for "Temporal.Date" and "ClockTime" for "Temporal.Time", so if combine them it should be "YearMonthDayClockTime", not "UnzonedYearMonthDayTime". (There is no need to add "Unzoned" for "YearMonthDayClockTime" because it's clear that both "YearMonthDay" and "ClockTime" are unzoned, at least much clear than "DateTime".)

Why not "YearMonthDayClockTime"?

• "YearMonthDay" is already a combination, so we can't combine it to some unequal concept, the only reasonable combination version for "DateTime" may be "YearMonthDayHourMinuteSecond" (actually still problematic because not sure how to deal with "Millisecond" and "Nanosecond").
• It's too lengthy and looks weird --- it's a mess

But YearMonthDay, ClockTime, UnzonedDateTime do not have the corresponding relationship like Date, Time, DateTime ?

Yes, but we get:

• corresponding relationship of YearMonth, MonthDay and YearMonthDay
• three much clear API names:
  
  
  
  • YearMonthDay name is much clear than Date (a very general word) what it is and whether it's zoned or unzoned
  
  
  • ClockTime name is much clear than Time (a very general word) what it is and whether it's zoned or unzoned
  
  
  • UnzonedDateTime name is clear than DateTime whether it's zoned or unzoned
  
  
• because use ClockTime instead of Time, we could also use Time as namespace now (or there will be Time.Time which seems weird)