Moment.JS Shows the Wrong Date!

I have been answering some Stack Overflow questions lately, and it seems like quite a lot of them all boil down to someone saying that Moment.JS is showing the wrong date.

Here are some of the most common reasons why Moment might not be showing what you expect, and the ways to get it to do what you want:

The console shows the wrong date when I dump a Moment object

I might run code that looks something like this:

MomentConsoleUTC

As you can see, I parsed January 1, but am seeing December 31 in the console.

When you dump a Moment object to the console, you see Object.prototype.toString() being called on the _d variable, which is the built-in JavaScript date object that Moment wraps. In most JavaScript implementations, that will cause that object to display in local time. I parsed a UTC time though, so I’m seeing the wrong result in the console. If I had used Moment Timezone, I would also be seeing a wrong value in the console.

This is easy to work around. Ignore the value of _d – it is not useful information. Instead, rely on .format() to get the correct result:

moment.utc('2016-01-01').format()
2016-01-01T00:00:00Z

.format() Shows a Date I Didn’t Parse

Most often, when .format() isn’t giving the expected result, it is because the date was parsed with an offset, and the wrong Moment constructor function was used. This is a little bit of a complicated statement, but let’s break it down.

First, the date format causing confusion is usually ISO 8601 format with offset. That format looks like this:

2016-05-14T08:33:14-03:00

This indicates that the date in question is May 14 2016 at 8:33 AM in local time, and that the local time of this date is offset three hours behind UTC.

You may also see an ISO8601 formatted date that looks like this:

2016-05-14T13:37:09Z

Note that the z in the date above indicates that it is in UTC, or has an offset of +00:00.

This is a very helpful format in that it reflects both local time, and global time in the same time stamp. It can get people into trouble when making moments though.

Moment offers four ways to construct a moment object, and all of them will use this offset information to achieve different results.

The moment constructor functions are as follows:

  • moment()
  • moment.utc()
  • moment.parseZone()
  • moment.tz() (this only works with the Moment TimeZone add on)

The moment() Function

When you use the default moment constructor, it will convert the date from the provided offset to the environment’s local time. Right now my local time is -05:00. As such, if I take my -03:00 date from above, and parse it with moment, I get the following:

moment('2016-05-14T08:33:14-03:00').format()
"2016-05-14T06:33:14-05:00"

As you can see, the time has been shifted from 08:33:14 to 06:33:14 to reflect the offset change.

It is important to note that the default moment constructor will use information from the browser to keep the moment in the user’s local time, even when offsets change due to DST. If I add six months to this moment, my local offset will be -06:00. This will be properly handled:

moment('2016-05-14T08:33:14-03:00').add(6, 'months').format()
2016-11-14T06:33:14-06:00

The moment.utc() Function

When you use the moment UTC constructor, it will convert the date from the offset provided to UTC. Using the same date string:

moment.utc('2016-05-14T08:33:14-03:00').format()
"2016-05-14T11:33:14Z"

As you can see, this time the date has been shifted forward three hours, from 08:33:14 to 11:33:14 to be in line with UTC.

The moment.parseZone() Function

The .parseZone() function will parse a moment with the offset fixed to the provided offset.

It is very important to remember that this function is mis-named. When you use .parseZone() you are parsing the moment to have a fixed offset. A fixed offset is NOT a time zone. Most time zones will have more than one offset at various points in the year due to DST. Also, most time zones have changed their offset over time. Any math performed with a moment in fixed offset mode may yield unexpected results. The use cases for a fixed offset moment are limited. See the Stack Overflow timezone tag for more information on time zones vs offsets.

Using my same time, I get the following result with .parseZone():

moment.parseZone('2016-05-14T08:33:14-03:00').format()
2016-05-14T08:33:14-03:00

As you can see, the time and offset are unchanged.

The moment.tz() Function

The moment.tz() function will parse a given time with offset and convert it to the time zone provided. It is useful when you need to interpret a time in a time zone other than UTC, or the user’s local time.

Note that this functionality does not work without the Moment TimeZone add on library being included in your project. The Moment TimeZone library uses the IANA time zones to provide time zone support. A list of IANA time zone identifiers and offsets can be found here.

If you only need to work in UTC, and the user’s local time, do NOT bring in the Moment TimeZone library. It only causes extra code to be sent to the browser. Of course if you are in Node, feel free to bring it in everywhere just in case.

Using the same date and time as before, I will specify the time be parsed to Europe/Berlin. This time zone is UTC +2 at the time of year specified:

moment.tz('2016-05-14T08:33:14-03:00', 'Europe/Berlin').format()
2016-05-14T13:33:14+02:00

As you can see, the time has been shifted five hours forward, to move from -03:00 to +02:00. The resultant time is 13:33. This moment will be time zone aware, so if you were to add six months to it, at which point Berlin will have an offset of -01:00, the moment will correctly change offsets:

moment.tz('2016-05-14T08:33:14-03:00', 'Europe/Berlin').add(6, 'months').format()
2016-11-14T13:33:14+01:00

