differenceInMonths

DifferenceInMonths is a date utility function that returns the number of full months between two dates. It is commonly used in date manipulation libraries such as date-fns and provides a signed integer: positive when the first date is after the second, negative when it is before.

How it works: the function compares the year and month components to establish a base month difference, computed as (yearLeft - yearRight) * 12 + (monthLeft - monthRight). It then adjusts for the days of the month; if the day of dateLeft is earlier than the day of dateRight, one month is subtracted to reflect that a complete month has not elapsed. Time of day is not counted toward the final month total, though time values can influence the result near month boundaries unless dates are normalized.

Return value: an integer representing the number of full months between the two dates. If the two dates are the same or within less than a full month (given their day components), the result may be zero. The result is negative if the first date precedes the second date.

Key considerations: differenceInMonths differs from differenceInCalendarMonths. The latter counts calendar month boundaries and ignores the day component entirely, while differenceInMonths takes into account the day of the month to determine whether a full month has passed. When using this function, ensure the inputs are valid Date objects or timestamps and be mindful of time zones and time parts if precise boundary handling is required.

Example: differenceInMonths(new Date(2020, 2, 15), new Date(2020, 0, 15)) returns 2.