Date.prototype.getTime()
Returns the number of milliseconds since the Unix epoch for a Date, the standard way to compare dates.
getTime()- Added in JavaScript ES1
Return value
numberA number representing the timestamp in milliseconds since the epoch (1 January 1970 00:00:00 UTC). Returns NaN if the date is invalid.
getTime() collapses a Date down to a single number: milliseconds elapsed since the epoch, always measured in UTC regardless of the machine's time zone. Because it is a plain number, it is the unit you do arithmetic in.
When to reach for it
- Subtracting two dates to get a duration:
end.getTime() - start.getTime()gives milliseconds. - Sorting an array of dates, or using a date as a stable key or cache stamp.
- Copying a date without sharing the object:
new Date(other.getTime()).
What trips people up
Comparing Date objects with === compares references, so two dates for the same instant are never equal. Compare timestamps instead. Relational operators (<, >, -) do work directly on dates because they coerce through valueOf(), which returns the same number as getTime().
An invalid date returns NaN, and NaN compares false against everything — including itself. If a date came from parsing user input, test it with Number.isNaN(d.getTime()) before trusting any arithmetic built on it.
For measuring how long code takes, performance.now() is the better tool: it is monotonic and higher resolution, whereas the system clock can jump.
Example
When to use it
- Compute how many days remain until a deadline
- Sort a list of records by their timestamp field
- Detect an invalid parsed date before doing arithmetic on it
- Clone a Date without both variables pointing at one object
Frequently asked questions
What is the difference between getTime() and valueOf()?
There is none in behaviour — both return the millisecond timestamp, and valueOf() is what the engine calls when a Date is coerced to a number. getTime() is the explicit form; valueOf() is why date2 - date1 works without calling anything.
How do I get the number of days between two dates in JavaScript?
Subtract the timestamps and divide by 86400000: (b.getTime() - a.getTime()) / 86400000. If you want whole calendar days rather than elapsed 24-hour periods, call setHours(0, 0, 0, 0) on copies of both dates first, otherwise the time-of-day components skew the result.
Why does getTime() return NaN?
Because the Date is an Invalid Date — it was built from a string the engine could not parse, or from an out-of-range value. Check with Number.isNaN(d.getTime()) rather than comparing the date itself, since NaN is not equal to anything including itself.
More examples
Guard against an invalid date
A Date built from unparseable text is still a Date object, so the only reliable check is that its timestamp is NaN. The third log shows getTime() returning NaN rather than throwing.
function daysUntil(input) {
const d = new Date(input);
if (Number.isNaN(d.getTime())) return null;
return Math.ceil((d.getTime() - Date.UTC(2024, 0, 1)) / 86400000);
}
console.log(daysUntil("2024-01-15"));
console.log(daysUntil("not a date"));
console.log(new Date("nonsense").getTime());Sorting and cloning by timestamp
Subtracting timestamps gives the numeric comparator sort() needs. The clone is a separate object, so mutating it leaves the original event untouched.
const events = [
{ name: "deploy", at: new Date("2024-05-03T09:00:00Z") },
{ name: "alert", at: new Date("2024-05-01T18:30:00Z") },
{ name: "rollback", at: new Date("2024-05-02T02:15:00Z") },
];
events.sort((x, y) => x.at.getTime() - y.at.getTime());
console.log(events.map((e) => e.name));
const copy = new Date(events[0].at.getTime());
copy.setUTCHours(0);
console.log(events[0].at.toISOString(), copy.toISOString());
Discussion