The Quirks of Date Math: Leap Years, Gregorian Calendars, and Age Calculations

Why Calculating Dates is One of Software’s Hardest Problems#

Unlike units of mass or length which adhere to strict decimal ratios, calendar time is an irregular historical construct:

• Months vary between 28, 29, 30, and 31 days.
• Years vary between 365 and 366 days.
• Days vary between 23, 24, and 25 hours during Daylight Saving Time transitions.
• Timezones shift across political boundaries.

The Astronomical Solar Year and the 400-Year Leap Rule#

The Earth takes approximately **365.24219 days** (a tropical year) to orbit the Sun. If we used a flat 365-day calendar, the seasons would drift by roughly 24 days every century.

To compensate, the Gregorian Calendar established three precise rules for leap years:

1. Every year divisible by 4 is a leap year (e.g. 2024, 2028).

2. EXCEPT years divisible by 100 are NOT leap years (e.g. 1900, 2100).

3. EXCEPT years divisible by 400 ARE leap years (e.g. 2000, 2400).

How to Calculate Exact Age (Years, Months, Days)#

An accurate age calculation requires rolling backward when current days or months are less than the birth date:

function calculateExactAge(birthDate: Date, targetDate: Date = new Date()) {
  let years = targetDate.getFullYear() - birthDate.getFullYear();
  let months = targetDate.getMonth() - birthDate.getMonth();
  let days = targetDate.getDate() - birthDate.getDate();

  if (days < 0) {
    months -= 1;
    // Get days in preceding month
    const prevMonthDays = new Date(targetDate.getFullYear(), targetDate.getMonth(), 0).getDate();
    days += prevMonthDays;
  }
  if (months < 0) {
    years -= 1;
    months += 12;
  }
  return { years, months, days };
}

Handling February 29th (Leap Day) Birthdays Legally#

In non-leap years, people born on February 29 legally reach their next age milestone on March 1 in the UK and US, whereas countries like New Zealand and Taiwan recognize February 28 as the legal birthday in non-leap years.

Avoiding Date Math Pitfalls in JavaScript/TypeScript#

Never compute differences by simply dividing millisecond timestamps by `(1000 * 60 * 60 * 24 * 365.25)`. This ignores month-boundary geometry and causes off-by-one-day calculation errors.