daymath 0.1.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # daymath
 
-Calendar date math for `YYYY-MM-DD` strings. **date-fns-shaped** names. **Temporal.PlainDate** under the hood.
+Calendar date math for **ISO 8601** day strings. **date-fns-shaped** names. **Temporal.PlainDate** under the hood.
 
 No `Date`. No time zones. No silent “local now.”
 
@@ -20,34 +20,73 @@ import {
   addMonths,
   differenceInDays,
   isBefore,
-  parse,
+  isSameDay,
+  startOfMonth,
+  eachDayOfInterval,
 } from 'daymath'
 
-addDays('2026-08-06', 1)           // '2026-08-07'
-addMonths('2026-01-31', 1)         // '2026-02-28' (constrain)
+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
-parse('2026-08-06')                // '2026-08-06'
+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'
+addDays('9999-12-31', 1)                    // '+010000-01-01' (expanded year)
+eachDayOfInterval({
+  start: '2026-08-05',
+  end: '2026-08-07',
+}) // ['2026-08-05', '2026-08-06', '2026-08-07']
 ```
 
-Inputs: `YYYY-MM-DD` string or `Temporal.PlainDate`.  
-Outputs: always `YYYY-MM-DD` string (for math helpers).
+**Inputs:** ISO 8601 day string or `Temporal.PlainDate`.  
+- `YYYY-MM-DD` (years 0000–9999)  
+- expanded `±YYYYYY-MM-DD` (e.g. `+010000-01-01`)  
 
-`Date` throws. Time-bearing ISO strings throw. Sloppy forms like `2026-8-6` throw.
+**Outputs:** Temporal’s ISO day string (same forms).
 
-## API
+`Date` throws (including `isValid(date)`). Bad strings: math helpers throw; `isValid('asdf')` → `false`. Time-bearing / sloppy forms throw.
 
-| Function | Notes |
-|----------|--------|
-| `parse` / `format` / `isValid` | Strict `YYYY-MM-DD` |
-| `addDays` / `subDays` | |
-| `addWeeks` / `subWeeks` | |
-| `addMonths` / `subMonths` | Calendar months; end-of-month constrains |
-| `addYears` / `subYears` | Leap day constrains |
-| `differenceInDays` | `dateLeft − dateRight` (date-fns order) |
-| `isBefore` / `isAfter` / `isEqual` | |
-| `compareAsc` / `compareDesc` | For `.sort()` |
-| `min` / `max` | Non-empty arrays |
+See [FUTURE.md](./FUTURE.md) for backlog (bundle size, business days, …).
+
+## date-fns parity notes
+
+| Topic | daymath |
+|-------|---------|
+| Value type | ISO day string (not `Date`) |
+| `isSameDay` | Alias of `isEqual` (same calendar day) |
+| `isValid` | Our predicate: valid day string / PlainDate. `Date` **throws** (not date-fns’s Date check) |
+| `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.
 
@@ -57,7 +96,7 @@ Uses global `Temporal` when present; otherwise [`temporal-polyfill`](https://www
 
 ## Types
 
-Ships `index.d.ts` (no TypeScript compile step for authors). Source is plain JS.
+Ships `index.d.ts` (no TypeScript compile step). Source is plain JS.
 
 ## License
 

package/index.d.ts

@@ -1,17 +1,36 @@
 import type { Temporal } from 'temporal-polyfill'
 
 /**
- * Calendar day input: `YYYY-MM-DD` string, or a Temporal.PlainDate.
- * `Date` is rejected at runtime.
+ * 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`)
+ * `Date` is rejected at runtime (TypeError).
  */
 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
+}
+
+/**
+ * True for a valid daymath day string / PlainDate.
+ * Invalid strings → false. `Date` → throws TypeError (not a quiet false).
+ */
 export function isValid(value: unknown): boolean
 
-/** Validate / normalize to `YYYY-MM-DD`. */
+/** Validate / normalize to ISO 8601 day string (Temporal `toString` form). */
 export function parse(date: DayInput): string
 
-/** Format as `YYYY-MM-DD` (only pattern supported). */
+/** Format as ISO day (only `yyyy-MM-dd` / `YYYY-MM-DD` patterns supported). */
 export function format(date: DayInput, pattern?: 'yyyy-MM-dd' | 'YYYY-MM-DD'): string
 
 export function addDays(date: DayInput, amount: number): string
