"How many days between these two dates?" sounds like a one-liner. Subtract, divide by 86,400,000, done. It works in most tests you will write, which is exactly why it ships with a bug.
I have been building small date and money calculators, and the date ones have produced more "wait, that's wrong" moments than anything else. Here are the four places it breaks, with outputs I ran myself (Node 24), and a version that does not.
The naive version
const MS_PER_DAY = 24 * 60 * 60 * 1000;
function naiveDays(a, b) {
return Math.floor((b - a) / MS_PER_DAY);
}
Fine in a quick test. Now run it in a machine set to US Eastern time:
const a = new Date(2026, 2, 1); // March 1, 2026, local midnight
const b = new Date(2026, 2, 31); // March 31, 2026, local midnight
(b - a) / MS_PER_DAY // 29.958333333333332
naiveDays(a, b) // 29
March 1 to March 31 is 30 days. You got 29, and the same code on a server running UTC returns 30. The bug only shows up for users in a time zone that changes its clocks.
Bug 1: not every day has 24 hours
In 2026 the US moved its clocks forward on March 8. That day is 23 hours long, so a span that crosses it is one hour short of a whole number of days. 29.958333... is 29 days plus 23 hours, which is what you get when you count the real elapsed time and not the calendar.
Going the other way, clocks fell back on November 1, 2026. October 1 to November 5 comes out as 35.041666..., so Math.floor happens to give the right answer there and Math.round would too. That is the nasty part: the same function is right in autumn and wrong in spring.
Math.round hides the problem for local-midnight dates, but I would not rely on it. If one of your inputs has a time of day, or comes from a different zone, rounding will eventually pick the wrong side.
Bug 2: date-only strings are parsed as UTC
Say you read the dates from a form or an API as "2026-03-01". JavaScript treats a date-only ISO string as UTC midnight, but prints it in local time:
new Date("2026-03-01").toString()
// "Sat Feb 28 2026 19:00:00 GMT-0500 (Eastern Standard Time)"
new Date("2026-03-01T00:00").toString()
// "Sun Mar 01 2026 00:00:00 GMT-0500 (Eastern Standard Time)"
Same-looking input, a different day on screen. Drop the T00:00 and anything that calls getDate() on it returns the 28th in New York. This is behind a lot of "my birthday shows up a day early" reports.
The fix: count calendar days, in UTC
A calendar day count has nothing to do with clocks, so take clocks out of it. Pull out the year, month and day, build UTC timestamps from those with Date.UTC, and subtract. UTC has no daylight saving, so every day is exactly 86,400,000 ms.
function daysBetween(a, b) {
const utc = (d) => Date.UTC(d.getFullYear(), d.getMonth(), d.getDate());
return Math.round((utc(b) - utc(a)) / MS_PER_DAY);
}
daysBetween(new Date(2026, 2, 1), new Date(2026, 2, 31)); // 30, in any time zone
I ran it with TZ set to America/New_York, UTC and Asia/Karachi. All three printed 30. If your inputs are date strings, split them yourself (const [y, m, d] = s.split("-").map(Number)) and call Date.UTC(y, m - 1, d) directly, so no local-time conversion ever happens.
The Math.round is only there to absorb floating point noise in the division. With UTC midnights the quotient is already a whole number.
Bug 3: leap years
February 28 to March 1 is 1 day in 2026 and 2 days in 2024. The UTC approach gets that right for free, because it uses the real calendar. The place people go wrong is when they write their own leap year check. The rule has three parts:
const isLeap = (y) => (y % 4 === 0 && y % 100 !== 0) || y % 400 === 0;
[1900, 2000, 2024, 2026, 2100].map(isLeap);
// [false, true, true, false, false]
Forget the 100 and 400 rules and 1900 and 2100 come out wrong. Better still, do not write the check at all: let Date.UTC handle it, as above. A year from January 1, 2024 to January 1, 2025 is 366 days with that function, and 2026 to 2027 is 365.
Bug 4: "how many months and days?"
Total days is the easy question. The question people really ask is "how long is that in years, months and days?", and here there is no single right answer, only a convention.
How long is January 31 to March 1, 2026? In total days it is 29. In months and days, you first have to decide what "one month after January 31" means, because February has no 31st. The usual convention (used by Python's dateutil, among others) clamps to the last day of the month: January 31 plus one month is February 28, and then one more day gets you to March 1. So the answer is 1 month, 1 day.
The textbook method of borrowing days from the previous month, the way you did subtraction at school, goes wrong here. I wrote it first and got [0, 1, -2], a negative number of days. Clamping fixes it:
const dim = (y, m) => new Date(Date.UTC(y, m, 0)).getUTCDate(); // m is 1-12
function addMonths([y, m, d], n) {
const t = y * 12 + (m - 1) + n;
const ny = Math.floor(t / 12), nm = (t % 12) + 1;
return [ny, nm, Math.min(d, dim(ny, nm))];
}
function diffYMD(a, b) { // a and b are [year, month, day], a <= b
const ts = ([y, m, d]) => Date.UTC(y, m - 1, d);
let months = (b[0] - a[0]) * 12 + (b[1] - a[1]);
let start = addMonths(a, months);
if (ts(start) > ts(b)) { months--; start = addMonths(a, months); }
const days = Math.round((ts(b) - ts(start)) / MS_PER_DAY);
return { years: Math.floor(months / 12), months: months % 12, days };
}
I checked it against dateutil.relativedelta on seven date pairs, and the answers matched on all of them:
| From | To | Years, months, days |
|---|---|---|
| 2026-01-31 | 2026-03-01 | 0, 1, 1 |
| 2024-01-31 | 2024-03-01 | 0, 1, 1 |
| 2026-03-31 | 2026-04-30 | 0, 1, 0 |
| 1990-05-15 | 2026-11-18 | 36, 6, 3 |
| 2024-02-29 | 2025-02-28 | 1, 0, 0 |
| 2024-02-29 | 2025-03-01 | 1, 0, 1 |
| 2000-02-29 | 2026-02-28 | 26, 0, 0 |
The leap day rows are the awkward ones. Whether someone born on February 29 turns a year older on February 28 or March 1 is a legal question and differs by country, so the "right" output depends on your product.
A short checklist
- Count calendar days with
Date.UTC, not with localDatesubtraction. - Do not parse date-only strings and then read them back in local time.
- Let the runtime handle leap years. If you must write the check, use all three rules.
- For "years, months and days", pick a convention, write it down, and test the month-end and leap-day cases.
- Decide whether your count is inclusive. January 1 to January 1 is 0 days, but many people expect 1 if they are counting a stay or a deadline.
If you want to compare your results against something while you test, there is a free date difference calculator you can use for that kind of sanity check. Newer runtimes are also adding the Temporal API, which is built to avoid most of the traps above. It was not available in the Node 24 build I tested on, so I stuck with plain Date.
Disclosure: I run MultiCalify, a free calculator site, and the link above points to it.
Top comments (0)