Date With Offset

In JavaScript, all Dates have a local time zone. On my computer:

var now = new Date();
// Sun Apr 14 2013 09:49:16 GMT-0700 (PDT)

This makes working with time zones difficult. You can represent that date in UTC with Date.prototype.toISOString:

now.toISOString();
// "2013-04-14T16:49:16.576Z"

Unfortunately, you can't pass around an actual Date in any other time zone. Instead, create a DateWithOffset:

var nowInUTC = new DateWithOffset(0);
// Sun Apr 14 2013 16:49:16 GMT+0000

Creating DateWithOffsets

The DateWithOffset constructor works just like the Date constructor, but the last argument is always the offset from UTC in minutes. Some examples:

var nowInParis = new DateWithOffset(60);
// Sun Apr 14 2013 17:49:16 GMT+0100

var theSameTimeInMelbourne = new DateWithOffset(nowInParis, 600);
// Mon Apr 15 2013 02:49:16 GMT+1000

Date Parsing

If the first argument is a String and contains an offset end with "Z", it is treated as UTC time:

var newYearsGMTInBoston = new DateWithOffset("Jan 1 2013 00:00Z", -300);
// Mon Dec 31 2012 19:00:00 GMT-0500

If it's a String and doesn't contain an offset of end with "Z", it is treated as local to the given offset:

var newYearsInBoston = new DateWithOffset("Jan 1 2013 00:00", -300);
// Tue Jan 01 2013 00:00:00 GMT-0500

Similarly, DateWithOffsets created with individual year, month, and day (and, optionally, hours, minutes, seconds, and milliseconds) arguments are treated as local to the given offset:

var newYearsInChicago = new DateWithOffset(2013, 0, 1, -360);

Note this behavior differs from that of the normal Date constructor, which treats such strings as local to the browser (or server execution environment).

Rich Offset Objects

The last argument can be a Number (as above) or anything that responds to valueOf. If you have richer time zone objects, you can pass them directly into new DateWithOffset:

var tokyo = {
  name: 'Tokyo',
  toString: function() { return 'Tokyo (GMT+0900)' },
  valueOf: function() { return 540; }
};

var nowInTokyo = new DateWithOffset(now, tokyo);
// Mon Apr 15 2013 01:49:16 GMT+0900

Note: the offset is that between this object and UTC, which means that it is positive if the object's time zone is ahead of UTC and negative if it is behind. This is the opposite of what Date.prototype.getTimezoneOffset returns.

Compatibility with Date

You can use a DateWithOffset anywhere you use a Date:

nowInUTC.getHours();                  // 16
nowInParis.getTime();                 // 1365958156000
theSameTimeInMelbourne.getTime();     // 1365958156000
newYearsInBoston.getTimezoneOffset(); // 300

newYearsInBoston.setDate(15);
newYearsInBoston;                     // Tue Jan 15 2013 00:00:00 GMT-0500

Additional Features

Get back the original offset:

nowInBoston.offset();
// -300

nowInTokyo.offset().toString();
// "Tokyo (GMT+0900)"

Get a new DateWithOffset representing the same point in time at a different UTC offset:

var nowInChicago = nowInBoston.withOffset(-300)

Get a plain Date representing the same point in time at the local offset:

var nowInLocal = nowInParis.date();