Date.prototype.valueOf()
Returns the date's timestamp in milliseconds since the Unix epoch, or NaN if it is invalid.
valueOf()- Added in JavaScript ES1 (1997)
Return value
numberA number representing the timestamp, in milliseconds, of this date since the epoch — midnight at the beginning of 1 January 1970, UTC. Returns NaN if the date is invalid.
Errors
Throws a TypeError if called on a value that does not have the internal date slot.
Changelog
- PHP ES6 (2015)Symbol.toPrimitive was added to Date.prototype and takes priority during coercion; it still calls valueOf() for the number hint, so arithmetic behaviour is unchanged.
valueOf() returns the single number a Date actually stores: milliseconds since the Unix epoch. It is functionally identical to getTime(); the difference is who calls it. valueOf() is part of the coercion protocol, invoked automatically whenever a Date is used where a number is expected.
Why date2 - date1 gives milliseconds
The - operator coerces both operands with a number hint. For a Date, that reaches Symbol.toPrimitive, which delegates to valueOf(). So the subtraction is plain arithmetic on two epoch millisecond counts, and the result is a duration in milliseconds — divide by 1000, 60000 or 86400000 for seconds, minutes or days.
The same coercion makes <, > and sorting work: dates.sort((a, b) => a - b) sorts chronologically for free.
Where it does not apply
+ uses the default hint, which for Date resolves to toString() — so date + 1 concatenates. Write +date + 1 or date.valueOf() + 1.
== and === compare object identity, not timestamps: two Dates for the same instant are never ===. Compare a.valueOf() === b.valueOf() instead.
Validity check
An invalid date returns NaN, which makes Number.isNaN(d.valueOf()) the reliable test — string comparisons against "Invalid Date" are not.
Example
When to use it
- Measuring the elapsed time between two events in milliseconds
- Sorting an array of dates with sort((a, b) => a - b)
- Testing whether a parsed date is valid before using it
- Storing a compact numeric timestamp instead of a string
Frequently asked questions
Why does subtracting two dates give milliseconds?
Because the - operator coerces each Date with a number hint, which calls valueOf() and yields milliseconds since the epoch. Divide the difference by 1000 for seconds, 60000 for minutes, or 86400000 for days.
What is the difference between valueOf and getTime?
Nothing functionally — both return the same millisecond timestamp. valueOf() is the method the language calls during numeric coercion, while getTime() is the one you call explicitly.
How do I check whether two dates are equal?
Compare their timestamps: a.valueOf() === b.valueOf(), or equivalently a - b === 0. The === operator compares object identity, so two distinct Date objects for the same instant are never strictly equal.
More examples
Equality needs valueOf
Both equality operators compare object references and report false, while every numeric comparison sees the same timestamp. The a <= b && a >= b trick works for the same reason.
const a = new Date("2024-01-01T00:00:00Z");
const b = new Date("2024-01-01T00:00:00Z");
console.log(a === b);
console.log(a == b);
console.log(a.valueOf() === b.valueOf());
console.log(a - b === 0);
console.log(a <= b && a >= b);Sorting and finding extremes
Subtraction inside the comparator uses valueOf, so no explicit conversion is needed. Math.max cannot take Dates directly, so map to timestamps first and wrap the winner back in a Date.
const dates = [
new Date("2024-03-01T00:00:00Z"),
new Date("2023-11-15T00:00:00Z"),
new Date("2024-01-20T00:00:00Z"),
];
console.log(dates.sort((x, y) => x - y).map((d) => d.toISOString().slice(0, 10)));
console.log(new Date(Math.max(...dates.map((d) => d.valueOf()))).toISOString().slice(0, 10));Validity and the plus-operator trap
NaN propagates from an invalid date's valueOf, giving a dependable validity check. The typeof lines show + producing a string until a unary + forces the number hint.
function isValid(d) {
return d instanceof Date && !Number.isNaN(d.valueOf());
}
console.log(isValid(new Date("2024-02-29")), isValid(new Date("2024-02-30x")));
const d = new Date(Date.UTC(2024, 0, 1));
console.log(typeof (d + 1));
console.log(typeof (+d + 1));
console.log(new Date(d.valueOf() + 86_400_000).toISOString().slice(0, 10));
Discussion