@@ -22,16 +41,91 @@ 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,12 +1,31 @@
-/** daymath — calendar date math (YYYY-MM-DD). date-fns-shaped. No Date / time zones. */
+/** daymath — calendar date math (ISO 8601 day). date-fns-shaped. No Date / time zones. */
 import { Temporal as TemporalPolyfill } from 'temporal-polyfill'
 
 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`)
+ */
+const ISO_DAY =
+  /^(?:[+-]\d{6}|\d{4})-\d{2}-\d{2}$/
+
 /** @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.
+ * Reject Date and non-calendar values. Accept ISO day string or PlainDate.
  * @param {unknown} value
  * @param {string} label
  * @returns {Temporal.PlainDate}
@@ -14,14 +33,13 @@ const Temporal = globalThis.Temporal ?? TemporalPolyfill
 function toPlainDate(value, label = 'date') {
   if (value instanceof Date) {
     throw new TypeError(
-      `daymath: Date is not allowed for ${label} (pass YYYY-MM-DD string)`,
+      `daymath: Date is not allowed for ${label} (pass ISO 8601 day string)`,
     )
   }
   if (typeof value === 'string') {
-    // Strict calendar day: no time, no offset, no week dates.
-    if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    if (!ISO_DAY.test(value)) {
       throw new RangeError(
-        `daymath: ${label} must be YYYY-MM-DD (got ${JSON.stringify(value)})`,
+        `daymath: ${label} must be ISO 8601 day YYYY-MM-DD or ±YYYYYY-MM-DD (got ${JSON.stringify(value)})`,
       )
     }
     try {
@@ -36,7 +54,7 @@ function toPlainDate(value, label = 'date') {
     return value
   }
   throw new TypeError(
-    `daymath: ${label} must be YYYY-MM-DD string or Temporal.PlainDate`,
+    `daymath: ${label} must be ISO 8601 day string or Temporal.PlainDate`,
   )
 }
 
@@ -45,8 +63,66 @@ function toDayString(plain) {
   return plain.toString()
 }
 
-/** @param {unknown} value */
+/** 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 ────────────────────────────────────────
+
+/**
+ * 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
+ */
 export function isValid(value) {
+  if (value instanceof Date) {
+    throw new TypeError(
+      'daymath: Date is not allowed for isValid (pass ISO 8601 day string)',
+    )
+  }
   try {
     toPlainDate(value)
     return true
@@ -56,7 +132,7 @@ export function isValid(value) {
 }
 
 /**
- * Validate / normalize a calendar day string.
+ * Validate / normalize an ISO 8601 calendar day string.
  * @param {DayInput} date
  * @returns {string}
  */
@@ -65,7 +141,7 @@ export function parse(date) {
 }
 
 /**
- * Format as YYYY-MM-DD (only supported pattern for now).
+ * Format as YYYY-MM-DD (only supported pattern).
  * @param {DayInput} date
  * @param {string} [pattern='yyyy-MM-dd']
  * @returns {string}
@@ -79,6 +155,8 @@ export function format(date, pattern = 'yyyy-MM-dd') {
   return toDayString(toPlainDate(date))
 }
 
+// ─── add / sub ─────────────────────────────────────────────────────
+
 /**
  * @param {DayInput} date
  * @param {number} amount
@@ -120,7 +198,7 @@ export function subWeeks(date, amount) {
 }
 
 /**
- * Calendar months (Temporal overflow: constrain — e.g. Jan 31 + 1 month → Feb 28/29).
+ * Calendar months (overflow constrain — Jan 31 + 1 month → Feb 28/29).
  * @param {DayInput} date
  * @param {number} amount
  * @returns {string}
@@ -160,6 +238,174 @@ export function subYears(date, 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
@@ -172,6 +418,89 @@ export function differenceInDays(dateLeft, 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
@@ -201,6 +530,7 @@ export function isAfter(date, dateToCompare) {
 }
 
 /**
+ * Same calendar day.
  * @param {DayInput} dateLeft
  * @param {DayInput} dateRight
  * @returns {boolean}
@@ -214,6 +544,50 @@ export function isEqual(dateLeft, dateRight) {
   )
 }
 
+/** 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
@@ -244,7 +618,9 @@ export function compareDesc(dateLeft, dateRight) {
 export function min(dates) {
   assertNonEmptyDates(dates)
   return toDayString(
-    dates.map((d) => toPlainDate(d)).reduce((a, b) => (Temporal.PlainDate.compare(a, b) <= 0 ? a : b)),
+    dates
+      .map((d) => toPlainDate(d))
+      .reduce((a, b) => (Temporal.PlainDate.compare(a, b) <= 0 ? a : b)),
   )
 }
 
@@ -255,23 +631,183 @@ export function min(dates) {
 export function max(dates) {
   assertNonEmptyDates(dates)
   return toDayString(
-    dates.map((d) => toPlainDate(d)).reduce((a, b) => (Temporal.PlainDate.compare(a, b) >= 0 ? a : b)),
+    dates
+      .map((d) => toPlainDate(d))
+      .reduce((a, b) => (Temporal.PlainDate.compare(a, b) >= 0 ? a : b)),
   )
 }
 
-/** @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`)
+// ─── 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')
   }
-  if (!Number.isInteger(n)) {
-    throw new RangeError(`daymath: ${label} must be an integer`)
+  /** @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
 }
 
-/** @param {unknown} dates */
-function assertNonEmptyDates(dates) {
-  if (!Array.isArray(dates) || dates.length === 0) {
-    throw new RangeError('daymath: expected a non-empty array of dates')
+/**
+ * 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,7 +1,7 @@
 {
   "name": "daymath",
-  "version": "0.1.0",
-  "description": "Calendar date math (YYYY-MM-DD / PlainDate). date-fns-shaped. No time zones.",
+  "version": "0.2.1",
+  "description": "Calendar date math (ISO 8601 day / PlainDate). date-fns-shaped. No time zones.",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",