Walltime.js Plugin

Time is important.  Keeping accurate time has been one of the major challenges of technology throughout all of history.  Here’s a little history lesson from the US Navy:

In 1845, at the request of the Secretary of the Navy, the Observatory installed a time ball atop the 9.6-inch telescope dome. The time ball was dropped every day precisely at Noon, enabling the inhabitants of Washington to set their timepieces. Ships in the Potomac River could also set their clocks before putting to sea. The Observatory’s Time Service was initiated in 1865. A time signal was transmitted via telegraph lines to the Navy Department, and also activated the Washington fire bells at 0700, 1200, and 1800.

For the Navy, time is important for navigating all those ships around the globe.  For Sprout Social, time is important because we have some pretty cool technology that determines the optimal time to send a tweet or Facebook post to get the most reach for our customers.

Time in the Browser

Right now, browsers can give you pretty accurate time information for the time zone currently configured on your computer. The problem comes in when you need to know what time it is in another time zone than your own. For instance, if I’m a user in Australia, and I want to post something at 3:00 AM Chicago time, where the majority of my followers are, how do I calculate that accurately with JavaScript and send it up to the server?

// Some basic javascript Date examples

// NOTE: Javascript dates have 0 indexed months, because they are awesome

// January 1, 2012 (Chicago, IL)
var firstOfYear = new Date(2012, 0, 1),
    // 6 Hour offset (before DST change)
    hoursOffset = firstOfYear.getTimezoneOffset() / 60; 

// April 1, 2012 (Chicago, IL)
var afterDST = new Date(2012, 3, 1),
    // 5 Hour offset (after DST change)
    hoursOffset = afterDST.getTimezoneOffset() / 60;

// November 16, 2012 (Chicago, IL)
var postDate = new Date(2012, 10, 16),
    // 6 Hour offset (after DST change back)
    hoursOffset = postDate.getTimezoneOffset() / 60;


Daylight Savings and Olson Files

It turns out, the hard part of these equations is determining the daylight savings offset for a given time zone.  We already have a really easy way to get UTC for any time in JavaScript; the problem is determining if another time zone than our own currently has a daylight savings rule applied.  Otherwise, we could just keep a map of all the time zone offsets and apply the different offsets to our UTC – back and forth.

# US central time, represented by Chicago

# Alabama, Arkansas, Florida panhandle (Bay, Calhoun, Escambia,
# Gulf, Holmes, Jackson, Okaloosa, Santa Rosa, Walton, and
# Washington counties), Illinois, western Indiana
# (Gibson, Jasper, Lake, LaPorte, Newton, Porter, Posey, Spencer,
# Vanderburgh, and Warrick counties), Iowa, most of Kansas, western
# Kentucky, Louisiana, Minnesota, Mississippi, Missouri, eastern
# Nebraska, eastern North Dakota, Oklahoma, eastern South Dakota,
# western Tennessee, most of Texas, Wisconsin

Rule	Chicago	1920	only	-	Jun	13	2:00	1:00	D
Rule	Chicago	1920	1921	-	Oct	lastSun	2:00	0	S
Rule	Chicago	1921	only	-	Mar	lastSun	2:00	1:00	D
Rule	Chicago	1922	1966	-	Apr	lastSun	2:00	1:00	D
Rule	Chicago	1922	1954	-	Sep	lastSun	2:00	0	S
Rule	Chicago	1955	1966	-	Oct	lastSun	2:00	0	S

It turns out, there is a group of files that keep a record of all the daylight savings rules across the world just for this kind of thing:

The tz database, also called the zoneinfo database or IANA Time Zone Database, is a collaborative compilation of information about the world’s time zones, primarily intended for use with computer programs and operating systems. It is sometimes referred to as the Olson database after the founding contributor Arthur David Olson.

The problem is that no one has really implemented using them in JavaScript yet (there is another library called timezone-js, but it turns out they are not applying the rules properly).

Introducing Walltime-js

Walltime makes it easy to convert from one UTC date to the “wall time” of just about any time zone:

var someUTCDate = new Date(),
    chicagoWallTime = WallTime.UTCToWallTime(someUTCDate, "America/Chicago"),
    backToUTCTIme = WallTime.WallTimeToUTC("America/Chicago", chicagoWallTime);

In addition, what if we need to convert from a local time zone time in another time zone than your own to a UTC time?  We’ve got you covered there too:

Make sure to check out the source on Github and file any issues you may find.