Timezone and DST

[tc39]

Timezone and DST

[dcosson]

I agree it's worth being explicit about differences between timezones and UTC offsets. (But first off, I'm glad to see this proposal getting off the ground and also glad that it seems to borrow more from Joda than momentjs, in my experience using both Joda has led to far fewer bugs by being more explicit and forcing you to keep different concepts separate).

However, regarding ZonedDateTime I think even the latest Joda/Java implementation could be better if they didn't conflate ZonedDateTime and OffsetDateTime. Joda supports OffsetDateTime, which must be an offset and not a timezone, but ZonedDateTime still accepts either an offset or a timezone. I agree that given that ambiguity the OffsetDateTime is redundant, which is why tc39 is dropping it. However, I would encourage you to reconsider for tc39 and to make separate types for ZonedInstant and OffsetInstant, and enforce the difference such that a ZonedInstant does not accept an offset as its zone.

In the zone descriptions outlined for tc39:

Note that the time zone of a ZonedInstant can be any of:

Coordinated Universal Time, indicated by the string 'UTC'
The system local time zone, indicated by the string 'SYSTEM'
A fixed offset from UTC, indicated by a string in '±HH:MM' or '±HHMM' format
A Zone or Link name from the IANA time zone database, as also listed here.

There is behavior here that should be different for ZonedInstant vs OffsetInstant.

1. Timezones are not supported in all browsers. So trying to construct a SYSTEM as a timezone-based ZonedInstant in a browser that doesn't support resolvedOptions.timeZone should fail, instead of silently falling back to using the offset instead. If ZonedInstant allows either offsets or timezones, then I imagine in browsers that don't support a timezone it would make sense for SYSTEM to silently fall back to using the offset instead. Which means the same code would silently behave differently in IE vs other browsers.

2. There is actually 1 hour a year in the US (and anywhere else that supports daylight savings) where a ZonedInstant is ambiguous. 2017-11-05T01:00:00-07:00[America/Los_Angeles] represents the UTC instant 2017-11-05T08:00:00Z where as 2017-11-05T01:00:00-08:00[America/Los_Angeles] is one hour later and represents the UTC instant 2017-11-05T09:00:00Z. Just the CivilDateTime 2017-11-05T01:00:00 and timezone America/Los_Angeles are not enough to disambiguate the instant in this case. To simplify the ZonedInstant API for the rest of the year, I think it's reasonable to take a shortcut here and expose the ambigous method CivilDateTime.withZone(zone) as described in the README and just have it pick one of the possible hours. However there should also be an unambiguous method CivilDateTime.withZoneAndOffset(zone, offset). This only applies to ZonedInstant and does not apply to OffsetInstant.

Since there are these differences between a ZonedInstant and OffsetInstant, and mixing them up can lead to hard-to-debug off-by-one errors that only show up at certain times of year, it seems like treating them as separate types would be beneficial.

[dcosson]

One follow-up just so I don't forget my train of thought here - if splitting ZonedInstant into two separate types is off the table, at the very least there should be different ways to construct them. Possibly something like: civilDateTime.withTimeZone(zone), civilDateTime.withOffset(offset), and civilDateTime.withTimeZoneAndOffset(zone, offset). All three return ZonedInstant objects and either the zone or offset parameters to these methods could be 'SYSTEM', which would have a different meaning in each case.

Then ZonedInstance needs properties to show which type of zone it was constructed with. One possibility is something like zonedInstance.isTimeZoneBased and zonedInstance.isOffsetBased. In general they can both be true, if constructed from a non-ambiguous CivilDateTime and timezone. If constructed from an ambiguous CivilDateTime and timezone, isTimeZoneBased would be true and isOffsetBased would be false. And of course if constructed from only an offset and no zone, isOffsetBased would be true and isTimeZoneBased would be false.

[maggiepint]

