Exploring the JavaScript Date Object

There are some great libraries out there to deal with dates in JavaScript, with Moment.js and date-fns being perhaps the two most popular. It’s very common however to have just some basic needs for playing with dates and using a library instead of the native JavaScript date object would be overkill. Let’s therefore explore what we can do natively using the date object.

Creating Date Objects #

Creating a new date instance is as easy as newing up a date object.
Without arguments, we get the current date and time in the local timezone:

const now = new Date();

console.log(now); // Wed Dec 06 2017 18:30:55 GMT-0800 (PST)

Milliseconds Since Unix Epoch #

You can also pass-in an integer for a date object that’s X amount of milliseconds after January 1st 1970 UTC:

const latter = new Date(4000000000);

console.log(latter); // Sun Feb 15 1970 23:06:40 GMT-0800 (PST)

Date String #

You can also alternatively create a date object by passing a string:

const summerOf95 = new Date("1995-06-28");

// or, with a full date string that also includes the time and the time zone. Note here that `Z` is for UTC timezone:
const december31st = new Date("1999-12-31T02:56:03.392Z");

Date Components #

Finally, you can create a date object in your local timezone using separate component argument:

const someDate = new Date(2000, 5, 20, 16, 34, 12, 24);

console.log(someDate); // Tue Jun 20 2000 16:34:12 GMT-0700 (PDT)

Notice how the months are zero-based, and 5 therefore represents June. Components for time can be omitted and `` will be assumed:

const someDate = new Date(2000, 5, 20, 16, null, 12, 24);

console.log(someDate); // Tue Jun 20 2000 16:00:12 GMT-0700 (PDT)

If you’re confused by the date returned when console logging a date object, remember that most browsers output the time in your local timezone.

Timestamps #

Get a timestamp (number of milliseconds since Jan 1st 1970 UTC) using a date instance’s getTime method:

const nowTimestamp = new Date().getTime();

console.log(nowTimestamp); // 1512616153783

Timestamp for now #

In the above example, we’re getting the timestamp for now. This is so common that JavaScript now has a method to get just that more easily:

const nowTimestamp = Date.now();

console.log(nowTimestamp); // 1512616153783

Timestamps are useful to easily calculate the difference in milliseconds between two dates. For example, here we get the difference in milliseconds between Feb 3rd 1996 and Jan 1 1970:

const diff = new Date("1995-02-03").getTime() - new Date(0).getTime();

In the above case, you can ommit the call to getTime and the dates will automatically be coerced to timestamps:

const diff = new Date("1995-02-03") - new Date(0);

Human Readable Strings #

Date object instances also give us a few useful methods to get human-friendly string representations. The toDateString, toTimeString, toLocaleDateString, toLocaleString, toLocaleTimeString and toUTCString methods are the most useful ones, and demonstrated in the following example:

const now = new Date();

console.log(now.toDateString()); // Wed Dec 06 2017
console.log(now.toTimeString()); // 19:23:42 GMT-0800 (PST)
console.log(now.toLocaleDateString()); // 12/6/2017
console.log(now.toLocaleString()); // 12/6/2017, 7:20:28 PM
console.log(now.toLocaleTimeString()); // 7:20:51 PM
console.log(now.toUTCString()); // Thu, 07 Dec 2017 03:21:14 GMT

Getting Date or Time Components #

You can get specific date/time components from a date instance using the following methods:

getFullYear(): The year, using 4 digits.
getDate(): The day of the month (e.g: 31).
getMonth(): A zero-based integer for the month (e.g: 0 for January).
getDay(): The index for the day of the week from 0 for Sunday up to 6 for Saturday.
getHours(): The hour of the day.
getMinutes(): The minutes.
getSeconds(): The seconds.
getMilliseconds(): The milliseconds.

Here’s a simple example:

const now = new Date();

console.log(`It's ${now.getHours()}:${now.getMinutes()} o'clock`);
// It's 19:34 O'Clock

Note that all the above methods return date/time components in the local timezone. Each method has an equivalent so that UTC date/time is returned instead (e.g: getUTCMinutes()).

Setting Date or Time Components #

Similar to how we can get date/time components, we can also set them using analogous methods:

const now = new Date();

now.setFullYear(2049);

console.log(now.toLocaleString()); // 12/6/2049, 7:40:04 PM

Note that there’s a shortcut where most of the set methods can take multiple arguments to set the other components. These two snippets produce the same result:
The tedious way

const now = new Date();

The shortcut

const now = new Date();

Adding/Subtracting Time #

Using a combination of the get and set methods, you can add to or subtract from the date/time components of a date instance. Here for example, we add 15 minutes to the current time:

const now = new Date();

console.log(now.toLocaleTimeString()); // 7:47:53 PM

now.setMinutes(now.getMinutes() + 15);

console.log(now.toLocaleTimeString()); // 8:02:53 PM