Proposal-temporal: Calling types not tied to a specific location "local"

[lau]

First of all, it is exciting that there is a proposal for improvements to date and time in ECMAScript. Thanks for working on that.

I know that some other APIs use "local" for types not tied to a specific location. One can speculate about why that is. My guess is that it comes from the idea of having either "UTC" or "not-UTC".

However "local" might not make the most sense. I looked up "local" in a dictionary:

local |ˈləʊk(ə)l|
adjective
1 relating or restricted to a particular area or one's neighbourhood: researching local history | the local post office.
• denoting a telephone call made to a nearby place and charged at a relatively low rate.
• denoting a train or bus serving a particular district, with frequent stops: the village has an excellent local bus service.
2 (in technical use) relating to a particular region or part, or to each of any number of these: a local infection | migration can regulate the local density of animals.
• Computing denoting a variable or other entity that is only available for use in one part of a program.
• Computing denoting a device that can be accessed without the use of a network. Compare with remote.

So local is talking about a particular region or part. In the proposal there is a description of two different types of datetimes:
"A date and a time without any time zone reference." and "A date and a time, at a specific instant in time, with a time zone."

Imagine you didn't know anything about previous datetime libraries. Which of those two descriptions fit best with "relating to a particular region or part" ? The one that is specific to "Europe/Paris" or the one that is "without any time zone reference"?

To me ZonedDateTime seems more "local" than LocalDateTime. The type "without any time zone reference" is general, it does not know anything about a specific time.

An alternative is to use Naive instead of Local. NaiveDateTime, NaiveDate, NaiveTime. Elixir has a type called NaiveDateTime and Python also has a naive type.

[maggiepint]

I kind of like this. We discussed this one quite a lot. @mj1856 @bterlson?

[mj1856]

The wording is derived from the ISO8601 specification. In particular, from ISO8601:2004(E) terms and definitions:

2.1.16
local time
locally applicable time of day such as standard time of day, or a non-UTC based time of day

The same wording is throughout the spec, such as in 4.3.2 where it describes using Z for UTC, an numeric offset for a known difference from UTC, and that "The zone designator is empty if use is made of local time...". In other words, ISO8601 says when you have a timestamp without an offset or Z, that it is "local time".

I think the key wording is "locally applicable". It can apply to any local time zone of any locality. The time zone itself is unspecified.

Sure, we don't have to use this wording, but there is precedence for it. We should ask ourselves not if the wording is confusing, but if the wording is any more or less confusing to JavaScript developers than it is to developers of other languages that have already adopted this wording.

@jodastephen - Any comments from the Java world about the interpretation of the term "local"?

[jodastephen]

The term "local" in LocalTime does indeed derive from ISO-8601. While there will always be some who dislike a particular piece of terminology, my experience is that the name becomes accepted pretty quickly. The name has been used in Joda-Time since 2000, and in Java 8 for the last 2 years. It has also been adopted by other libraries building on the Joda-Time/JSR-310 experience. As such, I'd strongly recommend retaining "local" in the class names.

[bterlson]

Naïve kind of feels like a value judgement. No one wants to be naïve :) Fine retaining local, personally. It's basically a term of art but those are quite common in this domain.

[maggiepint]

I want to note that we say 'localtza' in the 262 spec, and it implies a time zone adjustment in the local zone. This local of course implies no time zone. So there's that.

[Turbo87]

The same wording is throughout the spec, such as in 4.3.2 where it describes using Z for UTC, an numeric offset for a known difference from UTC, and that "The zone designator is empty if use is made of local time...".

Without reading the spec this sounds like what we currently have in the existing Date object where you essentially have a UTC mode and a local time mode for most of the methods. It seems though that we might have to distinguish between LocalDateTime as date/time in the local system time zone and LocalDateTime as a date/time without and time zone info attached. From the sound of the spec quote it seems that the spec is describing the former one, while JodaTime and JSR-310 are actually implementing the second one.

I'm wondering if we should aim for having a date/time instance including timezone be the default. In that case we could call that just DateTime and change the one without timezone info to ZonelessDateTime or something like that. 🤔

[dilijev]

... we might have to distinguish between LocalDateTime as date/time in the local system time zone and LocalDateTime as a date/time without and time zone info attached.

Yes, this is a confusing point to me. Local time zone with the current Date objects means a Date taken to be the local time zone of the system (the default time zone), but here we're talking about a "local" timezone to mean a time without any timezone information (which may be how the Date timezone is rendered). I don't really see a potential use case for a DateTime object like this. If the default is going to be local timezone, let that be explicit. How often does a user want to switch timezones and have their DateTimes not be adjusted to reflect the change? If a relocatable time is needed it should be explicitly asked for, and I think Local time is a poor choice of name. I would probably pick a name like RawDateTime to represent this concept (I agree with @bterlson that NaiveDateTime is not a good choice either.)

[maggiepint]

One prefix we have been throwing around is Plain. This is what is used in
Time4j. Thoughts?

On May 9, 2017 1:06 AM, "Doug Ilijev" [e-mail] wrote:

