How to Use Date.parse in JavaScript

The Date.parse() method can help while dealing with calculations including dates. These calculations are far easier, more accurate, and written more logically when the underlying date is represented as a Number rather than a string.

The Date.parse() method takes as an argument a string representing a date, and returns the number of milliseconds that have elapsed between January 1, 1970, 00:00:00 UTC and the date provided. If the string provided is invalid, or is not recognized as a date format for some reason, the Date.parse() method returns NaN.

According to MDN, it is not recommended to use Date.parse. Their reasoning provided is: ”… until ES5, parsing of strings was entirely implementation dependent. There are still many differences in how different hosts parse date strings, therefore date strings should be manually parsed (a library can help if many different formats are to be accommodated).” In recognition of this, we provide some other options below under Convert a date String into a UNIX timestamp.

Syntax

The Date.parse() method has the following syntax:

Date.parse(dateString)

This method accepts only a single parameter:

dateString – A string representing a date in the ISO 8601 calendar date extended format. Note – different browsers may support other formats in addition to ISO 8601.

The ISO 8601 date format is as follows: YYYY-MM-DDTHH:mm:ss.sssZ. The characters represent the following data:

• YYYY – the current year, in four digits (e.g. 2020)
• MM – the current month, with a leading 0 (e.g. 09, 11)
• DD – The current day of the month, with a leading 0 (e.g. 07, 17)
• T – the literal character T, which is used to mark the beginning of the timestamp
• HH – The current hour, in 24 hour format (e.g. 09, 13, 22)
• mm – The current minute of the hour, with a leading 0 where needed (e.g. 08, 54)
• ss.sss – The current seconds and milliseconds (e.g. 03.444, 24.536)
• Z – the literal character Z, which is used to mark the end of the timestamp

More about the Date Time String Format can be found here.

At a minimum, the year is mandatory. If a value is not provided in the input string, it will be given its minimum value (i.e. the month will be January if no month is provided, the time will be midnight if no timestamp is provided). If the value specified is invalid for any of the portions of the timestamp string (e.g. month is set to ‘00’), NaN is returned.

Years can be passed in as four decimal digits (i.e. 2020) or 6 decimal digits with a + or – operator attached.

Basic examples

Below are some basic examples of how to use Date.parse() to parse a date string:

const unixZeroT = Date.parse('1970');
console.log(unixZeroT); // expected output: 0

In the above example only the year is specified, causing the timestamp to default to Midnight, January 1st, 1970. As this represents the starting value for the timestamp comparison, a zero is returned.

const justNow = Date.parse('+002020-08-09T15:00:00.000');
console.log(justNow); // expected output: 1596974400000

In the above example the year was specified with 6 digits and a plus operator at the beginning. This String stands for August 9, 2020 15:00 PM UTC, and the return value represents the number of milliseconds between that date and January 1st, 1970 00:00 AM UTC.

Convert a date String into a UNIX timestamp

Per the MDN guidance, there are two additional methods that can be used to obtain a numeric representation of a given date. The two methods we will look at are Date.now() and getTime().

const date = new Date();
const time1 = Date.now(date);
console.log(time1); // expected output: 1596987649975
const time2 = date.getTime();
console.log(time2); // expected output: 1596987649975

In the examples above, the variable date is assigned with a date string. Both Date.now() and getTime() convert the date string into a UNIX timestamp.

Note: the results of both methods above are exactly the same, as they represent different means of getting the same information – the number of milliseconds elapsed since January 1, 1970.

Related Articles:

JavaScript – How to Format Date

JavaScript – How to Get an Object’s Keys and Values

JavaScript – How to Use Option Selected Property