Normalize date input
Convert an API date string into an epoch-millisecond value for comparison or storage.
JS Puzzles · Const
Date parsing
Date.parse(str) reads a date from a string and returns its timestamp in milliseconds since 1 January 1970 UTC. Invalid formats produce NaN.
How it works
Date.parse(str) interprets a date string and returns the corresponding timestamp: the number of milliseconds since 1 January 1970 in UTC. It accepts the full date-time form or shorter year, year-month, and year-month-day forms; an invalid format produces NaN.
Syntax
Date.parse(str)Parameters
| Name | Type | Description |
|---|---|---|
str | string | A date string in the documented date-time format or one of its shorter variants. |
Returns
A timestamp: the number of milliseconds from 1 January 1970 UTC+0, or NaN for an invalid format.
Key points
- Date.parse takes one string argument and interprets it as a date.
- The complete documented pattern combines a calendar date, a T separator, a time, optional fractional seconds, and zone information.
- T divides the date portion from the time portion.
- A numeric offset such as -07:00 identifies the offset from UTC.
- The parser also permits date-only strings with reduced precision.
- Successful parsing produces an epoch-millisecond number rather than a Date object.
Common mistakes
- Parsing failure does not throw an exception; Date.parse returns NaN, so check with Number.isNaN before using the result.
- The standalone Z designates UTC+0, while a numeric offset expresses a different time zone.
Example: Parse an ISO-style date string
const timestamp = Date.parse('2012-01-26T13:51:50.417-07:00');
if (Number.isNaN(timestamp)) {
throw new Error('Invalid date');
}
console.log(timestamp);Parses a date-time string with an explicit offset and prints its millisecond timestamp.
When to use it
Build a Date object
Create a Date instance from a parsed timestamp when date methods are needed.
Check parsing success
Validate a date string before accepting it in application input.
Interview questions
QWhat does Date.parse return?
Date.parse(str) converts a supported date string into a numeric timestamp measured in milliseconds from 1 January 1970 UTC. It returns NaN when the format is invalid.
Follow-up: How would you safely use the result? Check Number.isNaN(timestamp) before constructing a Date or performing calculations.
QWhat string format does Date.parse accept?
The documented full form is YYYY-MM-DDTHH:mm:ss.sssZ. T separates the date and time, the fractional seconds are optional in shorter forms, and Z or a numeric offset supplies time-zone information.
Follow-up: What shorter inputs are supported? YYYY, YYYY-MM, and YYYY-MM-DD are documented shorter variants.
QWhat is the meaning of the returned number?
A valid parsed value is a timestamp, meaning milliseconds counted from 1 January 1970 at UTC+0. This numeric result can be passed to the Date constructor to create a Date object.
Follow-up: What should happen for malformed input? Treat NaN as invalid rather than as a usable timestamp.
Related
DateDate constructorDate.parse