... we might have to distinguish between LocalDateTime as date/time in the
local system time zone and LocalDateTime as a date/time without and time
zone info attached.

Yes, this is a confusing point to me. Local time zone with the current
Date objects means a Date taken to be the local time zone of the system
(the default time zone), but here we're talking about a "local" timezone to
mean a time without any timezone information (which may be how the Date
timezone is rendered). I don't really see a potential use case for a
DateTime object like this. If the default is going to be local timezone,
let that be explicit. How often does a user want to switch timezones and
have their DateTimes not be adjusted to reflect the change? If a
relocatable time is needed it should be explicitly asked for, and I think
Local time is a poor choice of name. I would probably pick a name like
RawDateTime to represent this concept (I agree with @bterlson
https://github.com/bterlson that NaiveDateTime is not a good choice
either.)

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/maggiepint/proposal-temporal/issues/11#issuecomment-300015412,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AFxi0mPqa1MyEJ_gwEK1xILpjwx1uyWsks5r35_igaJpZM4M5eFk
.

[apaprocki]

FWIW in our low-level native code types, we refer to a date and time with no other information as a DateTime with no additional prefix, allowing the types holding additional information to be named appropriately (i.e. date, time, and offset would be OffsetDateTime; date, time, and timezone would be ZonedDateTime). If you forget about the history of the JS Date built-in for a second, this naming convention explicitly states exactly what data the type contains so there should be no surprises.

[timrwood]

What about Just or Only as prefixes? They both imply the exclusion of other data, though I don't thing there is a precedent in other languages.

JustDateTime // No offset or zone
OnlyDateTime
JustDate // No time, offset, or zone
OnlyDate
JustTime // No date, offset, or zone
OnlyTime

[timrwood]

@apaprocki, yeah, DateTime, Date, and Time would be ideal, but the existing JS Date throws a confusing wrench in there.

[jodastephen]

I get that people struggle with the term "LocalDate", but I remind everyone that it is very widely used at this point in date/time libraries based on Joda-Time and JSR-310. Putting up naming walls across languages for the same concept isn't helpful. The messaging turns out to be simple

• got a birth date? Use LocalDate
• got a shop opening time? Use LocalTime
• got business rules to calculate where DST may impact? Use ZonedDateTime

