JavaScript Date, UTC and local times

I've talked about the Date type in the past, and since then I've come across a couple of gotchas that developers should probably be aware of.

Unlike the regular DateTime type in the .NET Framework, the JavaScript Date type supports the both the UTC and the local timezone information at once. So for example you'll see there's both a getHours method and a getUTCHours method, which you can call on the same instance.

There are two things which surprise folks that are not familiar with this type. One is that when you create an instance, the signature and/or values that you initialize it with determine whether the input is interpreted as UTC or local. So new Date() creates a Date with the current time (which means that the local time should match what's on your watch), new Date(number) creates a date with the given number of milliseconds offset from 1/1/1970 UTC, new Date(text) parses the text form of the date (which may specify its own time zone), and new Date(year, month, etc) creates a date with the specified values on the current time zone.

Because initializing a UTC date with milliseconds is not very developer-friendly, I usually use the UTC method as a helper, for example new Date(Date.UTC(1999, 1, 25)) .

The other part that may confuse developers is the fact that the toString method always writes out the local version of the date, regardless of how it was initialized. So if you want to handle UTC dates and not worry about differences in your users' time zones, you should initialize them with the Date(number) constructor, and display them with the toUTCString method.

Here is a nice table of some of the values you'd get - I generated this on my local machine, at -8 from UTC (Pacific Standard Time).

More on Date and how it interacts with ADO.NET Data Services on the next installment...