daymath 0.2.2 → 0.3.0

package/README.md

@@ -1,19 +1,31 @@
 # daymath
 
 [![npm](https://img.shields.io/npm/v/daymath.svg)](https://www.npmjs.com/package/daymath)
+[![ci](https://github.com/leemr/daymath/actions/workflows/ci.yml/badge.svg)](https://github.com/leemr/daymath/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/leemr/daymath/graph/badge.svg)](https://codecov.io/gh/leemr/daymath)
 [![license](https://img.shields.io/npm/l/daymath.svg)](./LICENSE)
 [![node](https://img.shields.io/node/v/daymath.svg)](https://www.npmjs.com/package/daymath)
 
 **ISO 8601** calendar day math. **date-fns-shaped** names. **Temporal.PlainDate** under the hood.
 
-No `Date`. No time zones. No silent “local now.”
+No `Date`. No time zones. No silent “local now.” ISO 8601 ❤️
 
-[**Play in the browser →**](https://leemr.github.io/daymath/) · [npm](https://www.npmjs.com/package/daymath) · [FUTURE.md](./FUTURE.md)
+[**Play →**](https://leemr.github.io/daymath/) · [npm](https://www.npmjs.com/package/daymath) · [Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md) · [FUTURE](./FUTURE.md)
 
 ```bash
 npm install daymath
 ```
 
+Same code also publishes to **GitHub Packages** as `@leemr/daymath` (scoped; see [GitHub npm registry docs](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)):
+
+```bash
+# one-time: map the scope (auth with a PAT that has read:packages, or GITHUB_TOKEN in Actions)
+echo '@leemr:registry=https://npm.pkg.github.com' >> .npmrc
+npm install @leemr/daymath
+```
+
+Most people should keep using **`daymath` on npmjs**.
+
 ```js
 import { addDays, addMonths, differenceInDays, isSameDay } from 'daymath'
 
@@ -23,6 +35,10 @@ differenceInDays('2026-08-06', '2026-08-01') // 5
 isSameDay('2026-08-06', '2026-08-06')        // true
 ```
 
+```bash
+node examples/basic.mjs   # from a clone
+```
+
 ## Why
 
 `Date` is a timestamp. Hire dates, passport expiry, trip days are **calendar** values. daymath only does plain days as ISO strings.
@@ -34,6 +50,8 @@ isSameDay('2026-08-06', '2026-08-06')        // true
 
 `Date` **throws** (including `isValid`). `isValid('asdf')` → `false`.
 
+Range: `-271821-04-19` … `+275760-09-13` — the `Temporal.PlainDate` limit, roughly ±10⁸ days from the epoch. A day outside it throws a `RangeError`.
+
 ## date-fns parity (names, not `Date`)
 
 | Topic | daymath |
@@ -41,9 +59,9 @@ isSameDay('2026-08-06', '2026-08-06')        // true
 | Values | ISO day **strings**, not `Date` |
 | `isSameDay` | Alias of `isEqual` |
 | `isValid` | Valid daymath day; **`Date` throws** |
-| `getMonth` / `setMonth` | **0–11** (0 = January) |
-| `getDay` | **0–6** (0 = Sunday) |
-| `weekStartsOn` | default `0` (Sunday) |
+| `getMonth` / `setMonth` | **1–12** (1 = January) — ISO, **not** date-fns |
+| `getDay` | **1–7** (1 = Monday, 7 = Sunday) — ISO, **not** date-fns |
+| `weekStartsOn` | default `7` (Sunday); `0` also accepted |
 | Intervals | `{ start, end }` |
 
 ## API
@@ -72,13 +90,17 @@ Uses global `Temporal` when present; otherwise [`temporal-polyfill`](https://www
 
 ## Types & tests
 
-Plain JS + `index.d.ts` (no compile step).
+Plain JS + `index.d.ts` (no compile step). CI runs on Node 18, 20, 22, 24, and 26; the coverage gate runs on 24.
 
 ```bash
 npm test
-npm run test:coverage   # 100% lines on index.js
+npm run test:coverage   # c8: 100% lines/funcs/branches on index.js + lcov
 ```
 
+CI uploads coverage to [Codecov](https://codecov.io/gh/leemr/daymath) (see [CONTRIBUTING.md](./CONTRIBUTING.md) for one-time app/token setup).
+
+PRs welcome via fork — see [CONTRIBUTING.md](./CONTRIBUTING.md). Security reports: [SECURITY.md](./SECURITY.md).
+
 ## License
 
 MIT

package/index.d.ts

@@ -4,6 +4,9 @@ import type { Temporal } from 'temporal-polyfill'
  * Calendar day input: ISO 8601 day string, or a Temporal.PlainDate.
  * - `YYYY-MM-DD` (years 0000–9999)
  * - expanded `±YYYYYY-MM-DD` (e.g. `+010000-01-01`)
+ *
+ * Usable range is the Temporal `PlainDate` range `-271821-04-19` …
+ * `+275760-09-13`; a day outside it throws a `RangeError`.
  * `Date` is rejected at runtime (TypeError).
  */
 export type DayInput = string | Temporal.PlainDate
@@ -15,10 +18,12 @@ export type Interval = {
 }
 
 /**
- * Week options. `weekStartsOn`: 0 = Sunday … 6 = Saturday (date-fns default 0).
+ * Week options. `weekStartsOn`: ISO 1 = Monday … 7 = Sunday (default 7).
+ * `0` is also accepted for Sunday — 0 ≡ 7 (mod 7), so pre-0.3.0 callers keep
+ * working with no change in behaviour.
  */
 export type WeekOptions = {
-  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7
 }
 
 /**
@@ -46,11 +51,11 @@ export function subQuarters(date: DayInput, amount: number): string
 
 /** Full year number. */
 export function getYear(date: DayInput): number
-/** Month index like Date/date-fns: 0 = January … 11 = December. */
+/** Month number, ISO 8601: 1 = January … 12 = December. Not date-fns's 0-based index. */
 export function getMonth(date: DayInput): number
 /** Day of month 1…31. */
 export function getDate(date: DayInput): number
-/** Weekday like Date/date-fns: 0 = Sunday … 6 = Saturday. */
+/** Weekday, ISO 8601: 1 = Monday … 7 = Sunday. Only Sunday differs from date-fns. */
 export function getDay(date: DayInput): number
 export function getDayOfYear(date: DayInput): number
 export function getDaysInMonth(date: DayInput): number
@@ -59,7 +64,7 @@ export function getQuarter(date: DayInput): number
 export function isLeapYear(date: DayInput): boolean
 
 export function setYear(date: DayInput, year: number): string
-/** `month`: 0 = January … 11 = December (date-fns). */
+/** `month`: 1 = January … 12 = December (ISO 8601). */
 export function setMonth(date: DayInput, month: number): string
 export function setDate(date: DayInput, dayOfMonth: number): string
 

package/index.js

@@ -7,6 +7,11 @@ const Temporal = globalThis.Temporal ?? TemporalPolyfill
  * ISO 8601 calendar day string:
  * - `YYYY-MM-DD` (years 0000–9999)
  * - expanded `±YYYYYY-MM-DD` (Temporal form, e.g. `+010000-01-01`)
+ *
+ * The shape passes this regex; the value must also fall inside the Temporal
+ * `PlainDate` range `-271821-04-19` … `+275760-09-13` (roughly ±10^8 days from
+ * the epoch). Outside it, Temporal throws and we re-throw with the `daymath:`
+ * prefix.
  */
 const ISO_DAY =
   /^(?:[+-]\d{6}|\d{4})-\d{2}-\d{2}$/
@@ -19,7 +24,9 @@ const ISO_DAY =
  */
 /**
  * @typedef {object} WeekOptions
- * @property {0|1|2|3|4|5|6} [weekStartsOn] 0=Sun … 6=Sat (date-fns default 0)
+ * @property {0|1|2|3|4|5|6|7} [weekStartsOn] ISO 1=Mon … 7=Sun (default 7).
+ * `0` is also accepted for Sunday, because 0 ≡ 7 (mod 7) and the week-offset
+ * arithmetic cannot tell them apart. Pre-0.3.0 callers keep working unchanged.
  */
 
 // ─── core conversion ───────────────────────────────────────────────
@@ -63,11 +70,6 @@ function toDayString(plain) {
   return plain.toString()
 }
 
-/** Temporal ISO weekday 1=Mon…7=Sun → JS/date-fns 0=Sun…6=Sat */
-function isoToJsWeekday(isoDayOfWeek) {
-  return isoDayOfWeek === 7 ? 0 : isoDayOfWeek
-}
-
 /** @param {unknown} n @param {string} label */
 function assertFiniteNumber(n, label) {
   if (typeof n !== 'number' || !Number.isFinite(n)) {
@@ -78,6 +80,40 @@ function assertFiniteNumber(n, label) {
   }
 }
 
+/**
+ * Run a Temporal op and keep the `daymath:` message contract when it fails.
+ * Temporal throws bare `Out-of-bounds date` / `Non-positive day`; we prefix and
+ * keep the original text plus `cause`. Covers both a result past the range and
+ * an argument Temporal refuses outright, hence the neutral wording.
+ * @template T
+ * @param {string} label
+ * @param {() => T} op
+ * @returns {T}
+ */
+function guardRange(label, op) {
+  try {
+    return op()
+  } catch (err) {
+    throw new RangeError(
+      `daymath: ${label} could not produce a valid date (${/** @type {Error} */ (err).message})`,
+      { cause: err },
+    )
+  }
+}
+
+/**
+ * Shared body for every add/sub function. Each caller passes its own name, so
+ * the message never reports a function the caller did not call.
+ * @param {DayInput} date
+ * @param {{ days?: number, months?: number, years?: number }} delta
+ * @param {string} label
+ * @returns {string}
+ */
+function addDuration(date, delta, label) {
+  const d = toPlainDate(date)
+  return guardRange(label, () => toDayString(d.add(delta)))
+}
+
 /** @param {unknown} dates */
 function assertNonEmptyDates(dates) {
   if (!Array.isArray(dates) || dates.length === 0) {
@@ -90,11 +126,11 @@ function assertNonEmptyDates(dates) {
  * @returns {0|1|2|3|4|5|6}
  */
 function weekStartsOnFrom(options) {
-  const w = options?.weekStartsOn ?? 0
-  if (!Number.isInteger(w) || w < 0 || w > 6) {
-    throw new RangeError('daymath: weekStartsOn must be an integer 0…6 (0=Sun)')
+  const w = options?.weekStartsOn ?? 7
+  if (!Number.isInteger(w) || w < 0 || w > 7) {
+    throw new RangeError('daymath: weekStartsOn must be an integer 0…7 (7 or 0 = Sunday)')
   }
-  return /** @type {0|1|2|3|4|5|6} */ (w)
+  return /** @type {0|1|2|3|4|5|6|7} */ (w)
 }
 
 /**
@@ -116,6 +152,8 @@ function toInterval(interval) {
  * True if value is a valid daymath day (ISO day string or PlainDate).
  * Invalid strings → false. `Date` → throws (not a quiet false — swap trap).
  * @param {unknown} value
+ * @returns {boolean}
+ * @throws {TypeError} If `value` is a `Date`
  */
 export function isValid(value) {
   if (value instanceof Date) {
@@ -164,7 +202,7 @@ export function format(date, pattern = 'yyyy-MM-dd') {
  */
 export function addDays(date, amount) {
   assertFiniteNumber(amount, 'amount')
-  return toDayString(toPlainDate(date).add({ days: amount }))
+  return addDuration(date, { days: amount }, 'addDays')
 }
 
 /**
@@ -174,7 +212,7 @@ export function addDays(date, amount) {
  */
 export function subDays(date, amount) {
   assertFiniteNumber(amount, 'amount')
-  return addDays(date, -amount)
+  return addDuration(date, { days: -amount }, 'subDays')
 }
 
 /**
@@ -184,7 +222,9 @@ export function subDays(date, amount) {
  */
 export function addWeeks(date, amount) {
   assertFiniteNumber(amount, 'amount')
-  return addDays(date, amount * 7)
+  const days = amount * 7 // re-check: 7x a finite amount can still reach Infinity
+  assertFiniteNumber(days, 'amount')
+  return addDuration(date, { days }, 'addWeeks')
 }
 
 /**
@@ -194,7 +234,9 @@ export function addWeeks(date, amount) {
  */
 export function subWeeks(date, amount) {
   assertFiniteNumber(amount, 'amount')
-  return addWeeks(date, -amount)
+  const days = -amount * 7
+  assertFiniteNumber(days, 'amount')
+  return addDuration(date, { days }, 'subWeeks')
 }
 
 /**
@@ -205,7 +247,7 @@ export function subWeeks(date, amount) {
  */
 export function addMonths(date, amount) {
   assertFiniteNumber(amount, 'amount')
-  return toDayString(toPlainDate(date).add({ months: amount }))
+  return addDuration(date, { months: amount }, 'addMonths')
 }
 
 /**
@@ -215,7 +257,7 @@ export function addMonths(date, amount) {
  */
 export function subMonths(date, amount) {
   assertFiniteNumber(amount, 'amount')
-  return addMonths(date, -amount)
+  return addDuration(date, { months: -amount }, 'subMonths')
 }
 
 /**
@@ -225,7 +267,7 @@ export function subMonths(date, amount) {
  */
 export function addYears(date, amount) {
   assertFiniteNumber(amount, 'amount')
-  return toDayString(toPlainDate(date).add({ years: amount }))
+  return addDuration(date, { years: amount }, 'addYears')
 }
 
 /**
@@ -235,7 +277,7 @@ export function addYears(date, amount) {
  */
 export function subYears(date, amount) {
   assertFiniteNumber(amount, 'amount')
-  return addYears(date, -amount)
+  return addDuration(date, { years: -amount }, 'subYears')
 }
 
 /**
@@ -245,7 +287,9 @@ export function subYears(date, amount) {
  */
 export function addQuarters(date, amount) {
   assertFiniteNumber(amount, 'amount')
-  return addMonths(date, amount * 3)
+  const months = amount * 3
+  assertFiniteNumber(months, 'amount')
+  return addDuration(date, { months }, 'addQuarters')
 }
 
 /**
@@ -255,7 +299,9 @@ export function addQuarters(date, amount) {
  */
 export function subQuarters(date, amount) {
   assertFiniteNumber(amount, 'amount')
-  return addQuarters(date, -amount)
+  const months = -amount * 3
+  assertFiniteNumber(months, 'amount')
+  return addDuration(date, { months }, 'subQuarters')
 }
 
 // ─── getters / setters (date-fns / Date month & weekday indexing) ─
@@ -266,12 +312,13 @@ export function getYear(date) {
 }
 
 /**
- * Month index like Date/date-fns: 0 = January … 11 = December.
+ * Month number, ISO 8601: 1 = January … 12 = December. Matches the `MM` field
+ * of the input string, and Temporal. **Not** date-fns, which is 0-based.
  * @param {DayInput} date
  * @returns {number}
  */
 export function getMonth(date) {
-  return toPlainDate(date).month - 1
+  return toPlainDate(date).month
 }
 
 /** Day of month 1…31. @param {DayInput} date @returns {number} */
@@ -280,12 +327,14 @@ export function getDate(date) {
 }
 
 /**
- * Weekday like Date/date-fns: 0 = Sunday … 6 = Saturday.
+ * Weekday, ISO 8601: 1 = Monday … 7 = Sunday. Matches Temporal and
+ * `Intl.Locale#weekInfo.firstDay`. **Not** date-fns, where Sunday is 0.
+ * Only Sunday differs; Monday–Saturday are 1–6 in both.
  * @param {DayInput} date
  * @returns {number}
  */
 export function getDay(date) {
-  return isoToJsWeekday(toPlainDate(date).dayOfWeek)
+  return toPlainDate(date).dayOfWeek
 }
 
 /** @param {DayInput} date @returns {number} */
@@ -315,71 +364,81 @@ export function isLeapYear(date) {
  */
 export function setYear(date, year) {
   assertFiniteNumber(year, 'year')
-  return toDayString(toPlainDate(date).with({ year }))
+  const d = toPlainDate(date)
+  return guardRange('setYear', () => toDayString(d.with({ year })))
 }
 
 /**
  * @param {DayInput} date
- * @param {number} month 0 = January … 11 = December (date-fns)
+ * @param {number} month 1 = January … 12 = December (ISO 8601)
  * @returns {string}
  */
 export function setMonth(date, month) {
   assertFiniteNumber(month, 'month')
-  if (month < 0 || month > 11) {
-    throw new RangeError('daymath: month must be 0…11 (0=January)')
+  if (month < 1 || month > 12) {
+    throw new RangeError('daymath: month must be 1…12 (1=January)')
   }
-  return toDayString(toPlainDate(date).with({ month: month + 1 }))
+  const d = toPlainDate(date)
+  return guardRange('setMonth', () => toDayString(d.with({ month })))
 }
 
 /**
  * @param {DayInput} date
- * @param {number} dayOfMonth
+ * @param {number} dayOfMonth 1…31; a day past the month end constrains to the
+ * last day of that month (no roll-over into the next month, unlike date-fns)
  * @returns {string}
  */
 export function setDate(date, dayOfMonth) {
   assertFiniteNumber(dayOfMonth, 'day')
-  return toDayString(toPlainDate(date).with({ day: dayOfMonth }))
+  const d = toPlainDate(date)
+  return guardRange('setDate', () => toDayString(d.with({ day: dayOfMonth })))
 }
 
 // ─── start / end of unit ───────────────────────────────────────────
 
+// The first/last day of a unit can fall outside the PlainDate range even when
+// the input is inside it — startOfMonth('-271821-04-19') wants April 1st, which
+// is below the minimum. Throwing is right; guardRange keeps the message ours.
+
 /** @param {DayInput} date @returns {string} */
 export function startOfMonth(date) {
   const d = toPlainDate(date)
-  return toDayString(d.with({ day: 1 }))
+  return guardRange('startOfMonth', () => toDayString(d.with({ day: 1 })))
 }
 
 /** @param {DayInput} date @returns {string} */
 export function endOfMonth(date) {
   const d = toPlainDate(date)
-  return toDayString(d.with({ day: d.daysInMonth }))
+  return guardRange('endOfMonth', () => toDayString(d.with({ day: d.daysInMonth })))
 }
 
 /** @param {DayInput} date @returns {string} */
 export function startOfYear(date) {
   const d = toPlainDate(date)
-  return toDayString(d.with({ month: 1, day: 1 }))
+  return guardRange('startOfYear', () => toDayString(d.with({ month: 1, day: 1 })))
 }
 
 /** @param {DayInput} date @returns {string} */
 export function endOfYear(date) {
   const d = toPlainDate(date)
-  return toDayString(d.with({ month: 12, day: 31 }))
+  return guardRange('endOfYear', () => toDayString(d.with({ month: 12, day: 31 })))
 }
 
 /** @param {DayInput} date @returns {string} */
 export function startOfQuarter(date) {
   const d = toPlainDate(date)
   const month = (getQuarter(d) - 1) * 3 + 1
-  return toDayString(d.with({ month, day: 1 }))
+  return guardRange('startOfQuarter', () => toDayString(d.with({ month, day: 1 })))
 }
 
 /** @param {DayInput} date @returns {string} */
 export function endOfQuarter(date) {
   const d = toPlainDate(date)
   const month = getQuarter(d) * 3
-  const mid = d.with({ month, day: 1 })
-  return toDayString(mid.with({ day: mid.daysInMonth }))
+  return guardRange('endOfQuarter', () => {
+    const mid = d.with({ month, day: 1 })
+    return toDayString(mid.with({ day: mid.daysInMonth }))
+  })
 }
 
 /**
@@ -389,10 +448,20 @@ export function endOfQuarter(date) {
  */
 export function startOfWeek(date, options) {
   const d = toPlainDate(date)
+  const diff = daysIntoWeek(d, options)
+  return guardRange('startOfWeek', () => toDayString(d.subtract({ days: diff })))
+}
+
+/**
+ * How far the day sits past the start of its week.
+ * @param {Temporal.PlainDate} d
+ * @param {WeekOptions} [options]
+ * @returns {number}
+ */
+function daysIntoWeek(d, options) {
   const weekStartsOn = weekStartsOnFrom(options)
-  const day = isoToJsWeekday(d.dayOfWeek)
-  const diff = (day - weekStartsOn + 7) % 7
-  return toDayString(d.subtract({ days: diff }))
+  // mod 7 makes weekStartsOn 0 and 7 identical, so both spellings of Sunday work
+  return (d.dayOfWeek - weekStartsOn + 7) % 7
 }
 
 /**
@@ -401,7 +470,12 @@ export function startOfWeek(date, options) {
  * @returns {string}
  */
 export function endOfWeek(date, options) {
-  return addDays(startOfWeek(date, options), 6)
+  const d = toPlainDate(date)
+  const diff = daysIntoWeek(d, options)
+  // one guard for the whole walk, so a failure at either end says endOfWeek
+  return guardRange('endOfWeek', () =>
+    toDayString(d.subtract({ days: diff }).add({ days: 6 })),
+  )
 }
 
 // ─── differences ───────────────────────────────────────────────────
@@ -425,11 +499,20 @@ export function differenceInDays(dateLeft, dateRight) {
  * @returns {number}
  */
 export function differenceInWeeks(dateLeft, dateRight) {
-  return Math.trunc(differenceInDays(dateLeft, dateRight) / 7)
+  // `|| 0` normalises -0: Math.trunc keeps the sign of a negative gap shorter
+  // than a week, so a 1..6 day backwards difference returned -0
+  return Math.trunc(differenceInDays(dateLeft, dateRight) / 7) || 0
 }
 
 /**
- * Full months (signed), Temporal since with largestUnit month.
+ * Full months (signed). A month counts as full when `addMonths` would carry the
+ * earlier date to the later one, so the end of a short month counts: 31 January
+ * to 28 February is one month, because `addMonths` clamps 31 February to the
+ * 28th. That keeps `differenceInMonths(addMonths(d, n), d) === n`.
+ *
+ * Temporal's `since` is not used here. It has no overflow option, so it counts
+ * 28 days rather than one month for that pair, and the round trip breaks in
+ * 21,934 of 1,761,936 cases. `add` clamps, so the measurement has to match.
  * @param {DayInput} dateLeft
  * @param {DayInput} dateRight
  * @returns {number}
@@ -437,8 +520,18 @@ export function differenceInWeeks(dateLeft, dateRight) {
 export function differenceInMonths(dateLeft, dateRight) {
   const left = toPlainDate(dateLeft, 'dateLeft')
   const right = toPlainDate(dateRight, 'dateRight')
-  const dur = left.since(right, { largestUnit: 'month' })
-  return dur.months
+  const sign = Temporal.PlainDate.compare(left, right)
+  if (sign === 0) return 0
+  const diff = Math.abs(differenceInCalendarMonths(left, right))
+  if (diff < 1) return 0
+  const [earlier, later] = sign > 0 ? [right, left] : [left, right]
+  // Where `earlier` lands after `diff` months: same year-month as `later` by
+  // construction, on `earlier`'s day clamped to that month's length. Compared
+  // as day numbers rather than built as a date, because the landing can sit
+  // past the maximum PlainDate even when both operands are inside the range.
+  const landingDay = Math.min(earlier.day, later.daysInMonth)
+  const isLastMonthNotFull = landingDay > later.day
+  return sign * (diff - +isLastMonthNotFull) || 0
 }
 
 /**
@@ -454,7 +547,11 @@ export function differenceInCalendarMonths(dateLeft, dateRight) {
 }
 
 /**
- * Full years (signed).
+ * Full years (signed). Same rule as `differenceInMonths`: a year counts as full
+ * when `addYears` would carry the earlier date to the later one, so 29 February
+ * to 28 February of a common year is one year, because `addYears` clamps.
+ * That keeps `differenceInYears(addYears(d, n), d) === n`, and keeps this
+ * function agreeing with `trunc(differenceInMonths(a, b) / 12)`.
  * @param {DayInput} dateLeft
  * @param {DayInput} dateRight
  * @returns {number}
@@ -462,7 +559,22 @@ export function differenceInCalendarMonths(dateLeft, dateRight) {
 export function differenceInYears(dateLeft, dateRight) {
   const left = toPlainDate(dateLeft, 'dateLeft')
   const right = toPlainDate(dateRight, 'dateRight')
-  return left.since(right, { largestUnit: 'year' }).years
+  const sign = Temporal.PlainDate.compare(left, right)
+  if (sign === 0) return 0
+  const diff = Math.abs(left.year - right.year)
+  if (diff < 1) return 0
+  const [earlier, later] = sign > 0 ? [right, left] : [left, right]
+  // Where `earlier` lands after `diff` years: same year as `later`, same month,
+  // and the same day except that 29 February clamps to the 28th in a common
+  // year, which is the only day-of-month that changes length year to year.
+  // Compared field by field rather than built as a date, because the landing
+  // can sit past the maximum PlainDate even with both operands inside the range.
+  const landingDay =
+    earlier.month === 2 && earlier.day === 29 && !later.inLeapYear ? 28 : earlier.day
+  const isLastYearNotFull =
+    earlier.month > later.month ||
+    (earlier.month === later.month && landingDay > later.day)
+  return sign * (diff - +isLastYearNotFull) || 0
 }
 
 /**
@@ -482,7 +594,9 @@ export function differenceInCalendarYears(dateLeft, dateRight) {
  * @returns {number}
  */
 export function differenceInQuarters(dateLeft, dateRight) {
-  return Math.trunc(differenceInMonths(dateLeft, dateRight) / 3)
+  // `|| 0` normalises -0, same reason as differenceInWeeks: a backwards gap of
+  // one or two months truncates to -0
+  return Math.trunc(differenceInMonths(dateLeft, dateRight) / 3) || 0
 }
 
 /**
@@ -554,7 +668,14 @@ export const isSameDay = isEqual
  * @returns {boolean}
  */
 export function isSameWeek(dateLeft, dateRight, options) {
-  return isEqual(startOfWeek(dateLeft, options), startOfWeek(dateRight, options))
+  const left = toPlainDate(dateLeft, 'dateLeft')
+  const right = toPlainDate(dateRight, 'dateRight')
+  // own guard, so a week start below the minimum does not say startOfWeek
+  return guardRange('isSameWeek', () =>
+    left.subtract({ days: daysIntoWeek(left, options) }).equals(
+      right.subtract({ days: daysIntoWeek(right, options) }),
+    ),
+  )
 }
 
 /**
@@ -608,7 +729,8 @@ export function compareAsc(dateLeft, dateRight) {
  * @returns {-1 | 0 | 1}
  */
 export function compareDesc(dateLeft, dateRight) {
-  return /** @type {-1 | 0 | 1} */ (-compareAsc(dateLeft, dateRight))
+  // `|| 0` normalises -0 for equal days
+  return /** @type {-1 | 0 | 1} */ (-compareAsc(dateLeft, dateRight) || 0)
 }
 
 /**
@@ -641,7 +763,7 @@ export function max(dates) {
 
 /** @param {DayInput} date @returns {boolean} */
 export function isSunday(date) {
-  return getDay(date) === 0
+  return getDay(date) === 7
 }
 /** @param {DayInput} date @returns {boolean} */
 export function isMonday(date) {
@@ -670,7 +792,7 @@ export function isSaturday(date) {
 /** @param {DayInput} date @returns {boolean} */
 export function isWeekend(date) {
   const d = getDay(date)
-  return d === 0 || d === 6
+  return d === 6 || d === 7
 }
 
 /** @param {DayInput} date @returns {boolean} */
@@ -699,8 +821,11 @@ export function eachDayOfInterval(interval) {
   /** @type {string[]} */
   const out = []
   let cur = start
-  while (Temporal.PlainDate.compare(cur, end) <= 0) {
+  // break on the last day, never step past it — an add beyond the max
+  // PlainDate (+275760-09-13) throws
+  for (;;) {
     out.push(toDayString(cur))
+    if (Temporal.PlainDate.compare(cur, end) >= 0) break
     cur = cur.add({ days: 1 })
   }
   return out
@@ -718,10 +843,16 @@ export function eachMonthOfInterval(interval) {
   }
   /** @type {string[]} */
   const out = []
-  let cur = start.with({ day: 1 })
-  const last = end.with({ day: 1 })
-  while (Temporal.PlainDate.compare(cur, last) <= 0) {
+  // the 1st of start's month can sit below the minimum PlainDate
+  const [cur0, last] = guardRange('eachMonthOfInterval', () => [
+    start.with({ day: 1 }),
+    end.with({ day: 1 }),
+  ])
+  let cur = cur0
+  // same boundary rule as eachDayOfInterval
+  for (;;) {
     out.push(toDayString(cur))
+    if (Temporal.PlainDate.compare(cur, last) >= 0) break
     cur = cur.add({ months: 1 })
   }
   return out
@@ -740,10 +871,13 @@ export function eachYearOfInterval(interval) {
   /** @type {string[]} */
   const out = []
   let y = start.year
-  while (y <= end.year) {
-    out.push(toDayString(Temporal.PlainDate.from({ year: y, month: 1, day: 1 })))
-    y += 1
-  }
+  // Jan 1 of start's year can sit below the minimum PlainDate
+  guardRange('eachYearOfInterval', () => {
+    while (y <= end.year) {
+      out.push(toDayString(Temporal.PlainDate.from({ year: y, month: 1, day: 1 })))
+      y += 1
+    }
+  })
   return out
 }
 
@@ -786,7 +920,7 @@ export function clamp(date, interval) {
  * Whether two inclusive intervals overlap.
  * @param {Interval} intervalLeft
  * @param {Interval} intervalRight
- * @param {{ inclusive?: boolean }} [options] default inclusive true (date-fns default false uses half-open; we default true for plain days)
+ * @param {{ inclusive?: boolean }} [options] `inclusive` defaults to false, like date-fns: intervals that only touch at an endpoint do not overlap
  * @returns {boolean}
  */
 export function areIntervalsOverlapping(intervalLeft, intervalRight, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "daymath",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Calendar date math (ISO 8601 day / PlainDate). date-fns-shaped. No time zones.",
   "type": "module",
   "main": "./index.js",
@@ -18,17 +18,21 @@
   ],
   "scripts": {
     "test": "node --test test.js",
-    "test:coverage": "node --test --experimental-test-coverage --test-coverage-include=index.js test.js",
-    "prepublishOnly": "npm run test:coverage"
+    "test:coverage": "c8 --include=index.js --check-coverage --lines 100 --functions 100 --branches 100 --reporter=text --reporter=lcov node --test test.js",
+    "test:differential": "node scripts/differential.mjs",
+    "test:differential:quick": "node scripts/differential.mjs 2020 2030",
+    "prepublishOnly": "npm run test:coverage",
+    "publish:github": "node scripts/publish-github-packages.mjs"
   },
-
   "keywords": [
     "date",
     "calendar",
     "plain-date",
     "temporal",
     "date-fns",
-    "YYYY-MM-DD"
+    "YYYY-MM-DD",
+    "ISO-8601",
+    "PlainDate"
   ],
   "author": "leemr",
   "license": "MIT",
@@ -39,11 +43,16 @@
   "bugs": {
     "url": "https://github.com/leemr/daymath/issues"
   },
-  "homepage": "https://github.com/leemr/daymath#readme",
+  "homepage": "https://leemr.github.io/daymath/",
+  "sideEffects": false,
   "dependencies": {
     "temporal-polyfill": "^1.0.3"
   },
   "engines": {
     "node": ">=18"
+  },
+  "devDependencies": {
+    "c8": "^12.0.0",
+    "date-fns": "4.4.0"
   }
 }