Tricky, tricky dates

Any pro­gram­mer who worked with dates would tell that dates are a com­plex sub­ject. Time zones, UTC, day­light sav­ing time, leap years, and, my fa­vorite of all—leap sec­onds that “are not en­tire­ly pre­dictable”—can make your life mis­er­able very quick­ly.

And it did.

I was work­ing on a fea­ture of a pro­ject I in­her­it­ed from a group of de­vel­op­ers, when I no­ticed that the dates weren't be­hav­ing very nice­ly. The in­ter­face had a form, and in this form, there was a field spec­i­fy­ing a time: hour, minute, and sec­ond. For ex­am­ple: “09:37:20.” When the form was sub­mit­ted, this val­ue shift­ed mag­i­cal­ly ap­prox­i­mate­ly nine and a half min­utes back in time. Check­ing the code, I dis­cov­ered a few in­ter­est­ing things.

Date ini­tial­iza­tion

The date was ini­tial­ized like this: new Date(0, 0, 0, hour, minute, second, 0). It may take a mo­ment to no­tice that there is an er­ror here. And an­oth­er mo­ment to un­der­stand that what it looks like is not at all what hap­pens un­der the hood. Let's go to the Mozil­la's doc­u­men­ta­tion page of Date con­struc­tor to see what the dif­fer­ent ar­gu­ments mean here.

The doc­u­men­ta­tion starts with a fun fact:

Any miss­ing fields are giv­en the low­est pos­si­ble val­ue (1 for day and 0 for every oth­er com­po­nent).

So ac­tu­al­ly, the min­i­mum val­ue for day is 1, but JavaScript doesn't com­plain if one spec­i­fies a low­er val­ue. In­deed:

$ new Date(2021, 5, 1, 14, 30, 45, 0)

2021-06-01T12:30:45.000Z

