fix: prevent mixed-sign diff durations

Author: justin-schroeder

src/__tests__/diff.spec.ts

@@ -1,10 +1,14 @@
 import { afterEach, describe, expect, it, vi } from "vitest"
-import { addDay, addSecond, date, diff } from "../index"
+import { add, addDay, addSecond, date, diff } from "../index"
 
 afterEach(() => {
   vi.useRealTimers()
 })
 
+function expectAllPositive(duration: Record<string, number>) {
+  expect(Object.values(duration).every((value) => value > 0)).toBe(true)
+}
+
 describe("diff", () => {
   it("returns a duration with calendar and time units", () => {
     expect(diff("2025-04-01 12:00:50", "2024-01-01 12:00:00")).toEqual({
@@ -63,4 +67,35 @@ describe("diff", () => {
       minutes: 245,
     })
   })
+
+  it("does not emit mixed signs when calendar units clamp", () => {
+    const duration = diff("2025-02-28", "2024-02-29", { abs: true })
+
+    expect(duration).toEqual({
+      months: 11,
+      weeks: 3,
+      days: 7,
+    })
+    expectAllPositive(duration)
+  })
+
+  it("keeps leap-day calendar boundary durations round-trippable", () => {
+    const start = "2024-02-29"
+    const end = "2025-02-28"
+
+    expect(add(start, diff(end, start))).toEqual(date(end))
+    expect(add(end, diff(start, end))).toEqual(date(start))
+  })
+
+  it("uses days instead of negative fields when weeks are skipped", () => {
+    const duration = diff("2025-02-28", "2024-02-29", { skip: ["weeks"] })
+
+    expect(duration).toEqual({
+      months: 11,
+      days: 27,
+      hours: 24,
+    })
+    expectAllPositive(duration)
+    expect(add("2024-02-29", duration)).toEqual(date("2025-02-28"))
+  })
 })

src/diff.ts

@@ -25,6 +25,21 @@ function negateDuration(duration: Duration): Duration {
   return negated
 }
 
+function calendarDiff(
+  current: Date,
+  target: Date,
+  diffUnit: (dateA: Date, dateB: Date) => number,
+  addUnit: (date: Date, count: number) => Date
+): [number, Date] {
+  let amount = diffUnit(current, target)
+  let next = addUnit(current, -amount)
+  while (amount > 0 && next < target) {
+    amount--
+    next = addUnit(current, -amount)
+  }
+  return [amount, next]
+}
+
 /**
  * Options for `diff` function
  */
@@ -86,14 +101,14 @@ export function diff(
   const duration: Duration = {}
 
   if (!skip.has("years")) {
-    const years = diffYears(a, b)
-    a = addYear(a, -years)
+    const [years, next] = calendarDiff(a, b, diffYears, addYear)
+    a = next
     if (years) duration.years = years
   }
 
   if (!skip.has("months")) {
-    const months = diffMonths(a, b)
-    a = addMonth(a, -months)
+    const [months, next] = calendarDiff(a, b, diffMonths, addMonth)
+    a = next
     if (months) duration.months = months
   }