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.
The Date.parse() method has the following syntax:
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.
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.
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.