Calculations of years and months wrong due to leap years

The constants used for milliseconds in a year and milliseconds in a month are incorrect because they are computed from the slightly naïve understanding of leap days in the Gregorian calendar.

A leap day occurs every four years. However, because that’s actually slightly too often, if the year is divisible by 100 then it is not a leap year. However, because that would be too infrequent, if the year is divisible by 400 they it is a leap year.

Thus the correct decimal representation of the average length of a year is 365.2425 days. Likewise, since the year is 12 exact months, an average length of a month is 30.436875 days.

[EvanHahn]

Did some more thinking about this, finally.

I think there are a few distinct questions at hand:

1. Is this a breaking change?
2. What should the default durations for months and years be, if at all?
3. Which units should be included by default?

The answer to the first question is easy: if we change anything, then it’s a breaking change. (I started a branch for the next major version if you want to follow along.)

The other two questions are trickier.

Wikipedia provides a list of time units. Milliseconds, seconds, minutes, hours, days, and weeks are constant. Months and years, however, have a range. In other words, it’s easy to answer “how long is an hour, in milliseconds?” and impossible to answer “how long is a month, in milliseconds?”

To inform what we should do, I looked at what other folks do.

• Python’s official timedelta only goes up to weeks, presumably because of this ambiguity.
• Go’s official Duration stringification only goes up to hours, and they claim “days can be different lengths”. I don’t know more about this.
• Rails’s distance_of_time_in_words sidesteps this problem with inexact measurements (e.g., “about 6 years”).
• pretty-ms says that years are 365 days and doesn’t support months or weeks, after the maintainer acknowledged this ambiguity.
• millisec doesn’t know about weeks, months, or years (though there is an issue about it).

Many others don’t deal with this problem at all:

• Python’s unofficial dateutils.relativedelta doesn’t seem to do humanization at all, and durations for units don’t seem to be specified.
• Moment’s .diff function is date-aware, but HumanizeDuration.js only deals with milliseconds (even so, they had a bunch of issues with month/year differences)

My rough takeaway from the above: if your library deals with exact durations (e.g., “1.7 minutes” instead of “about 2 minutes”), then you either (1) don’t deal with months and years (2) treat them carefully.

I’d like to continue to support months and years, because I think they’re useful.

Given that, I think HumanizeDuration.js should:

1. Remove mo and y from the default list. For example, by default, humanizing 400 days should humanize to 57 weeks, 1 day, not something like 1 year, 1 month, ....
2. Allow users to opt-in to mo and y, and allow them to set the unit duration as they see fit. This is already supported with the unitMeasures option.
3. Consider updating the default durations of mo and y, as is done in #157.
4. Document the above clearly.

If that sounds good, I’ll do this in the next major version.

[EvanHahn]

Ah dates, always more complicated than I think.

I think your change in #157 is worthy but suffers from a similar problem as the issue reported in #152—these are arguably breaking changes. And because this library is in maintenance mode, I’m hesitant. However, they are also arguably bug fixes, in which case they would be in scope.

What do you think?