Search code examples
timezonemomentjsutcdst

Correct way to use moment.js to convert a series of non-UTC timestamps that cross the Fall DST boundary to UTC timestamps?

Background

I am investigating different use cases of moment.js for a project but am stumped on the issue of daylight savings ending in the fall. Before asking my question, since I want to be clear and provide background for others who have similar questions, let me explain what I am doing and what found with spring daylight savings.

First, I am working with UTC timestamps and America/New_York timestamps. In the US, daylight savings in 2017 begins on March 12 at 2AM (skipping from 2:00:00AM to 3:00:00AM) and ends on November 5 at 2AM (reverting from 2:00:00AM to 1:00:00AM). Since I also always know the target time zone (America/New_York) that I need to convert to, I will not rely upon moment.js to detect my local time zone and instead explicitly specify the time zone I want.

During the spring when daylight savings goes into effect, the time zones that observe daylight savings, like America/New_York, jump forward an hour. moment.js handles this just fine.

For example, if I pass moment.js a UTC timestamp for the time one second before daylight savings goes into effect for America/New_York, it looks like this:

moment('2017-03-12T06:59:59Z').tz('America/New_York').format('YYYY/MM/DD hh:mm:ss a z')

The input above is taken as UTC because of the Z on my timestamp and I am explicitly setting the target timezone with .tz('America/New_York') so that it doesn't use local system time.

Alternatively using moment-timezone I can explicitly set the input time zone as UTC and set the output as America/New_York.

moment.tz('2017-03-12T06:59:59', 'UTC').tz('America/New_York').format('YYYY/MM/DD hh:mm:ss a z')

Either way, the result is 2017/03/12 01:59:59 am EST.

Then, I run the same commands for a moment just one second later. I will just use the format given in the first example above where I specify the time as UTC and then convert it to America/New_York time:

moment('2017-03-12T07:00:00Z').tz('America/New_York').format('YYYY/MM/DD hh:mm:ss a z')

And my result is correct as expected: 2017/03/12 03:00:00 am EDT - due to daylight savings the time skipped ahead by one hour.

I can then use moment-timezone to go back the other way by passing in an America/New_York timestamp and converting it to UTC.

moment.tz('2017-03-12T01:59:59', 'America/New_York').utc().format('YYYY/MM/DD hh:mm:ss a z')

This gives me 2017/03/12 06:59:59 am UTC

And the next moment in the America/New_York time zone, because of daylight savings coming into play, is 03:00:00 so I convert that to UTC...

    moment.tz('2017-03-12T03:00:00', 'America/New_York').utc().format('YYYY/MM/DD hh:mm:ss a z')

... and get 2017/03/12 07:00:00 am UTC which looks correct. An hour was skipped ("lost") in America/New_York time, but moment can detect that and convert it to UTC.

In Summary, for the spring daylight savings change in the US, I can pass a UTC timestamp into either moment.js or moment-timezone and get back a timestamp in another time zone with the correct daylight savings offset also applied. I can also then pass an America/New_York timestamp into moment and get back a correctly converted UTC timestamp.

My Question

Great, so I want to do the same thing when daylight savings ends in the fall and of course it isn't that simple. My hypothesis is that due to daylight savings effectively causing an hour to "repeat", there is no way for moment to know the correct time UTC. In other words, where there was a gap of one hour when daylight savings started, now we have overlap of one hour.

Question (part 1): Is there a way to pass a relative timestamp and time zone into moment and get back the correct UTC time? When I tried this in the examples below, moment skips an hour on the UTC side.

moment.tz('2017-11-05T01:00:00', 'America/Denver').tz('UTC').format('YYYY/MM/DD hh:mm:ss a z') => "2017/11/05 07:00:00 am UTC"
moment.tz('2017-11-05T01:59:59', 'America/Denver').tz('UTC').format('YYYY/MM/DD hh:mm:ss a z') => "2017/11/05 07:59:59 am UTC"
moment.tz('2017-11-05T02:00:00', 'America/Denver').tz('UTC').format('YYYY/MM/DD hh:mm:ss a z') => "2017/11/05 09:00:00 am UTC"
moment.tz('2017-11-05T02:59:59', 'America/Denver').tz('UTC').format('YYYY/MM/DD hh:mm:ss a z') => "2017/11/05 09:59:59 am UTC"

