Fix calendar-aligned elapsed durations

src/duration.ts

@@ -126,17 +126,16 @@ export class Duration {
 }
 
 export function applyDuration(date: Date | number, duration: Duration): Date {
-  const r = new Date(date)
+  let r = new Date(date)
+  const calendarMonths = duration.years * 12 + duration.months
   if (duration.sign < 0) {
     r.setUTCSeconds(r.getUTCSeconds() + duration.seconds)
     r.setUTCMinutes(r.getUTCMinutes() + duration.minutes)
     r.setUTCHours(r.getUTCHours() + duration.hours)
     r.setUTCDate(r.getUTCDate() + duration.weeks * 7 + duration.days)
-    r.setUTCMonth(r.getUTCMonth() + duration.months)
-    r.setUTCFullYear(r.getUTCFullYear() + duration.years)
+    r = applyCalendarMonths(r, calendarMonths)
   } else {
-    r.setUTCFullYear(r.getUTCFullYear() + duration.years)
-    r.setUTCMonth(r.getUTCMonth() + duration.months)
+    r = applyCalendarMonths(r, calendarMonths)
     r.setUTCDate(r.getUTCDate() + duration.weeks * 7 + duration.days)
     r.setUTCHours(r.getUTCHours() + duration.hours)
     r.setUTCMinutes(r.getUTCMinutes() + duration.minutes)
@@ -145,6 +144,108 @@ export function applyDuration(date: Date | number, duration: Duration): Date {
   return r
 }
 
+/**
+ * Applies a number of calendar months to a copy of the reference date.
+ *
+ * @param reference - Date from which to count.
+ * @param months - Signed number of months to apply.
+ * @returns The resulting date without modifying the reference.
+ */
+function applyCalendarMonths(reference: Date, months: number): Date {
+  const result = new Date(reference)
+  const referenceDay = result.getUTCDate()
+
+  // Move from the first to avoid rolling an invalid date into the next month.
+  result.setUTCDate(1)
+  result.setUTCMonth(result.getUTCMonth() + months)
+  const targetMonth = result.getUTCMonth()
+  result.setUTCMonth(targetMonth + 1, 0)
+  result.setUTCDate(Math.min(referenceDay, result.getUTCDate()))
+  return result
+}
+
+/**
+ * Checks whether two UTC times match through the requested precision.
+ *
+ * @param date - Date being compared.
+ * @param reference - Reference date for the comparison.
+ * @param precisionIndex - Index of the requested unit in {@link unitNames}.
+ */
+function hasSameTimeAtPrecision(date: Date, reference: Date, precisionIndex: number): boolean {
+  if (precisionIndex <= unitNames.indexOf('day')) return true
+  if (date.getUTCHours() !== reference.getUTCHours()) return false
+  if (precisionIndex === unitNames.indexOf('hour')) return true
+  if (date.getUTCMinutes() !== reference.getUTCMinutes()) return false
+  if (precisionIndex === unitNames.indexOf('minute')) return true
+  if (date.getUTCSeconds() !== reference.getUTCSeconds()) return false
+  if (precisionIndex === unitNames.indexOf('second')) return true
+  return date.getUTCMilliseconds() === reference.getUTCMilliseconds()
+}
+
+/**
+ * Returns a calendar-based duration for completed calendar-month spans or
+ * endpoints aligned at the requested precision, leaving shorter intervals on
+ * the fixed-duration path.
+ *
+ * @param date - Target date.
+ * @param reference - Date from which elapsed time is measured.
+ * @param precisionIndex - Index of the requested unit in {@link unitNames}.
+ * @returns The corrected duration, or `undefined` when no correction is needed.
+ */
+function calendarElapsedTime(date: Date, reference: Date, precisionIndex: number): Duration | undefined {
+  const calendarMonths =
+    (date.getUTCFullYear() - reference.getUTCFullYear()) * 12 + date.getUTCMonth() - reference.getUTCMonth()
+
+  // Anchor the candidate month count to the reference, then back it off if it
+  // crossed the target. This prevents 30-day estimates from inventing a year.
+  let wholeMonths = calendarMonths
+  let anchor = applyCalendarMonths(reference, calendarMonths)
+  const candidateAligned =
+    anchor.getUTCFullYear() === date.getUTCFullYear() &&
+    anchor.getUTCMonth() === date.getUTCMonth() &&
+    anchor.getUTCDate() === date.getUTCDate() &&
+    hasSameTimeAtPrecision(date, anchor, precisionIndex)
+  const candidateOvershot =
+    calendarMonths !== 0 && !candidateAligned && (calendarMonths > 0 ? anchor > date : anchor < date)
+  if (candidateOvershot) {
+    wholeMonths += calendarMonths > 0 ? -1 : 1
+    anchor = applyCalendarMonths(reference, wholeMonths)
+  }
+
+  const isCalendarAligned =
+    anchor.getUTCFullYear() === date.getUTCFullYear() &&
+    anchor.getUTCMonth() === date.getUTCMonth() &&
+    anchor.getUTCDate() === date.getUTCDate() &&
+    hasSameTimeAtPrecision(date, anchor, precisionIndex)
+  if (!wholeMonths && !isCalendarAligned) return
+
+  // Calendar-aligned durations omit only units below the requested precision.
+  // Other corrected durations retain the remainder after the month anchor.
+  const sign = Math.sign(date.getTime() - reference.getTime())
+  const remainder = isCalendarAligned ? 0 : Math.abs(date.getTime() - anchor.getTime())
+  const seconds = Math.floor(remainder / 1000)
+  const minutes = Math.floor(seconds / 60)
+  const hours = Math.floor(minutes / 60)
+  const days = Math.floor(hours / 24)
+
+  let years = 0
+  let months = 0
+  const durationMonths = isCalendarAligned ? calendarMonths : wholeMonths
+  const durationYears = Math.trunc(durationMonths / 12)
+  if (precisionIndex >= unitNames.indexOf('year')) years = durationYears
+  if (precisionIndex >= unitNames.indexOf('month')) months = durationMonths - durationYears * 12
+  return new Duration(
+    years,
+    months,
+    0,
+    precisionIndex >= unitNames.indexOf('day') ? days * sign : 0,
+    precisionIndex >= unitNames.indexOf('hour') ? (hours - days * 24) * sign : 0,
+    precisionIndex >= unitNames.indexOf('minute') ? (minutes - hours * 60) * sign : 0,
+    precisionIndex >= unitNames.indexOf('second') ? (seconds - minutes * 60) * sign : 0,
+    precisionIndex >= unitNames.indexOf('millisecond') ? (remainder - seconds * 1000) * sign : 0,
+  )
+}
+
 export function elapsedTime(date: Date, precision: Unit = 'second', now = Date.now()): Duration {
   const delta = date.getTime() - now
   if (delta === 0) return new Duration()
@@ -157,6 +258,11 @@ export function elapsedTime(date: Date, precision: Unit = 'second', now = Date.n
   const month = Math.floor(day / 30)
   const year = Math.floor(month / 12)
   const i = unitNames.indexOf(precision)
+
+  const nowDate = new Date(now)
+  const calendarDuration = calendarElapsedTime(date, nowDate, i)
+  if (calendarDuration) return calendarDuration
+
   return new Duration(
     i >= 0 ? year * sign : 0,
     i >= 1 ? (month - year * 12) * sign : 0,

test/duration.ts

@@ -94,6 +94,8 @@ suite('duration', function () {
       {referenceDate: '2023-12-24T20:53:50.104Z', input: '-P1Y2M3DT4H5M6S', expected: '2022-10-21T16:48:44.104Z'},
       {referenceDate: '2023-08-15T00:00:00.000Z', input: 'P1Y3M25D', expected: '2024-12-10T00:00:00.000Z'},
       {referenceDate: '2024-12-10T00:00:00.000Z', input: '-P1Y3M25D', expected: '2023-08-15T00:00:00.000Z'},
+      {referenceDate: '2023-01-31T00:00:00.000Z', input: 'P1M', expected: '2023-02-28T00:00:00.000Z'},
+      {referenceDate: '2020-02-29T00:00:00.000Z', input: 'P1Y', expected: '2021-02-28T00:00:00.000Z'},
     ])
     for (const {referenceDate, input, expected} of tests) {
       test(`${referenceDate} -> ${input} -> ${expected}`, () => {
@@ -107,18 +109,18 @@ suite('duration', function () {
       {
         now: '2022-01-21T16:48:44.104Z',
         input: '2022-10-21T16:48:44.104Z',
-        expected: 'P9M3D',
+        expected: 'P9M',
       },
       {
         now: '2022-01-21T16:48:44.104Z',
         input: '2022-10-21T16:48:45.104Z',
-        expected: 'P9M3DT1S',
+        expected: 'P9MT1S',
       },
       {
         now: '2022-01-21T16:48:44.104Z',
         input: '2022-10-21T16:48:45.104Z',
         precision: 'day',
-        expected: 'P9M3D',
+        expected: 'P9M',
       },
       {
         now: '2022-10-21T16:44:44.104Z',
@@ -207,7 +209,7 @@ suite('duration', function () {
       {
         now: '2022-10-24T14:46:00.000Z',
         input: '2021-10-30T14:46:00.000Z',
-        expected: '-P11M29D',
+        expected: '-P11M25D',
       },
       {
         now: '2022-10-24T14:46:00.000Z',
@@ -218,7 +220,7 @@ suite('duration', function () {
       {
         now: '2022-10-24T14:46:00.000Z',
         input: '2021-10-29T14:46:00.000Z',
-        expected: '-P1Y',
+        expected: '-P11M26D',
       },
       {
         now: '2023-03-23T12:03:00.000Z',
@@ -237,6 +239,22 @@ suite('duration', function () {
         precision: 'year',
         expected: '-P2Y',
       },
+      {
+        now: '2023-01-01T00:00:00.000Z',
+        input: '2023-12-31T00:00:00.000Z',
+        precision: 'year',
+        expected: 'PT0S',
+      },
+      {
+        now: '2020-02-29T00:00:00.000Z',
+        input: '2021-02-28T00:00:00.000Z',
+        expected: 'P1Y',
+      },
+      {
+        now: '2023-01-31T00:00:00.000Z',
+        input: '2023-02-28T00:00:00.000Z',
+        expected: 'P1M',
+      },
       {
         now: '2022-10-24T14:46:00.000Z',
         input: '2024-10-24T14:46:00.000Z',