@dcosson you have a lot going on here, but first I must note that there was an explicit choice to not go all-in on the Joda type system. We talked about it for a long time, but the fact is that it is not idiomatic to JavaScript to have a million types flying around. This is a sort of compromise.

A .getCurrentOffset() function (or similar) is a very reasonable capability. Feel free to make a PR on this proposal to add it.

There is never a point where a ZonedInstant is ambiguous. It is always either constructed with an explicit offset, or an explicit time zone. Neither one of those things can be ambiguous -instead it is the construction that can be ambiguous. I see what you are going for with the offset vs time zone constructor, but would be more likely to use a resolver similar to NodaTime. At one point, I had this described in the proposal, but it appears to have fallen out with revisions. PR welcome on that, or I will get around to it.

I'm not sure why you're bringing up IE11 in all of this. This is a new ECMAScript proposal, and it won't be back-ported.

[kaizhu256]

reference to tc39-notes: https://github.com/rwaldron/tc39-notes/blob/096b8af38c4b4b9684b09692a70938d49b5451a7/es9/2018-07/july-26.md

SYG: Are daylight saving times automatically not in this proposal? When you make a ZoneInstant with an explicit timezone,

MPT: Don’t understand the question. If you pass the word "local" to a ZoneInstant, it will take the browser’s timezone.

WH: [Clarifying SYG’s question] Do you have a notion of a US/Los_Angeles time zone whose UTC offset changes over the course of a year?

MPT: Yes it supports that.

its ambiguous how this could be supported? DST rules are frequently changed by state-governments (Fiji Islands, New Zealand, etc). implicit support would lead to the same issues as leapsonds, where external tables/databases would need to be periodically loaded/updated to keep implementations correct.

[mattjohnsonpint]

@kaizhu256 - browsers already have access to time zone information from their host environment, and via the Intl specification. Under the hood, it's usually implemented via ICU (though doesn't need to be, per se), and ultimately the data comes from the TZDB.

We don't want to create a hard dependency on this though. Lightweight environments (on IoT devices, for example) may not have the full TZDB on their devices. Still they should be able to work with UTC, fixed offset zones, and their own system's local time zone. Often in these environments the local time zone is set via a POSIX string (with the limitations therein) in the TZ environment variable. Passing LOCAL (or SYSTEM, rather) should pick up on that - or whatever the OS's or environment's local time zone configuration happens to be.

[mattjohnsonpint]

@crashposition said:

can we avoid the misleading method .getTimezoneOffset() which conflates both the TZ and DST offsets. These are very different things and It's often useful to have both values.

So this appears to be some confusion in terminology, and indeed the terminology can be inconsistent across various implementations and specs. Personally, I've been working for years to ingrain the mantra "Time Zone != Offset" into the minds of developers. (See here and here for examples).

Part of the confusion is that some people consider the "time zone" to be only inclusive of the standard time, thus they will say things like "I'm in Pacific Standard Time" throughout the year. A literal interpretation of that would be "I'm in UTC-8", but in fact it usually means "I'm either in UTC-8 or UTC-7 depending on whether DST is in effect or not." Thus a better representation of "time zone" is "Pacific Time" which can generically reflect either offset.

However, there are cross-culture issues with this as well. Consider that "Central European Time" refers both to the whole time zone generically as well as the sub-period that is not in "Central European Summer Time". To combat this in our API, I think it's important that we be consistent about terminology as:

• A "time zone" is either an IANA time zone identifier, or UTC (which happens to be an IANA identifier already), or SYSTEM (which is not an IANA identifier but has special meaning referring to the local time zone setting of the system).

• An "offset", or more verbosely a "time zone offset" is the total offset from UTC that applies at a particular point in time. This is inclusive of any DST that may be in effect.

In some cases, we may allow an offset to be passed in a parameter expecting a time zone, which indicates a time zone that is fixed at that offset for all points in time.

Thus, a time zone of America/Los_Angeles would have an offset of either "-07:00" or "-08:00" depending on which point in time is being represented.