gives the 1^st of June (in JavaScript, it's 5^th month in a range start­ing from zero, so June, not May), while:

$ new Date(2021, 5, 0, 14, 30, 45, 0)

2021-05-31T12:30:45.000Z

moves us one day in the past, that is, the 31^th of May. Ac­tu­al­ly, JavaScript doesn't even com­plain if you spec­i­fy a neg­a­tive val­ue, so new Date(2021, 5, -9, 14, 30, 45, 0) leads to the 22^th of May, and new Date(2021, -5, -9, 14, 30, 45, 0) is the 22^th of July, 2020. Nor does it ar­gue with you when you want it to cre­ate 32^th of June, which would be con­ve­nient in a mo­ment.

Year is a dif­fer­ent beast. Ac­cord­ing to the same doc­u­men­ta­tion:

Val­ues from 0 to 99 map to the years 1900 to 1999. All oth­er val­ues are the ac­tu­al year.

In oth­er words, the date of death of Cae­sar Ner­va Tra­janus (8 Au­gust 117) can be rep­re­sent­ed with a Date con­struc­tor in JavaScript, but his birth­date (18 Sep­tem­ber 53) can­not. Not that you have to deal with those sorts of dates in JavaScript on dai­ly ba­sis.

The speci­fici­ty of the treat­ment of the year ar­gu­ment, and the fact that zero is low­er than the min­i­mum ac­cept­ed val­ue for the day ar­gu­ment means that 0, 0, 0 leads to the 31^th of De­cem­ber of the year 1899. Since the ap­pli­ca­tion ma­nip­u­lates only the time, is it re­al­ly that im­por­tant whether the date hap­pens to be in 2021 or a cen­tu­ry ago? It ap­pears that it is im­por­tant, as soon as you con­sid­er the time zones.

Time zones

Most ma­nip­u­la­tions with the dates in­volve a some­times im­plic­it con­ver­sion from a time zone to an­oth­er. The sole way to call a con­struc­tor builds a lo­cal time. You may have no­ticed that in the first ex­am­ple in this ar­ti­cle, Node.js gave an UTC rep­re­sen­ta­tion of the date I cre­at­ed. 14:30 GMT+2 was trans­lat­ed into 12:30 UTC. De­pend­ing on the day and month, on my ma­chine Node.js will be us­ing ei­ther the Cen­tral Eu­ro­pean Stan­dard Time (GMT+1) or Cen­tral Eu­ro­pean Sum­mer Time (GMT+2). For in­stance, new Date(2021, 1, 26, 14, 30, 45, 0) gives ...13:​30:​45.​000Z which means that it's GMT+1 which was used in Feb­ru­ary 2021 in my time zone.

Let's list the days when the time zone changed:

var prev = undefined;
for (var i = 1; i < 45000; ++i) {
    var d = new Date(0, 0, i, 12, 0, 0, 0);
    var offset = d.getTimezoneOffset();
    if (offset != prev) {
        prev = offset;
        console.log(d.toString().substr(0, 15), Math.abs(offset));
    }
}

Here's the re­sult:

Steady pat­tern of two changes per year be­tween 1916 and the Sec­ond World War, then be­tween the oil cri­sis of 1970 and to­day. Maybe not the eas­i­est thing to fol­low, es­pe­cial­ly around the change from GMT+0/GMT+1 to GMT+1/GMT+2 1 dur­ing the Sec­ond World War, but straight­for­ward any­way. Things get very dif­fer­ent at the very be­gin­ning of the cen­tu­ry. Be­fore 1911, in­stead of a usu­al shift ex­pressed in mul­ti­ples of six­ty min­utes (thir­ty in some coun­tries), we have here a time zone with a nine min­utes dif­fer­ence. 2

To see it in ac­tion, let's com­pare two dates:

$ var t1 = new Date(1911, 2, 11, 0, 0, 0);
$ t1.toUTCString();
"Sat, 11 Mar 1911 00:00:00 GMT"
$ var t2 = new Date(1911, 2, 11, 0, 0, -1);
$ t2.toUTCString();
"Fri, 10 Mar 1911 23:50:38 GMT"

What about the mil­lisec­onds BUE?

$ t1.getTime();
-1855958400000
$ t2.getTime();
-1855958962000
$ (t1.getTime() - t2.getTime()) / 1000;
562

Yes, that's a 562 sec­onds dif­fer­ence in one sec­ond. Δ𝑡=9:21. A French page of Wikipedia on this sub­ject ex­plains what hap­pened. On the 9^th of March 1911, it was de­cid­ed in France to move to the of­fi­cial GMT sys­tem, which had a dif­fer­ence of 9 min­utes and 20.921 sec­onds. And so they did, and now there is a bug in my app.

The bug it­self

The ap­pli­ca­tion was do­ing two things: con­vert­ing the string rep­re­sen­ta­tion of the time to the Date ob­ject, and then cre­at­ing a string rep­re­sen­ta­tion of it. By mis­take, the string rep­re­sen­ta­tion was us­ing UTC, while the date it­self, when cre­at­ed with the con­struc­tor of the Date class, uses the lo­cal time zone. The orig­i­nal date such as new Date(0, 0, 0, 14, 30, 45, 0) would be­come Sun Dec 31 1899 14:30:45 GMT+0009, and when this date ob­ject was then con­vert­ed to UTC, the time part would be­come 14:21:24. Very con­ve­nient­ly, the hour re­mains the same, but the min­utes and sec­onds are dif­fer­ent from the orig­i­nal time.

Fun­ny thing: the orig­i­nal de­vel­op­ers have pos­si­bly test­ed their code, and no­ticed no er­rors at all. The pro­ject was orig­i­nal­ly de­vel­oped in the Unit­ed King­dom, and with GMT, this weird piece of code works per­fect­ly well. The new Date(0, 0, 0, 14, 30, 45, 0) re­sults in 1899-12-31T14:30:45.000Z, and once con­vert­ed to UTC, gives 14:30:45—the same time as the orig­i­nal in­put.

Ide­al­ly, one would test code us­ing dif­fer­ent time zones. Just like in­ter­na­tion­al­ized ap­pli­ca­tions are test­ed us­ing dif­fer­ent cul­tures—well, at least in the rare cas­es where they are ac­tu­al­ly test­ed. Node.js al­lows to change the time zone by set­ting the val­ue of process.env.TZ. In the cur­rent case, the ex­act state­ment would be: process.env.TZ = 'Europe/Paris'.

On the oth­er hand, you can't set the time zone in the brows­er. With a ma­ture test in­fra­struc­ture, it should be pos­si­ble to set the lo­cal time zone of a giv­en agent run­ning the tests. Most pro­jects, how­ev­er, don't have the in­fra­struc­ture as ma­ture.

An­oth­er is­sue is to know what to test. I learned about the events of 1911 be­cause I live in France and be­cause I no­ticed the bug on my ma­chine. I have no idea what fan­cy rules were ap­plied a cen­tu­ry ago in In­done­sia, Ar­me­nia, or Paraguay. Nei­ther do I ex­pect de­vel­op­ers from the UK or any oth­er coun­try to know what hap­pened in France on the 9^th of March.

The fact is, dates are com­plex. And JavaScript, by not san­i­tiz­ing the in­puts cor­rect­ly, is not very help­ful. Us­ing ma­ture li­braries, such as Mo­ment.js, which hide quite well the idio­syn­crasies of JavaScript while al­low­ing to set the time zone glob­al­ly, is an op­tion. With or with­out such li­braries, one should al­ways keep in mind that any­thing re­lat­ed to dates is as tricky as Uni­code.