It is also important to note that the alternative names are all negative BTW - "zoneless", "raw", "plain", "naive", "just", "only". Naming a class after what it is not is IMO a Bad Idea. (We went through the whole process of alternate prefixes for these classes during JSR-310, and everyone ended up happy with "Local" as a prefix.

To avoid any confusion,LocalDate, LocalTime and LocalDateTime are intended to be totally without reference to a time-zone. The concept of a "local time zone" is rather arbitrary, and usually the source of a lot of bugs when working with date/time. The only way to retain sanity with date/time is to be clear about what time-zone is being used, and to make it highly visible in the API (not hidden away, or implied). For example, the Date class in ECMA is close to Instant or ZonedDateTime, using the user's implied default time-zone for many methods.

The 262 spec's "LocalTZA" is IMO badly named. I've seen it referred to as "standard time" or "standard offset", but it should be viewed as essentially an unimportant implementation detail, not an important user-facing value. It should not drive this naming question.

[Turbo87]

Naming a class after what it is not is IMO a Bad Idea.

that sounds reasonable

To avoid any confusion,LocalDate, LocalTime and LocalDateTime are intended to be totally without reference to a time-zone. The concept of a "local time zone" is rather arbitrary, and usually the source of a lot of bugs when working with date/time.

I still think the term "Local" is confusing here even though it is mentioned in the spec. People often talk about local time vs. whatever other time zone, but that doesn't mean that this "local time" does not carry any timezone information.

What I'm saying is that I tend to prefer the proposal of @apaprocki with DateTime just consisting of date and time, and ZonedDateTime of timezone, date and time parts. That will potentially resolve a lot of confusion around the term "local". The only downside is that "just a date" is more complicated since Date is already taken, at least in global scope.

[apaprocki]

@jodastephen @Turbo87 In the end, the "Local" prefix is of course okay. Without it, there could be confusion with a module-scoped Date versus the built-in. There could also be confusion for users using search engines (e.g. LocalDate is easier to search for than a different flavor of Date). Especially if it is desirable to mentally inter-op with Joda / JSR-310 types, having the same naming helps because documentation / use cases could actually apply across languages. The key is just having clear documentation stating the rationale (and inter-op with other specs/languages) and there shouldn't be an issue.

[dilijev]

Naming a class after what it is not is IMO a Bad Idea.

that sounds reasonable

Agreed, but in some ways the concept of a time with no timezone is by definition a "without" concept since by default every time has a timezone, whether it is important or not. Talking about a Time without a timezone is actually a pretty abstract concept. For example, no matter what timezone, business hours for a restaurant chain might be 10am-9pm. That's an abstract time that can be relocated to different locations. And IMO LocalTime doesn't quite capture this idea (maybe even captures the opposite). The thought might be that the time specifically applies to one Location, and thus has a timezone, and maybe we need to use that prefixless Time object instead.

---

Here's a table collecting the various prefixes under discussion here. Very unscientifically (and probably biased) put roughly in decreasing order of positive sentiment I've seen so far. LMK if I missed anything.

Empty cell is base (Date|Time|DateTime)

| With-timezone Prefix | Without-timezone Prefix |
|---|---|
| | Local |
| Zoned | Local |
| Zoned | |
| | Plain |
| | Just or Only |
| | Naive |
| | Raw |
| | Zoneless or Unzoned |

To me, it appears we're pretty much all in agreement that a prefix is needed for without-timezone, and we're less sure about whether a with-timzeone prefix is needed.

I think the note of possible confusion of Temporal.Date and Date is valid, and the only way around that is to have a prefix for both Zoned and Unzoned (Date|Time|DateTime) classes. This discussion is leaning me towards thinking that's the best option. I think the best pair of prefixes for that so far is Zoned / Local.

I think we should avoid negative connotations. To that end, Naive is out. (Anyway, the meaning of the word doesn't really seem that applicable to this concept...)

I don't think Raw really captures much. It begs the question: why is a date with timezone any less raw than a date without a timezone? It's still an encapsulation of raw date/time data, isn't it? Internally, it's probably no more or less complicated to keep track of the information it encloses. Depends on the implementation.

Edit: reorganized comment somewhat.

[dilijev]

As a point of order, an argument saying something is better because it is used in some particular library or other language doesn't really seem to hold much water. Consensus of prior implementations would be better, but there doesn't really seem to be consensus on what terminology should be used for this concept. However, I'd be interested in seeing similar discussion threads that led to some of the decisions made for other libraries to help inform our choice.

I think it makes just as much sense for us to come to our own independent decision about the best terminology and naming as it would be to simply defer to those used in other implementations.

[jodastephen]

Java 8 uses LocalDate
Java has Joda-Time using LocalDate
C# has Node-Time using LocalDate
An NPM package LocalDate
A SAP XML format
A framwork Enonic

The mailing list discussions of JSR-310 are no longer online but a Mailman dump of them is available as MLM.zip here.

To those unaware of the design principles, JSR-310 is intended to provide a set of basic classes that combine to form more complex types.

Basic value types:

• LocalDate
• LocalTime
• ZoneOffset
• ZoneId
• Instant

Types that combine the basic types:

• LocalDateTime = LocalDate + LocalTime
• OffsetDateTime = LocalDate + LocalTime + ZoneOffset
• ZonedDateTime = LocalDate + LocalTime + ZoneOffset + ZoneId

These logical sets are intended to assist developers model date/time correctly, without developers necessarily realising that they are being helped to achieve the correct answer.

[maggiepint]

Not that we're the high authority on what goes forward, but @mj1856 and I are still favoring Plain as the most "plain" answer.

I know that there's tons of precedent for local, but that doesn't mean that people coming to JS have seen that precedent. I would be curious about hard numbers, but my instinct is that most new JS devs are fresh faces from college (or even in college) who would not have had much exposure to other APIs. As such, if Plain is more clear to them than local, it should be favored.

[jodastephen]

What Joda-Time solved, without it being originally planned, was the problem of terminology. Before Joda-Time, words like "date" and "time" were used fluidly without conveying a precise meaning. This is also known as ubiquitous language. Consistency across this industry is IMO really important, pandering to fresh faced college grads with zero experience is not.

[sgo]

I would agree that the argument college grads don't have a certain knowledge yet isn't a good one.
If anything I'd say these people would be well served with consistency in naming.

I've seen the "but newbies" argument used to force me as a non-newbie to use the more specific List interface at the expense of the more generic Iterable interface because it was believed Iterable was not as well understood as List.
I had no intention to imply an iteration order but my team was unmoving in their conviction that newbies can not understand the difference.

[jskeet]

In terms of the argument about it making it blindingly obvious: I believe the idea that anyone will come to a date/time library and be able to make the right decisions without reading any documentation is simply unrealistic. Whatever it's named, users will have to read docs. If there's a name which isn't hugely obvious before you've read the docs, but is fine when you have read the docs, that seems reasonable to me - and using a common name between lots of APIs definitely helps, IMO.

We had push-back against Local* in Noda Time too, to start with - but no-one ever suggested anything better. (I'm not keen on Plain as it doesn't indicate what aspect of it is plain - is it that it doesn't support leap seconds? Or that it's always in the Gregorian calendar? At least Local gives some indication that it's to do with locations and therefore time zones.)

So another vote (with no weight behind it :) for LocalDateTime.

[dilijev]

FWIW I'm now convinced that Local is a good choice. I also think the distinction of Offset and Zoned --
which (I think) was not clearly discussed before @jodastephen's comments -- is a good distinction to make. Offset alone doesn't convey timezone, partly because of DST.

[maggiepint]

I'm sure this will be a mildly unpopular opinion, but we've decided to go with Plain for the type names.

[mj1856]

Some reasoning behind this in my comments here.