But I Don’t WANT the Offset

A common complaint about these functions is that people just don’t want the offset to be used. They wish for the date to be interpreted as local time.

If you are thinking this, please use caution. When you get a date with an offset, you are getting valuable information about both local time, and the point on the global timeline. Throwing this information away may not be helpful down the road.

If you are sure that you do not want the offset information, the best practice would be to have the system that you are getting the date from stop sending the offset. Any other choice may be misinterpreted later.

As developers though, we live in reality. We can’t always change the data that is being sent to us. If you need to ignore the offset, you have a few options.

If the offset is z, so all dates are being sent in UTC, just parse in UTC mode. No change will be made to the time.

moment.utc('2016-05-14T08:33:14Z').format('LLL')
May 14, 2016 8:33 AM

If the offset is some other number, and you wish to ignore it, you can use .parseZone(), and simply not display the offset information:

moment.parseZone('2016-05-14T08:33:14-03:00').format('LLL')
May 14, 2016 8:33 AM

Remember though, both of the above methods will not handle DST transitions in the user’s local time. Thus, mathematical operations can have unexpected results.

If you want to interpret the date as the user’s local time, and be able to safely do math with it, you can specify a format that has no Z token, and thus ignores the offset:

moment('2016-05-14T08:33:14-03:00', 'YYYY-MM-DDTHH:mm:ss').format()
2016-05-14T08:33:14-05:00

As you can see, the time has been interpreted as local and has my offset. Note that this will not work in strict parsing mode, as there will be left over training characters. It will result in an invalid date.

Moment.js Locale Inheritance

Moment.js released version 2.12.0 a couple weeks ago, and with that came a major new feature – locale inheritance.

Defining custom locale data has been possible in Moment.js for a very long time, and it is one of the coolest features of the library.

Suppose I wanted create a locale that was specifically for mobile use, which was in French, but had shorter strings for Moment’s relative time feature. Previous to 2.12, I might have tried something like this:

moment.locale('fr-mobile', 
      {   
      relativeTime : {
          future : 'dans %s',
          past : 'il y a %s',
          s : 's',
          m : 'une m',
          mm : '%d m',
          h : 'une h',
          hh : '%d h',
          d : 'un j',
          dd : '%d j',
          M : 'un mo',
          MM : '%d mo',
          y : 'un an',
          yy : '%d ans'
      }
    });

 

With 2.11.2 and previous, the result would have been great when I called .fromNow():

moment.locale('fr-mobile');
moment().subtract(2, 'minute').fromNow()
il y a 2 m

But I would have gotten a surprise when I called .calendar():

moment.locale('fr-mobile');
moment().calendar();
Today at 10:27 PM

 

English! Whoops. This is because there was no locale inheritance in Moment.js. Locales always fell back to English if data was not defined. To create this fr-mobile locale, I would have had to define every locale property available in Moment.

Enter locale inheritance.

Now I can just define a parent locale for my mobile locale:

moment.locale('fr-mobile', 
      {  parentLocale:'fr', 
        relativeTime : {
            future : 'dans %s',
            past : 'il y a %s',
            s : 's',
            m : 'une m',
            mm : '%d m',
            h : 'une h',
            hh : '%d h',
            d : 'un j',
            dd : '%d j',
            M : 'un mo',
            MM : '%d mo',
            y : 'un an',
            yy : '%d ans'
        }
    });
    moment.locale('fr-mobile');
    moment().subtract(2, 'minute').fromNow()
    //il y a 2 m
    moment().calendar()
    //Aujourd'hui à 22:33

 

Much Better!

Previously, there was also an issue with partial object definitions. Suppose I wanted to change just a couple things about relative time in the French locale. I would have tried this:

moment.locale('fr', 
      {   
      relativeTime : {
          future : 'dans %s',
          past : 'il y a %s',
          s : 's',
          m : 'une m',
          mm : '%d m',
      }
    });
    moment.locale('fr');
    moment().subtract(2, 'minute').fromNow()
    //il y a 2 m
    moment().subtract(1, 'year').fromNow()
    //Uncaught TypeError: Cannot read property 'replace' of undefined

That didn’t go well did it?

Enter updateLocale in 2.12.

moment.updateLocale('fr', 
      { 
      relativeTime : {
          future : 'dans %s',
          past : 'il y a %s',
          s : 's',
          m : 'une m',
          mm : '%d m',
      }
    });
    moment.locale('fr');
    moment().subtract(2, 'minute').fromNow();
    //il y a 2 m
    moment().subtract(1, 'year').fromNow();
    //il y a un an

 

Big thanks to Iskren for getting this in.

Save effort, save file size, be happy!

Moment.js and Klingon Your Dates

So, I haven’t blogged in a long time. There are a lot of reasons for this, but the main one is that I’ve found a project.

I recently was invited to join the Moment.js core collaborators team. How this happened is a weird accident of networking. At CodeMash in January I was told I had to meet Matt Johnson. It turns out that Matt and I have both:

  1. Given conference talks on RavenDB
  2. Developed a time and attendance solution

