daymath 0.0.1 → 0.2.0

package/README.md

@@ -1,18 +1,95 @@
 # daymath
 
-Calendar date math (`YYYY-MM-DD` / plain dates). date-fns-shaped. No time zones.
+Calendar date math for **ISO 8601** `YYYY-MM-DD` strings. **date-fns-shaped** names. **Temporal.PlainDate** under the hood.
 
-**Status:** name reserved. API not shipped yet.
+No `Date`. No time zones. No silent “local now.”
 
 ```bash
 npm install daymath
 ```
 
-## Planned
+## Why
 
-- String-first date math (add/sub days, diffs, compare)
-- Temporal.PlainDate under the hood
-- No `Date`, no silent local-now surprises
+`Date` is a timestamp. Calendar work (“add one month”, “days between hire and start”) is not. This package only does plain calendar days.
+
+## Usage
+
+```js
+import {
+  addDays,
+  addMonths,
+  differenceInDays,
+  isBefore,
+  isSameDay,
+  startOfMonth,
+  eachDayOfInterval,
+} from 'daymath'
+
+addDays('2026-08-06', 1)                    // '2026-08-07'
+addMonths('2026-01-31', 1)                  // '2026-02-28' (constrain)
+differenceInDays('2026-08-06', '2026-08-01') // 5
+isBefore('2026-08-05', '2026-08-06')         // true
+isSameDay('2026-08-06', '2026-08-06')        // true (alias of isEqual)
+startOfMonth('2026-08-06')                  // '2026-08-01'
+eachDayOfInterval({
+  start: '2026-08-05',
+  end: '2026-08-07',
+}) // ['2026-08-05', '2026-08-06', '2026-08-07']
+```
+
+**Inputs:** ISO 8601 `YYYY-MM-DD` or `Temporal.PlainDate`.  
+**Outputs:** always `YYYY-MM-DD` string (for math helpers).
+
+`Date` throws. Time-bearing strings throw. Sloppy forms like `2026-8-6` throw.
+
+## date-fns parity notes
+
+| Topic | daymath |
+|-------|---------|
+| Value type | `YYYY-MM-DD` string (not `Date`) |
+| `isSameDay` | Alias of `isEqual` (same calendar day) |
+| `getMonth` / `setMonth` | **0–11** like Date/date-fns (0 = January) |
+| `getDay` | **0–6** like Date/date-fns (0 = Sunday) |
+| `weekStartsOn` | `0` = Sunday … `6` = Saturday (default `0`) |
+| Intervals | `{ start, end }` inclusive for `each*` / `isWithin` / `clamp` |
+| `areIntervalsOverlapping` | Default `{ inclusive: false }` (date-fns); pass `true` for closed |
+
+## API (0.2)
+
+### Parse / format
+`parse` · `format` · `isValid`
+
+### Add / sub
+`addDays` / `subDays` · `addWeeks` / `subWeeks` · `addMonths` / `subMonths` · `addYears` / `subYears` · `addQuarters` / `subQuarters`
+
+### Get / set
+`getYear` · `getMonth` · `getDate` · `getDay` · `getDayOfYear` · `getDaysInMonth` · `getQuarter` · `isLeapYear`  
+`setYear` · `setMonth` · `setDate`
+
+### Start / end
+`startOfMonth` / `endOfMonth` · `startOfYear` / `endOfYear` · `startOfQuarter` / `endOfQuarter` · `startOfWeek` / `endOfWeek`
+
+### Differences
+`differenceInDays` · `differenceInWeeks` · `differenceInMonths` · `differenceInCalendarMonths` · `differenceInYears` · `differenceInCalendarYears` · `differenceInQuarters` · `differenceInCalendarQuarters`
+
+### Compare
+`isBefore` · `isAfter` · `isEqual` · `isSameDay` · `isSameWeek` · `isSameMonth` · `isSameYear` · `isSameQuarter` · `compareAsc` · `compareDesc` · `min` · `max`
+
+### Weekday / month edges
+`isSunday`…`isSaturday` · `isWeekend` · `isFirstDayOfMonth` · `isLastDayOfMonth`
+
+### Intervals
+`eachDayOfInterval` · `eachMonthOfInterval` · `eachYearOfInterval` · `isWithinInterval` · `clamp` · `areIntervalsOverlapping`
+
+Amounts must be finite integers.
+
+## Temporal
+
+Uses global `Temporal` when present; otherwise [`temporal-polyfill`](https://www.npmjs.com/package/temporal-polyfill).
+
+## Types
+
+Ships `index.d.ts` (no TypeScript compile step). Source is plain JS.
 
 ## License
 

package/index.d.ts

@@ -0,0 +1,125 @@
+import type { Temporal } from 'temporal-polyfill'
+
+/**
+ * Calendar day input: ISO 8601 `YYYY-MM-DD` string, or a Temporal.PlainDate.
+ * `Date` is rejected at runtime.
+ */
+export type DayInput = string | Temporal.PlainDate
+
+/** Inclusive calendar-day interval (date-fns shape). */
+export type Interval = {
+  start: DayInput
+  end: DayInput
+}
+
+/**
+ * Week options. `weekStartsOn`: 0 = Sunday … 6 = Saturday (date-fns default 0).
+ */
+export type WeekOptions = {
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6
+}
+
+export function isValid(value: unknown): boolean
+
+/** Validate / normalize to ISO 8601 `YYYY-MM-DD`. */
+export function parse(date: DayInput): string
+
+/** Format as `YYYY-MM-DD` (only pattern supported). */
+export function format(date: DayInput, pattern?: 'yyyy-MM-dd' | 'YYYY-MM-DD'): string
+
+export function addDays(date: DayInput, amount: number): string
+export function subDays(date: DayInput, amount: number): string
+export function addWeeks(date: DayInput, amount: number): string
+export function subWeeks(date: DayInput, amount: number): string
+export function addMonths(date: DayInput, amount: number): string
+export function subMonths(date: DayInput, amount: number): string
+export function addYears(date: DayInput, amount: number): string
+export function subYears(date: DayInput, amount: number): string
+export function addQuarters(date: DayInput, amount: number): string
+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. */
+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. */
+export function getDay(date: DayInput): number
+export function getDayOfYear(date: DayInput): number
+export function getDaysInMonth(date: DayInput): number
+/** Quarter 1…4. */
+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). */
+export function setMonth(date: DayInput, month: number): string
+export function setDate(date: DayInput, dayOfMonth: number): string
+
+export function startOfMonth(date: DayInput): string
+export function endOfMonth(date: DayInput): string
+export function startOfYear(date: DayInput): string
+export function endOfYear(date: DayInput): string
+export function startOfQuarter(date: DayInput): string
+export function endOfQuarter(date: DayInput): string
+export function startOfWeek(date: DayInput, options?: WeekOptions): string
+export function endOfWeek(date: DayInput, options?: WeekOptions): string
+
+/** Full days: `dateLeft − dateRight` (date-fns argument order). */
+export function differenceInDays(dateLeft: DayInput, dateRight: DayInput): number
+export function differenceInWeeks(dateLeft: DayInput, dateRight: DayInput): number
+export function differenceInMonths(dateLeft: DayInput, dateRight: DayInput): number
+export function differenceInCalendarMonths(dateLeft: DayInput, dateRight: DayInput): number
+export function differenceInYears(dateLeft: DayInput, dateRight: DayInput): number
+export function differenceInCalendarYears(dateLeft: DayInput, dateRight: DayInput): number
+export function differenceInQuarters(dateLeft: DayInput, dateRight: DayInput): number
+export function differenceInCalendarQuarters(dateLeft: DayInput, dateRight: DayInput): number
+
+export function isBefore(date: DayInput, dateToCompare: DayInput): boolean
+export function isAfter(date: DayInput, dateToCompare: DayInput): boolean
+/** Same calendar day. */
+export function isEqual(dateLeft: DayInput, dateRight: DayInput): boolean
+/** Alias of `isEqual` (date-fns name). */
+export const isSameDay: typeof isEqual
+
+export function isSameWeek(
+  dateLeft: DayInput,
+  dateRight: DayInput,
+  options?: WeekOptions,
+): boolean
+export function isSameMonth(dateLeft: DayInput, dateRight: DayInput): boolean
+export function isSameYear(dateLeft: DayInput, dateRight: DayInput): boolean
+export function isSameQuarter(dateLeft: DayInput, dateRight: DayInput): boolean
+
+export function compareAsc(dateLeft: DayInput, dateRight: DayInput): -1 | 0 | 1
+export function compareDesc(dateLeft: DayInput, dateRight: DayInput): -1 | 0 | 1
+
+export function min(dates: DayInput[]): string
+export function max(dates: DayInput[]): string
+
+export function isSunday(date: DayInput): boolean
+export function isMonday(date: DayInput): boolean
+export function isTuesday(date: DayInput): boolean
+export function isWednesday(date: DayInput): boolean
+export function isThursday(date: DayInput): boolean
+export function isFriday(date: DayInput): boolean
+export function isSaturday(date: DayInput): boolean
+export function isWeekend(date: DayInput): boolean
+export function isFirstDayOfMonth(date: DayInput): boolean
+export function isLastDayOfMonth(date: DayInput): boolean
+
+export function eachDayOfInterval(interval: Interval): string[]
+export function eachMonthOfInterval(interval: Interval): string[]
+export function eachYearOfInterval(interval: Interval): string[]
+export function isWithinInterval(date: DayInput, interval: Interval): boolean
+export function clamp(date: DayInput, interval: Interval): string
+/**
+ * date-fns default: `inclusive: false` (touching endpoints only is not overlap).
+ * Pass `{ inclusive: true }` for closed intervals.
+ */
+export function areIntervalsOverlapping(
+  intervalLeft: Interval,
+  intervalRight: Interval,
+  options?: { inclusive?: boolean },
+): boolean