I assume its because time is happening chronologically like in the example below. UTC offset context is not given therefore I assume that moment cant distinguish between the America/New_York timestamps preceded by asterisks:

*2017/11/05 01:00:00 am America/New_York => 2017/11/05 07:00:00 am UTC
*2017/11/05 01:59:59 am America/New_York => 2017/11/05 07:59:59 am UTC
*2017/11/05 01:00:00 am America/New_York => ???
*2017/11/05 01:59:59 am America/New_York => ???
2017/11/05 02:00:00 am America/New_York => 2017/11/05 09:00:00 am UTC
2017/11/05 02:59:59 am America/New_York => 2017/11/05 09:59:59 am UTC

Again, what I want to know is if there is a way around this? Currently the timestamps in the data that I have does not contain UTC offsets.

Question (part 2): If I am presenting data in the America/New_York time zone then is it correct to think that I will essentially have two hours of data points all stuffed into a (seemingly) single one hour period from 01:00:00 to 01:59:59 on November 5, 2017?

Related Topics

There are a few other topics on SO that are related to this but none that I have found pose or answer this same question. I will link a few here for reference:

Solution

  • It looks like you have thought the problem through and done some basic research. Thanks!

    What you are describing is covered in the moment-timezone docs here. If the data isn't available as a UTC offset in your input, there's no way to tell the difference between the first or second occurrence of an ambiguous local time. Moment picks the first occurrence, because time moves in a forward direction, so this is usually the most sensible choice for most scenarios.

    The problem is one of ambiguity. Even as just a human being, if I say "1:00 am on November 5th 2017 in New York" you don't know which of two points in time I'm describing.

    That said, sometimes you have external knowledge that can help. For example, if you have an ordered set of timestamps containing time that skips backwards, then you know you encountered a fall-back transition. Say I'm recording data at 15 minute intervals in local time:

    00:45
01:00
01:15
01:30
01:45
01:00  <---  this one comes next sequentially, but appears backwards, so infer transition
01:15
01:30
01:45
02:00

    You'll have to write your own detection logic to compare one value to the next for that scenario. Also note that if you don't have any time that appears to be out of sequence, then you cannot be assured of which occurrence is being described. A "heartbeat" signal can assist with this in some scenarios.

    Now how do you choose the second occurrence in Moment without knowing the offsets in advance? Like this:

    First, grab the hasAmbiguousWallTime function from here.

    Then define another function:

    function adjustToLaterWhenAmbiguous(m) {
    if (hasAmbiguousWallTime(m)) {
        m.utcOffset(moment(m).add(1, 'hour').utcOffset(), true);
    }
}

    Now you can do this:

    // start with the first occurrence
var m = moment.tz("2017-11-05T01:00:00", "America/New_York");
m.format(); // "2017-11-05T01:00:00-04:00"

// now shift it to the second occurrence
if (... your logic, such as wall time going backwards in sequence, etc. ...) {
    adjustToLaterWhenAmbiguous(m);
    m.format(); // "2017-11-05T01:00:00-05:00"
}

    These two functions should probably be hardened and added to moment-timezone, but they should be sufficient for the scenario you describe.

    A couple of other minor points:

    • Instead of moment.tz(s, 'UTC'), consider using moment.utc(s)
    • Instead of moment.tz(s, 'America/New_York').tz('UTC'), consider
      using moment.tz(s, 'America/New_York').utc()
    • You may want to review the DST tag wiki for visualization of the problem space.
    • On part two of your question, yes - you'll end up stuffing two hours of data into what could possibly be visualized as a one-hour space. People have this problem with graphs and charts all the time. They graph something with a constant value over local time, then see a zeroing effect in the spring, and a doubling effect in the fall. Even if you tell moment to use the later occurrence, you won't avoid this unless you actually display the graph in UTC instead of local time.