A Date object instance represents a single point in time.

Despite being named Date, it also handles time.

Initialize the Date object

We initialize a Date object by using

new Date()

This creates a Date object pointing to the current moment in time.

Internally, dates are expressed in milliseconds since Jan 1st 1970 (UTC). This date is important because as far as computers are concerned, that’s where it all began.

You might be familiar with the UNIX timestamp: that represents the number of seconds that passed since that famous date.

Important: the UNIX timestamp reasons in seconds. JavaScript dates reason in milliseconds.

If we have a UNIX timestamp, we can instantiate a JavaScript Date object by using

const timestamp = 1530826365
new Date(timestamp * 1000)

unless the timestamp was generated by JS, in which case it’s already in the correct scale.

Make sure you pass a number (a string will get you an “invalid date” result - use parseInt() in doubt)

If we pass 0 we’d get a Date object that represents the time at Jan 1st 1970 (UTC):

new Date(0)

Creating dates from strings

If we pass a string rather than a number, then the Date object uses the parse method to determine which date you are passing. Examples:

new Date('2018-07-22')
new Date('2018-07') //July 1st 2018, 00:00:00
new Date('2018') //Jan 1st 2018, 00:00:00
new Date('07/22/2018')
new Date('2018/07/22')
new Date('2018/7/22')
new Date('July 22, 2018')
new Date('July 22, 2018 07:22:13')
new Date('2018-07-22 07:22:13')
new Date('2018-07-22T07:22:13')
new Date('25 March 2018')
new Date('25 Mar 2018')
new Date('25 March, 2018')
new Date('March 25, 2018')
new Date('March 25 2018')
new Date('March 2018') //Mar 1st 2018, 00:00:00
new Date('2018 March') //Mar 1st 2018, 00:00:00
new Date('2018 MARCH') //Mar 1st 2018, 00:00:00
new Date('2018 march') //Mar 1st 2018, 00:00:00

There’s lots of flexibility here. You can add, or omit, the leading zero in months or days.

Be careful with the month/day position, or you might end up with the month being misinterpreted as the day.

You can also use Date.parse:

Date.parse('2018-07-22')
Date.parse('2018-07') //July 1st 2018, 00:00:00
Date.parse('2018') //Jan 1st 2018, 00:00:00
Date.parse('07/22/2018')
Date.parse('2018/07/22')
Date.parse('2018/7/22')
Date.parse('July 22, 2018')
Date.parse('July 22, 2018 07:22:13')
Date.parse('2018-07-22 07:22:13')
Date.parse('2018-07-22T07:22:13')

Date.parse will return a timestamp (in milliseconds) rather than a Date object.

Creating dates from parameters

You can also pass a set of ordered values that represent each part of a date: the year, the month (starting from 0), the day, the hour, the minutes, seconds and milliseconds:

new Date(2018, 6, 22, 7, 22, 13, 0)
new Date(2018, 6, 22)

The minimum should be 3 parameters, but most JavaScript engines also interpret less than these:

new Date(2018, 6) //Sun Jul 01 2018 00:00:00 GMT+0200 (Central European Summer Time)
new Date(2018) //Thu Jan 01 1970 01:00:02 GMT+0100 (Central European Standard Time)

In any of these cases, the resulting date is relative to the timezone of your computer. This means that two different computers might output a different value for the same date object.

JavaScript, without any information about the timezone, will consider the date as UTC, and will automatically perform a conversion to the current computer timezone.

Summary: 4 ways to create a Date

• passing no parameters, creates a Date object that represents the current date and time
• passing a number, which represents the milliseconds from 1 Jan 1970 00:00 GMT
• passing a string, which represents a date
• passing a set of parameters, which represent the different parts of a date

Timezones

When initializing a date you can pass a timezone, so the date is not assumed UTC and then converted to your local timezone.

You can specify a timezone by adding it in +HOURS format, or by adding the timezone name wrapped in parentheses:

new Date('July 22, 2018 07:22:13 +0700')
new Date('July 22, 2018 07:22:13 (CET)')

If you specify a wrong timezone name in the parentheses, JavaScript will default to UTC without complaining.

If you specify a wrong numeric format, JavaScript will complain with an “Invalid Date” error.

Overflow handling

Pay attention. If you overflow a month with the days count, there will be no error, and the date will go to the next month:

new Date(2018, 6, 40) //Thu Aug 09 2018 00:00:00 GMT+0200 (Central European Summer Time)

The same goes for months, hours, minutes, seconds and milliseconds.

Lessons in this unit:

0:	Introduction
1:	▶︎ Date Basics
2:	Getting Date Parts
3:	Date Formatting
4:	Date Math
5:	Date Comparisons
6:	Date Recipes