This is a a very weird set of things to have in common with someone. If there is a third person in the world who has done these two things, let Matt and I know – we would like to be your friend.

Anyways, Matt is on the Moment.js team, and he decided that I should take what I know about date and time and come help out, so here I am.

Over the past month I have had a huge amount of fun working on the project. At this point I mostly write documentation and answer people’s questions on GitHub, but I have snuck a couple pull requests in :-).

On the subject of fun, it is a little known fact that as of 2.11.0 Moment.js supports Klingon as a locale, thanks to some wonderful nerds on the internet.

I felt compelled to make something out of this, so this past weekend I set out to change all the dates in your browser to Klingon via chrome extension.

As it turns out, chrome extensions are crazy easy to make. In order to support Klingon-ing of all dates, I simply queried the DOM with some regular expressions that would match a lot of common English date formats, and then fed them into a function. All of the code relevant to Moment.js is right here:

    function toKlingon (match) {
        //parse the string using the format that the Regular expression is looking for
        var a = moment(match, format);
        //change to the klingon locale and return formated as local long date
        return a.locale('tlh').format('LL');
    }

 

Rest assured that the DOM parsing involved was substantially more difficult than this.

This is a great example of just how well Moment.js does i18n. I don’t need to know anything about this language to be able to output dates formatted exactly as native speakers would.

The extension does have an issue where it will always display all date parts, even if they weren’t parsed. For example, dates from Gmail, which are written as “Mar 13” are output with a year.

I am working on a minor change to Moment that will expose what date parts were actually parsed, which would allow me to easily include only valid data in this situation.

I also need to do some more work on better/faster DOM parsing with the regular expressions, as it still doesn’t get quite every date, but generally the extension works. If you would like to try it, find it in the chrome store here.

Katas and Insecurity

I’m at CodeMash today doing precompiler sessions, and I have to say that it has so far been a great time.

Today I spent most of my session in an “Improving Software Craftsmaship” session where we pair programmed several Katas. In the course of doing this, I found myself paired with a couple of people who were a bit faster to the punch than me on what needed to be done next.

Now, I’m used to this. My coworker Erik can always do basically everything faster than me, and believe me when I say that this doesn’t upset me. Erik is a friend, and I always appreciate his help. This was DIFFERENT though.

See, here at CodeMash, I’m walking around with one of the blue lanyards – I’m a speaker. So, when someone bests me at Katas, I feel like I haven’t lived up to some unsaid expectation. This caused me a bit of a panic attack. I found myself having to walk down the hallway and remind myself of these things:

  1. I am here to learn as well as talk
  2. I can practice and get better
  3. I have my own strengths

This post is admittedly trite, but I wanted to put it out there anyways as a reminder to everyone that, well, we all feel insecure sometimes.

Dog Breeding is a Craft

I want to depart a bit from posts on the craft of coding, and instead focus on another craft that is near and dear to my heart. That is the craft of dog breeding.

It is very popular these days to say things like “don’t shop, adopt” when people talk about getting a puppy from a breeder. I understand the sentiment behind these statements – with, indeed, lots of dogs in rescues and shelters, why would one adopt from a breeder? Lots of great people in the dog world have written great things about why breeders are still relevant, and I won’t rehash arguments that others have given. However, one argument that I don’t see often is one that’s very important to me as a software craftsman.

Dog breeding is at it’s heart, a craft. In the same way that carpentry, metal work, masonry, glass blowing, brewing, and many other arts are passed down from master to apprentice, so is quality dog breeding. It takes years to become a master dog breeder. Many dog shows, many trials, many conversations, many litters that you put your heart and soul into, many litters that don’t work out exactly the way you wanted. It takes mentorship to become a master dog breeder. Nobody becomes a great dog breeder without being mentored by one or more other great breeders. One starts as an apprentice and works one’s way to mastery.

Dog breeding is one of the oldest crafts known to mankind. Keep in mind that dogs have existed nearly as long as humans, and many anthropologists believe that large parts of the success of the human race can be attributed to our breeding dogs from wolves to be our early hunting companions. This means that we have been selectively breeding dogs as long as, or longer than we’ve been engaging in other ‘ancient’ arts like brewing.

Wouldn’t it be heartbreaking if nobody ever made a finely crafted piece of furniture again because Ikea furniture is cheaper and readily available? We would lose a piece of human history if that happened.

When people suggest that nobody should breed dogs until there are no more dogs in the world to rescue, people are suggesting the death of an art that is as old as time. If everyone stops breeding dogs, there will be no more mentors for the next generation. We will lose an art that helped to build the human race. We will have to relearn what people have been perfecting for thousands of years.

I’m hardly advocating that everyone who breeds dogs should continue to do so. In fact, most people who are breeding dogs would do well to get out of the business. But those who are truly participating in the ancient craft with dedication should be encouraged to continue and supported in their endeavors, in order to preserve a part of our history.