package/index.js

@@ -1,4 +1,797 @@
-/** daymath — reserved. Real API coming. */
-export function addDays(date, days) {
-  throw new Error('daymath: not implemented yet (name reserved).')
+/** daymath — calendar date math (YYYY-MM-DD). date-fns-shaped. No Date / time zones. */
+import { Temporal as TemporalPolyfill } from 'temporal-polyfill'
+
+const Temporal = globalThis.Temporal ?? TemporalPolyfill
+
+/** @typedef {string | Temporal.PlainDate} DayInput */
+/**
+ * @typedef {object} Interval
+ * @property {DayInput} start
+ * @property {DayInput} end
+ */
+/**
+ * @typedef {object} WeekOptions
+ * @property {0|1|2|3|4|5|6} [weekStartsOn] 0=Sun … 6=Sat (date-fns default 0)
+ */
+
+// ─── core conversion ───────────────────────────────────────────────
+
+/**
+ * Reject Date and non-calendar values. Accept YYYY-MM-DD string or PlainDate.
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {Temporal.PlainDate}
+ */
+function toPlainDate(value, label = 'date') {
+  if (value instanceof Date) {
+    throw new TypeError(
+      `daymath: Date is not allowed for ${label} (pass YYYY-MM-DD string)`,
+    )
+  }
+  if (typeof value === 'string') {
+    // Strict ISO 8601 calendar date: YYYY-MM-DD only.
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+      throw new RangeError(
+        `daymath: ${label} must be YYYY-MM-DD (got ${JSON.stringify(value)})`,
+      )
+    }
+    try {
+      return Temporal.PlainDate.from(value)
+    } catch (err) {
+      throw new RangeError(`daymath: invalid ${label} ${JSON.stringify(value)}`, {
+        cause: err,
+      })
+    }
+  }
+  if (value instanceof Temporal.PlainDate) {
+    return value
+  }
+  throw new TypeError(
+    `daymath: ${label} must be YYYY-MM-DD string or Temporal.PlainDate`,
+  )
+}
+
+/** @param {Temporal.PlainDate} plain @returns {string} */
+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)) {
+    throw new TypeError(`daymath: ${label} must be a finite number`)
+  }
+  if (!Number.isInteger(n)) {
+    throw new RangeError(`daymath: ${label} must be an integer`)
+  }
+}
+
+/** @param {unknown} dates */
+function assertNonEmptyDates(dates) {
+  if (!Array.isArray(dates) || dates.length === 0) {
+    throw new RangeError('daymath: expected a non-empty array of dates')
+  }
+}
+
+/**
+ * @param {WeekOptions} [options]
+ * @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)')
+  }
+  return /** @type {0|1|2|3|4|5|6} */ (w)
+}
+
+/**
+ * @param {unknown} interval
+ * @returns {{ start: Temporal.PlainDate, end: Temporal.PlainDate }}
+ */
+function toInterval(interval) {
+  if (interval == null || typeof interval !== 'object') {
+    throw new TypeError('daymath: interval must be { start, end }')
+  }
+  const start = toPlainDate(/** @type {Interval} */ (interval).start, 'start')
+  const end = toPlainDate(/** @type {Interval} */ (interval).end, 'end')
+  return { start, end }
+}
+
+// ─── parse / format / valid ────────────────────────────────────────
+
+/** @param {unknown} value */
+export function isValid(value) {
+  try {
+    toPlainDate(value)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Validate / normalize a calendar day string (ISO 8601 YYYY-MM-DD).
+ * @param {DayInput} date
+ * @returns {string}
+ */
+export function parse(date) {
+  return toDayString(toPlainDate(date))
+}
+
+/**
+ * Format as YYYY-MM-DD (only supported pattern).
+ * @param {DayInput} date
+ * @param {string} [pattern='yyyy-MM-dd']
+ * @returns {string}
+ */
+export function format(date, pattern = 'yyyy-MM-dd') {
+  if (pattern !== 'yyyy-MM-dd' && pattern !== 'YYYY-MM-DD') {
+    throw new RangeError(
+      `daymath: only "yyyy-MM-dd" format is supported (got ${JSON.stringify(pattern)})`,
+    )
+  }
+  return toDayString(toPlainDate(date))
+}
+
+// ─── add / sub ─────────────────────────────────────────────────────
+
+/**
+ * @param {DayInput} date
+ * @param {number} amount
+ * @returns {string}
+ */
+export function addDays(date, amount) {
+  assertFiniteNumber(amount, 'amount')
+  return toDayString(toPlainDate(date).add({ days: amount }))
+}
+
+/**
+ * @param {DayInput} date
+ * @param {number} amount
+ * @returns {string}
+ */
+export function subDays(date, amount) {
+  assertFiniteNumber(amount, 'amount')
+  return addDays(date, -amount)
+}
+
+/**
+ * @param {DayInput} date
+ * @param {number} amount
+ * @returns {string}
+ */
+export function addWeeks(date, amount) {
+  assertFiniteNumber(amount, 'amount')
+  return addDays(date, amount * 7)
+}
+
+/**
+ * @param {DayInput} date
+ * @param {number} amount
+ * @returns {string}
+ */
+export function subWeeks(date, amount) {
+  assertFiniteNumber(amount, 'amount')
+  return addWeeks(date, -amount)
+}
+
+/**
+ * Calendar months (overflow constrain — Jan 31 + 1 month → Feb 28/29).
+ * @param {DayInput} date
+ * @param {number} amount
+ * @returns {string}
+ */
+export function addMonths(date, amount) {
+  assertFiniteNumber(amount, 'amount')
+  return toDayString(toPlainDate(date).add({ months: amount }))
+}
+
+/**
+ * @param {DayInput} date
+ * @param {number} amount
+ * @returns {string}
+ */
+export function subMonths(date, amount) {
+  assertFiniteNumber(amount, 'amount')
+  return addMonths(date, -amount)
+}
+
+/**
+ * @param {DayInput} date
+ * @param {number} amount
+ * @returns {string}
+ */
+export function addYears(date, amount) {
+  assertFiniteNumber(amount, 'amount')
+  return toDayString(toPlainDate(date).add({ years: amount }))
+}
+
+/**
+ * @param {DayInput} date
+ * @param {number} amount
+ * @returns {string}
+ */
+export function subYears(date, amount) {
+  assertFiniteNumber(amount, 'amount')
+  return addYears(date, -amount)
+}
+
+/**
+ * @param {DayInput} date
+ * @param {number} amount
+ * @returns {string}
+ */
+export function addQuarters(date, amount) {
+  assertFiniteNumber(amount, 'amount')
+  return addMonths(date, amount * 3)
+}
+
+/**
+ * @param {DayInput} date
+ * @param {number} amount
+ * @returns {string}
+ */
+export function subQuarters(date, amount) {
+  assertFiniteNumber(amount, 'amount')
+  return addQuarters(date, -amount)
+}
+
+// ─── getters / setters (date-fns / Date month & weekday indexing) ─
+
+/** @param {DayInput} date @returns {number} */
+export function getYear(date) {
+  return toPlainDate(date).year
+}
+
+/**
+ * Month index like Date/date-fns: 0 = January … 11 = December.
+ * @param {DayInput} date
+ * @returns {number}
+ */
+export function getMonth(date) {
+  return toPlainDate(date).month - 1
+}
+
+/** Day of month 1…31. @param {DayInput} date @returns {number} */
+export function getDate(date) {
+  return toPlainDate(date).day
+}
+
+/**
+ * Weekday like Date/date-fns: 0 = Sunday … 6 = Saturday.
+ * @param {DayInput} date
+ * @returns {number}
+ */
+export function getDay(date) {
+  return isoToJsWeekday(toPlainDate(date).dayOfWeek)
+}
+
+/** @param {DayInput} date @returns {number} */
+export function getDayOfYear(date) {
+  return toPlainDate(date).dayOfYear
+}
+
+/** @param {DayInput} date @returns {number} */
+export function getDaysInMonth(date) {
+  return toPlainDate(date).daysInMonth
+}
+
+/** Quarter 1…4. @param {DayInput} date @returns {number} */
+export function getQuarter(date) {
+  return Math.ceil(toPlainDate(date).month / 3)
+}
+
+/** @param {DayInput} date @returns {boolean} */
+export function isLeapYear(date) {
+  return toPlainDate(date).inLeapYear
+}
+
+/**
+ * @param {DayInput} date
+ * @param {number} year
+ * @returns {string}
+ */
+export function setYear(date, year) {
+  assertFiniteNumber(year, 'year')
+  return toDayString(toPlainDate(date).with({ year }))
+}
+
+/**
+ * @param {DayInput} date
+ * @param {number} month 0 = January … 11 = December (date-fns)
+ * @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)')
+  }
+  return toDayString(toPlainDate(date).with({ month: month + 1 }))
+}
+
+/**
+ * @param {DayInput} date
+ * @param {number} dayOfMonth
+ * @returns {string}
+ */
+export function setDate(date, dayOfMonth) {
+  assertFiniteNumber(dayOfMonth, 'day')
+  return toDayString(toPlainDate(date).with({ day: dayOfMonth }))
+}
+
+// ─── start / end of unit ───────────────────────────────────────────
+
+/** @param {DayInput} date @returns {string} */
+export function startOfMonth(date) {
+  const d = toPlainDate(date)
+  return 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 }))
+}
+
+/** @param {DayInput} date @returns {string} */
+export function startOfYear(date) {
+  const d = toPlainDate(date)
+  return 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 }))
+}
+
+/** @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 }))
+}
+
+/** @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 }))
+}
+
+/**
+ * @param {DayInput} date
+ * @param {WeekOptions} [options]
+ * @returns {string}
+ */
+export function startOfWeek(date, options) {
+  const d = toPlainDate(date)
+  const weekStartsOn = weekStartsOnFrom(options)
+  const day = isoToJsWeekday(d.dayOfWeek)
+  const diff = (day - weekStartsOn + 7) % 7
+  return toDayString(d.subtract({ days: diff }))
+}
+
+/**
+ * @param {DayInput} date
+ * @param {WeekOptions} [options]
+ * @returns {string}
+ */
+export function endOfWeek(date, options) {
+  return addDays(startOfWeek(date, options), 6)
+}
+
+// ─── differences ───────────────────────────────────────────────────
+
+/**
+ * Full calendar days: dateLeft − dateRight (date-fns order).
+ * @param {DayInput} dateLeft
+ * @param {DayInput} dateRight
+ * @returns {number}
+ */
+export function differenceInDays(dateLeft, dateRight) {
+  const left = toPlainDate(dateLeft, 'dateLeft')
+  const right = toPlainDate(dateRight, 'dateRight')
+  return left.since(right, { largestUnit: 'day' }).days
+}
+
+/**
+ * Full weeks (trunc toward 0), like date-fns.
+ * @param {DayInput} dateLeft
+ * @param {DayInput} dateRight
+ * @returns {number}
+ */
+export function differenceInWeeks(dateLeft, dateRight) {
+  return Math.trunc(differenceInDays(dateLeft, dateRight) / 7)
+}
+
+/**
+ * Full months (signed), Temporal since with largestUnit month.
+ * @param {DayInput} dateLeft
+ * @param {DayInput} dateRight
+ * @returns {number}
+ */
+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
+}
+
+/**
+ * Calendar month index diff: (yL−yR)*12 + (mL−mR). Ignores day-of-month.
+ * @param {DayInput} dateLeft
+ * @param {DayInput} dateRight
+ * @returns {number}
+ */
+export function differenceInCalendarMonths(dateLeft, dateRight) {
+  const left = toPlainDate(dateLeft, 'dateLeft')
+  const right = toPlainDate(dateRight, 'dateRight')
+  return (left.year - right.year) * 12 + (left.month - right.month)
+}
+
+/**
+ * Full years (signed).
+ * @param {DayInput} dateLeft
+ * @param {DayInput} dateRight
+ * @returns {number}
+ */
+export function differenceInYears(dateLeft, dateRight) {
+  const left = toPlainDate(dateLeft, 'dateLeft')
+  const right = toPlainDate(dateRight, 'dateRight')
+  return left.since(right, { largestUnit: 'year' }).years
+}
+
+/**
+ * Calendar year number diff. Ignores month/day.
+ * @param {DayInput} dateLeft
+ * @param {DayInput} dateRight
+ * @returns {number}
+ */
+export function differenceInCalendarYears(dateLeft, dateRight) {
+  return getYear(dateLeft) - getYear(dateRight)
+}
+
+/**
+ * Full quarters (trunc toward 0 of calendar-month/3 style via months).
+ * @param {DayInput} dateLeft
+ * @param {DayInput} dateRight
+ * @returns {number}
+ */
+export function differenceInQuarters(dateLeft, dateRight) {
+  return Math.trunc(differenceInMonths(dateLeft, dateRight) / 3)
+}
+
+/**
+ * Calendar quarter index diff.
+ * @param {DayInput} dateLeft
+ * @param {DayInput} dateRight
+ * @returns {number}
+ */
+export function differenceInCalendarQuarters(dateLeft, dateRight) {
+  const left = toPlainDate(dateLeft, 'dateLeft')
+  const right = toPlainDate(dateRight, 'dateRight')
+  return (
+    (left.year - right.year) * 4 + (getQuarter(left) - getQuarter(right))
+  )
+}
+
+// ─── compare / equal ───────────────────────────────────────────────
+
+/**
+ * @param {DayInput} date
+ * @param {DayInput} dateToCompare
+ * @returns {boolean}
+ */
+export function isBefore(date, dateToCompare) {
+  return (
+    Temporal.PlainDate.compare(
+      toPlainDate(date),
+      toPlainDate(dateToCompare, 'dateToCompare'),
+    ) < 0
+  )
+}
+
+/**
+ * @param {DayInput} date
+ * @param {DayInput} dateToCompare
+ * @returns {boolean}
+ */
+export function isAfter(date, dateToCompare) {
+  return (
+    Temporal.PlainDate.compare(
+      toPlainDate(date),
+      toPlainDate(dateToCompare, 'dateToCompare'),
+    ) > 0
+  )
+}
+
+/**
+ * Same calendar day.
+ * @param {DayInput} dateLeft
+ * @param {DayInput} dateRight
+ * @returns {boolean}
+ */
+export function isEqual(dateLeft, dateRight) {
+  return (
+    Temporal.PlainDate.compare(
+      toPlainDate(dateLeft, 'dateLeft'),
+      toPlainDate(dateRight, 'dateRight'),
+    ) === 0
+  )
+}
+
+/** Alias of `isEqual` (date-fns name for same calendar day). */
+export const isSameDay = isEqual
+
+/**
+ * @param {DayInput} dateLeft
+ * @param {DayInput} dateRight
+ * @param {WeekOptions} [options]
+ * @returns {boolean}
+ */
+export function isSameWeek(dateLeft, dateRight, options) {
+  return isEqual(startOfWeek(dateLeft, options), startOfWeek(dateRight, options))
+}
+
+/**
+ * @param {DayInput} dateLeft
+ * @param {DayInput} dateRight
+ * @returns {boolean}
+ */
+export function isSameMonth(dateLeft, dateRight) {
+  const a = toPlainDate(dateLeft, 'dateLeft')
+  const b = toPlainDate(dateRight, 'dateRight')
+  return a.year === b.year && a.month === b.month
+}
+
+/**
+ * @param {DayInput} dateLeft
+ * @param {DayInput} dateRight
+ * @returns {boolean}
+ */
+export function isSameYear(dateLeft, dateRight) {
+  return getYear(dateLeft) === getYear(dateRight)
+}
+
+/**
+ * @param {DayInput} dateLeft
+ * @param {DayInput} dateRight
+ * @returns {boolean}
+ */
+export function isSameQuarter(dateLeft, dateRight) {
+  const a = toPlainDate(dateLeft, 'dateLeft')
+  const b = toPlainDate(dateRight, 'dateRight')
+  return a.year === b.year && getQuarter(a) === getQuarter(b)
+}
+
+/**
+ * @param {DayInput} dateLeft
+ * @param {DayInput} dateRight
+ * @returns {-1 | 0 | 1}
+ */
+export function compareAsc(dateLeft, dateRight) {
+  return /** @type {-1 | 0 | 1} */ (
+    Temporal.PlainDate.compare(
+      toPlainDate(dateLeft, 'dateLeft'),
+      toPlainDate(dateRight, 'dateRight'),
+    )
+  )
+}
+
+/**
+ * @param {DayInput} dateLeft
+ * @param {DayInput} dateRight
+ * @returns {-1 | 0 | 1}
+ */
+export function compareDesc(dateLeft, dateRight) {
+  return /** @type {-1 | 0 | 1} */ (-compareAsc(dateLeft, dateRight))
+}
+
+/**
+ * @param {DayInput[]} dates
+ * @returns {string}
+ */
+export function min(dates) {
+  assertNonEmptyDates(dates)
+  return toDayString(
+    dates
+      .map((d) => toPlainDate(d))
+      .reduce((a, b) => (Temporal.PlainDate.compare(a, b) <= 0 ? a : b)),
+  )
+}
+
+/**
+ * @param {DayInput[]} dates
+ * @returns {string}
+ */
+export function max(dates) {
+  assertNonEmptyDates(dates)
+  return toDayString(
+    dates
+      .map((d) => toPlainDate(d))
+      .reduce((a, b) => (Temporal.PlainDate.compare(a, b) >= 0 ? a : b)),
+  )
+}
+
+// ─── weekday predicates ────────────────────────────────────────────
+
+/** @param {DayInput} date @returns {boolean} */
+export function isSunday(date) {
+  return getDay(date) === 0
+}
+/** @param {DayInput} date @returns {boolean} */
+export function isMonday(date) {
+  return getDay(date) === 1
+}
+/** @param {DayInput} date @returns {boolean} */
+export function isTuesday(date) {
+  return getDay(date) === 2
+}
+/** @param {DayInput} date @returns {boolean} */
+export function isWednesday(date) {
+  return getDay(date) === 3
+}
+/** @param {DayInput} date @returns {boolean} */
+export function isThursday(date) {
+  return getDay(date) === 4
+}
+/** @param {DayInput} date @returns {boolean} */
+export function isFriday(date) {
+  return getDay(date) === 5
+}
+/** @param {DayInput} date @returns {boolean} */
+export function isSaturday(date) {
+  return getDay(date) === 6
+}
+/** @param {DayInput} date @returns {boolean} */
+export function isWeekend(date) {
+  const d = getDay(date)
+  return d === 0 || d === 6
+}
+
+/** @param {DayInput} date @returns {boolean} */
+export function isFirstDayOfMonth(date) {
+  return getDate(date) === 1
+}
+
+/** @param {DayInput} date @returns {boolean} */
+export function isLastDayOfMonth(date) {
+  const d = toPlainDate(date)
+  return d.day === d.daysInMonth
+}
+
+// ─── intervals ─────────────────────────────────────────────────────
+
+/**
+ * Inclusive day range. Throws if start > end.
+ * @param {Interval} interval
+ * @returns {string[]}
+ */
+export function eachDayOfInterval(interval) {
+  const { start, end } = toInterval(interval)
+  if (Temporal.PlainDate.compare(start, end) > 0) {
+    throw new RangeError('daymath: interval start must not be after end')
+  }
+  /** @type {string[]} */
+  const out = []
+  let cur = start
+  while (Temporal.PlainDate.compare(cur, end) <= 0) {
+    out.push(toDayString(cur))
+    cur = cur.add({ days: 1 })
+  }
+  return out
+}
+
+/**
+ * First day of each month from start’s month through end’s month (date-fns shape).
+ * @param {Interval} interval
+ * @returns {string[]}
+ */
+export function eachMonthOfInterval(interval) {
+  const { start, end } = toInterval(interval)
+  if (Temporal.PlainDate.compare(start, end) > 0) {
+    throw new RangeError('daymath: interval start must not be after end')
+  }
+  /** @type {string[]} */
+  const out = []
+  let cur = start.with({ day: 1 })
+  const last = end.with({ day: 1 })
+  while (Temporal.PlainDate.compare(cur, last) <= 0) {
+    out.push(toDayString(cur))
+    cur = cur.add({ months: 1 })
+  }
+  return out
+}
+
+/**
+ * Jan 1 of each year from start’s year through end’s year.
+ * @param {Interval} interval
+ * @returns {string[]}
+ */
+export function eachYearOfInterval(interval) {
+  const { start, end } = toInterval(interval)
+  if (Temporal.PlainDate.compare(start, end) > 0) {
+    throw new RangeError('daymath: interval start must not be after end')
+  }
+  /** @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
+  }
+  return out
+}
+
+/**
+ * Inclusive: start ≤ date ≤ end.
+ * @param {DayInput} date
+ * @param {Interval} interval
+ * @returns {boolean}
+ */
+export function isWithinInterval(date, interval) {
+  const d = toPlainDate(date)
+  const { start, end } = toInterval(interval)
+  if (Temporal.PlainDate.compare(start, end) > 0) {
+    throw new RangeError('daymath: interval start must not be after end')
+  }
+  return (
+    Temporal.PlainDate.compare(d, start) >= 0 &&
+    Temporal.PlainDate.compare(d, end) <= 0
+  )
+}
+
+/**
+ * Clamp date into [start, end].
+ * @param {DayInput} date
+ * @param {Interval} interval
+ * @returns {string}
+ */
+export function clamp(date, interval) {
+  const d = toPlainDate(date)
+  const { start, end } = toInterval(interval)
+  if (Temporal.PlainDate.compare(start, end) > 0) {
+    throw new RangeError('daymath: interval start must not be after end')
+  }
+  if (Temporal.PlainDate.compare(d, start) < 0) return toDayString(start)
+  if (Temporal.PlainDate.compare(d, end) > 0) return toDayString(end)
+  return toDayString(d)
+}
+
+/**
+ * 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)
+ * @returns {boolean}
+ */
+export function areIntervalsOverlapping(intervalLeft, intervalRight, options) {
+  const a = toInterval(intervalLeft)
+  const b = toInterval(intervalRight)
+  if (Temporal.PlainDate.compare(a.start, a.end) > 0) {
+    throw new RangeError('daymath: intervalLeft start must not be after end')
+  }
+  if (Temporal.PlainDate.compare(b.start, b.end) > 0) {
+    throw new RangeError('daymath: intervalRight start must not be after end')
+  }
+  const inclusive = options?.inclusive ?? false
+  if (inclusive) {
+    return (
+      Temporal.PlainDate.compare(a.start, b.end) <= 0 &&
+      Temporal.PlainDate.compare(b.start, a.end) <= 0
+    )
+  }
+  // date-fns default: touch-at-endpoint is NOT overlap
+  return (
+    Temporal.PlainDate.compare(a.start, b.end) < 0 &&
+    Temporal.PlainDate.compare(b.start, a.end) < 0
+  )
 }

package/package.json

@@ -1,22 +1,32 @@
 {
   "name": "daymath",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "Calendar date math (YYYY-MM-DD / PlainDate). date-fns-shaped. No time zones.",
   "type": "module",
   "main": "./index.js",
+  "types": "./index.d.ts",
   "exports": {
-    ".": "./index.js"
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
   },
   "files": [
     "index.js",
+    "index.d.ts",
     "README.md"
   ],
+  "scripts": {
+    "test": "node --test test.js",
+    "prepublishOnly": "npm test"
+  },
   "keywords": [
     "date",
     "calendar",
     "plain-date",
     "temporal",
-    "date-fns"
+    "date-fns",
+    "YYYY-MM-DD"
   ],
   "author": "leemr",
   "license": "MIT",
@@ -27,5 +37,11 @@
   "bugs": {
     "url": "https://github.com/leemr/daymath/issues"
   },
-  "homepage": "https://github.com/leemr/daymath#readme"
+  "homepage": "https://github.com/leemr/daymath#readme",
+  "dependencies": {
+    "temporal-polyfill": "^1.0.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
 }