daymath 0.7.0 → 0.7.1

package/README.md

@@ -42,8 +42,8 @@ that reads a clock.
 Start here. No arguments means today, in UTC.
 
 ```js
-day()                                  // '2026-08-08'
-addDays(day(), 2)                      // '2026-08-10'
+day()                                  // today, in UTC
+addDays(day(), 2)                      // two days from today
 ```
 
 Then hand it whatever you already have. It converts; it never stores what you gave it.
@@ -75,7 +75,7 @@ UTC day to the one caller who asked for a local one. Put the zone in the string
 Name a zone when the answer depends on one.
 
 ```js
-day('Asia/Tokyo')                      // '2026-08-09'  today in Tokyo
+day('Asia/Tokyo')                      // today in Tokyo
 day(row.createdAt, 'America/New_York') // '2026-08-06'  the evening before
 day('2026-08-08T23:00:00Z', 'Asia/Tokyo') // '2026-08-09'  same instant, next day
 day(zdt.toString())                    // the zone in the string wins
@@ -214,7 +214,7 @@ For the accepting family only the year label moves, so every export still answer
 the annotation rides along:
 
 ```js
-getYear('2026-01-31[u-ca=buddhist]')        // 2569, not 2026
+getYear('2026-01-31[u-ca=buddhist]')        // 2569  not 2026
 getMonth('2026-01-31[u-ca=buddhist]')       // 1
 addDays('2026-01-31[u-ca=buddhist]', 1)     // '2026-02-01[u-ca=buddhist]'
 setYear('2026-01-31[u-ca=buddhist]', 2570)  // '2027-01-31[u-ca=buddhist]'

package/index.d.ts

@@ -80,121 +80,351 @@ export type WeekOptions = {
  *
  * A calendar that renumbers months or days is still refused where it is
  * applied, which means with a `[Zone]` bracket and on a day string.
+ * @example day(row.createdAt)             // a Date, read in UTC
+ * @example day(row.createdAt, 'Asia/Tokyo') // the same instant, Tokyo's day
+ * @example day('1999-01-01T00:00:00Z')    // '1999-01-01'
+ * @example day('2026-08-08 12:00:00')     // '2026-08-08'  a SQLite DATETIME
+ * @example day('2026-05-05', 'Asia/Tokyo') // '2026-05-05'  a day carries no time
  */
-export function day(tz?: string): string
 export function day(
   moment: Date | number | DayInput | null | undefined,
   tz?: string,
 ): string
+/**
+ * Today's calendar day, in a zone. **This is the one overload that reads a clock**, so it is the
+ * only call in daymath that is not a pure function. Give the other overload a moment and it is.
+ *
+ * The zone defaults to UTC, and the default is STATED rather than assumed: daymath has no silent
+ * local now. UTC is not your day for part of every day — it runs ahead of `America/New_York` for
+ * 16.7% of the day and behind `Asia/Tokyo` for 37.5% — so name your zone when that matters.
+ *
+ * A lone string here is read as a zone only after it fails to be a day, a zoned time and an
+ * instant, in that order. The zone test is by shape, so a timestamp can never be read as a zone.
+ * @example day()             // today, in UTC
+ * @example day('Asia/Tokyo') // today in Tokyo
+ * @example day('+05:30')     // a bare offset is a zone too
+ */
+export function day(tz?: string): string
 
 /**
  * True for a valid daymath day string / PlainDate.
  * Invalid strings → false. `Date` → throws TypeError (not a quiet false).
+ * @example isValid('2026-08-08')       // true
+ * @example isValid('2026-02-30')       // false
+ * @example isValid('2026-08-08 12:00:00') // true   clock dropped
+ * @example isValid(new Date())         // throws TypeError, not false
  */
 export function isValid(value: unknown): boolean
 
-/** Validate / normalize to ISO 8601 day string (Temporal `toString` form). */
+/**
+ * Validate / normalize to ISO 8601 day string (Temporal `toString` form).
+ *
+ * `parse` preserves what it is given; `day()` normalizes. So a calendar
+ * annotation survives here and is dropped by `day()`.
+ * @example parse('2026-08-08')                // '2026-08-08'
+ * @example parse('2026-08-08 12:00:00')       // '2026-08-08'  clock dropped
+ * @example parse('2026-01-31[u-ca=buddhist]') // '2026-01-31[u-ca=buddhist]'
+ * @example parse('2026-02-30')                // throws RangeError
+ */
 export function parse(date: DayInput): string
 
-/** Format as ISO day (only `yyyy-MM-dd` / `YYYY-MM-DD` patterns supported). */
+/**
+ * Format as ISO day (only `yyyy-MM-dd` / `YYYY-MM-DD` patterns supported).
+ *
+ * Not locale display. For that, use `Intl` or a date-fns formatter.
+ * @example format('2026-08-08')               // '2026-08-08'
+ * @example format('2026-08-08', 'dd/MM/yyyy') // throws RangeError
+ */
 export function format(date: DayInput, pattern?: 'yyyy-MM-dd' | 'YYYY-MM-DD'): string
 
+/**
+ * @example addDays('2026-08-08', 30) // '2026-09-07'
+ * @example addDays('2026-08-08', -1) // '2026-08-07'
+ */
 export function addDays(date: DayInput, amount: number): string
+/** @example subDays('2026-08-08', 1) // '2026-08-07' */
 export function subDays(date: DayInput, amount: number): string
+/** @example addWeeks('2026-08-08', 2) // '2026-08-22' */
 export function addWeeks(date: DayInput, amount: number): string
+/** Whole weeks. @example subWeeks('2026-08-22', 2) // '2026-08-08' */
 export function subWeeks(date: DayInput, amount: number): string
+/**
+ * Overflow **clamps** to the last day of the target month; it never rolls into
+ * the next one. Same rule in both directions, and the same rule `setMonth`,
+ * `setDate` and `setYear` use.
+ * @example addMonths('2026-01-31', 1)  // '2026-02-28'  clamped, not '2026-03-03'
+ * @example addMonths('2026-03-31', -1) // '2026-02-28'
+ * @example addMonths('2024-01-31', 1)  // '2024-02-29'  leap year
+ */
 export function addMonths(date: DayInput, amount: number): string
+/**
+ * Clamps, exactly as `addMonths` does.
+ * @example subMonths('2026-03-31', 1) // '2026-02-28'  clamped
+ */
 export function subMonths(date: DayInput, amount: number): string
+/**
+ * Clamps, so 29 February lands on the 28th of a common year.
+ * @example addYears('2024-02-29', 1) // '2025-02-28'  clamped
+ */
 export function addYears(date: DayInput, amount: number): string
+/**
+ * Clamps, exactly as `addYears` does.
+ * @example subYears('2024-02-29', 1) // '2023-02-28'  clamped
+ */
 export function subYears(date: DayInput, amount: number): string
+/**
+ * Three months at a time, and it clamps.
+ * @example addQuarters('2026-01-31', 1) // '2026-04-30'  clamped
+ */
 export function addQuarters(date: DayInput, amount: number): string
+/** Three months back, and it clamps. @example subQuarters('2026-04-30', 1) // '2026-01-30' */
 export function subQuarters(date: DayInput, amount: number): string
 
-/** Full year number. */
+/**
+ * Full year number. An annotation is applied on top of the ISO date part, never instead of it.
+ * @example getYear('2026-08-08') // 2026
+ * @example getYear('2026-01-31[u-ca=buddhist]') // 2569  the annotation adds 543
+ */
 export function getYear(date: DayInput): number
-/** Month number, ISO 8601: 1 = January … 12 = December. Not date-fns's 0-based index. */
+/**
+ * Month number, ISO 8601: 1 = January … 12 = December. Not date-fns's 0-based index.
+ * @example getMonth('2026-08-08') // 8   — date-fns would answer 7
+ * @example getMonth('2026-01-15') // 1
+ */
 export function getMonth(date: DayInput): number
-/** Day of month 1…31. */
+/** Day of month 1…31. @example getDate('2026-08-08') // 8 */
 export function getDate(date: DayInput): number
-/** Weekday, ISO 8601: 1 = Monday … 7 = Sunday. Only Sunday differs from date-fns. */
+/**
+ * Weekday, ISO 8601: 1 = Monday … 7 = Sunday. Only Sunday differs from date-fns.
+ * @example getDay('2026-08-10') // 1   a Monday
+ * @example getDay('2026-08-09') // 7   a Sunday — date-fns would answer 0
+ */
 export function getDay(date: DayInput): number
+/** 1 on 1 January. @example getDayOfYear('2026-03-01') // 60 */
 export function getDayOfYear(date: DayInput): number
+/** @example getDaysInMonth('2024-02-10') // 29 */
 export function getDaysInMonth(date: DayInput): number
-/** Quarter 1…4. */
+/** Quarter 1…4. @example getQuarter('2026-08-08') // 3 */
 export function getQuarter(date: DayInput): number
+/**
+ * Leap year of the day's own ISO year.
+ *
+ * **This is the one way to get a wrong answer with no error**, and it is worth reading before
+ * you pass a non-ISO calendar's year. A `[u-ca=…]` day is judged on its ISO year, which is the
+ * date part — so a Buddhist year written as a bare ISO year is a different year. Buddhist 2567
+ * is ISO 2024 and IS a leap year, but 2567 read as ISO is not, because 543 mod 4 is 3. The two
+ * rules disagree in 49 of the 101 Buddhist years from 2500 to 2600, and nothing throws.
+ * @example isLeapYear('2024-01-01') // true
+ * @example isLeapYear('2567-01-01') // false  ISO 2567, NOT Buddhist 2567 (which is ISO 2024)
+ */
 export function isLeapYear(date: DayInput): boolean
 
+/**
+ * Overflow clamps, so 29 February survives a move to a common year. **date-fns rolls here
+ * instead**, so this is the second deliberate disagreement after `setDate` — and the one a caller
+ * reaches by accident, through a stored 29 February.
+ * @example setYear('2024-02-29', 2026) // '2026-02-28'  clamped; date-fns gives '2026-03-01'
+ */
 export function setYear(date: DayInput, year: number): string
-/** `month`: 1 = January … 12 = December (ISO 8601). */
+/**
+ * `month`: 1 = January … 12 = December (ISO 8601). Overflow clamps.
+ * @example setMonth('2026-01-31', 2) // '2026-02-28'  clamped
+ */
 export function setMonth(date: DayInput, month: number): string
+/**
+ * Overflow clamps to the end of the month. **date-fns rolls here instead**, so
+ * this is one of the few places the two answer differently on purpose.
+ * @example setDate('2026-02-01', 31) // '2026-02-28'  daymath clamps
+ */
 export function setDate(date: DayInput, dayOfMonth: number): string
 
+/** @example startOfMonth('2026-08-08') // '2026-08-01' */
 export function startOfMonth(date: DayInput): string
+/**
+ * @example endOfMonth('2024-02-01') // '2024-02-29'
+ */
 export function endOfMonth(date: DayInput): string
+/** @example startOfYear('2026-08-08') // '2026-01-01' */
 export function startOfYear(date: DayInput): string
+/** @example endOfYear('2026-08-08') // '2026-12-31' */
 export function endOfYear(date: DayInput): string
+/** @example startOfQuarter('2026-08-08') // '2026-07-01' */
 export function startOfQuarter(date: DayInput): string
+/** @example endOfQuarter('2026-08-08') // '2026-09-30' */
 export function endOfQuarter(date: DayInput): string
+/**
+ * `weekStartsOn` defaults to **7 (Sunday)**, and `0` is accepted for Sunday too.
+ * @example startOfWeek('2026-08-12')                     // '2026-08-09'  Sunday
+ * @example startOfWeek('2026-08-12', { weekStartsOn: 1 }) // '2026-08-10'  Monday
+ */
 export function startOfWeek(date: DayInput, options?: WeekOptions): string
+/**
+ * `weekStartsOn` defaults to 7 (Sunday), so the week ends on Saturday.
+ * @example endOfWeek('2026-08-12')                     // '2026-08-15'  Saturday
+ * @example endOfWeek('2026-08-12', { weekStartsOn: 1 }) // '2026-08-16'  Sunday
+ */
 export function endOfWeek(date: DayInput, options?: WeekOptions): string
 
-/** Full days: `dateLeft − dateRight` (date-fns argument order). */
+/**
+ * Full days: `dateLeft − dateRight` (date-fns argument order).
+ * @example differenceInDays('2026-08-08', '2026-08-01') //  7
+ * @example differenceInDays('2026-08-01', '2026-08-08') // -7  order matters
+ */
 export function differenceInDays(dateLeft: DayInput, dateRight: DayInput): number
+/** Whole weeks. @example differenceInWeeks('2026-08-15', '2026-08-08') // 1 */
 export function differenceInWeeks(dateLeft: DayInput, dateRight: DayInput): number
+/**
+ * A month counts as full when `addMonths` would carry the earlier date to the
+ * later one, so `differenceInMonths(addMonths(d, n), d) === n` always holds. Use
+ * `differenceInCalendarMonths` to count boundaries crossed instead.
+ * @example differenceInMonths('2026-02-28', '2026-01-31')         // 1  addMonths clamps to here
+ * @example differenceInCalendarMonths('2026-02-01', '2026-01-31') // 1  one boundary, one day apart
+ */
 export function differenceInMonths(dateLeft: DayInput, dateRight: DayInput): number
+/**
+ * Month boundaries crossed, not whole months. `differenceInMonths` is the other question.
+ * @example differenceInCalendarMonths('2026-02-01', '2026-01-31') // 1  one day apart
+ */
 export function differenceInCalendarMonths(
   dateLeft: DayInput,
   dateRight: DayInput,
 ): number
+/**
+ * Counts by `addYears`, the same rule `differenceInMonths` uses, so the round-trip law holds.
+ * @example differenceInYears('2026-02-28', '2024-02-29') // 2  addYears clamps to here
+ */
 export function differenceInYears(dateLeft: DayInput, dateRight: DayInput): number
+/**
+ * Boundaries crossed, not whole years.
+ * @example differenceInCalendarYears('2026-01-01', '2025-12-31') // 1  one day apart
+ */
 export function differenceInCalendarYears(dateLeft: DayInput, dateRight: DayInput): number
+/** Counts by `addQuarters`. @example differenceInQuarters('2026-07-01', '2026-01-01') // 2 */
 export function differenceInQuarters(dateLeft: DayInput, dateRight: DayInput): number
+/**
+ * Quarter boundaries crossed, not whole quarters.
+ * @example differenceInCalendarQuarters('2026-07-01', '2026-06-30') // 1  one day apart
+ */
 export function differenceInCalendarQuarters(
   dateLeft: DayInput,
   dateRight: DayInput,
 ): number
 
+/**
+ * Strictly before; an equal pair is `false`.
+ * @example isBefore('2026-08-01', '2026-08-08') // true
+ * @example isBefore('2026-08-08', '2026-08-08') // false  not strictly before
+ */
 export function isBefore(date: DayInput, dateToCompare: DayInput): boolean
+/** Strictly after. @example isAfter('2026-08-01', '2026-08-08') // false */
 export function isAfter(date: DayInput, dateToCompare: DayInput): boolean
-/** Same calendar day. */
+/**
+ * Same calendar day, and the calendar label is ignored. Temporal's own `equals`
+ * compares the calendar too, so it answers `false` for one day written two ways;
+ * daymath compares the day alone and answers `true`.
+ * @example isEqual('2026-01-31[u-ca=buddhist]', '2026-01-31') // true  same day
+ */
 export function isEqual(dateLeft: DayInput, dateRight: DayInput): boolean
-/** Alias of `isEqual` (date-fns name). */
+/**
+ * Alias of `isEqual` (date-fns name), and it ignores the calendar label the same way.
+ * @example isSameDay('2026-01-31[u-ca=buddhist]', '2026-01-31') // true  same day
+ */
 export const isSameDay: typeof isEqual
 
+/**
+ * `weekStartsOn` defaults to 7 (Sunday), so a Saturday and the Sunday after it are DIFFERENT weeks.
+ * @example isSameWeek('2026-08-08', '2026-08-09')                     // false  Sat then Sun
+ * @example isSameWeek('2026-08-08', '2026-08-09', { weekStartsOn: 1 }) // true   Monday weeks
+ */
 export function isSameWeek(
   dateLeft: DayInput,
   dateRight: DayInput,
   options?: WeekOptions,
 ): boolean
+/** Same month AND year. @example isSameMonth('2026-08-01', '2026-08-31') // true */
 export function isSameMonth(dateLeft: DayInput, dateRight: DayInput): boolean
+/** @example isSameYear('2026-01-01', '2026-12-31') // true */
 export function isSameYear(dateLeft: DayInput, dateRight: DayInput): boolean
+/** @example isSameQuarter('2026-07-01', '2026-09-30') // true */
 export function isSameQuarter(dateLeft: DayInput, dateRight: DayInput): boolean
 
+/**
+ * Comparator for `Array.prototype.sort`, oldest first.
+ * @example compareAsc('2026-01-01', '2026-08-08') // -1
+ */
 export function compareAsc(dateLeft: DayInput, dateRight: DayInput): -1 | 0 | 1
+/** Newest first. @example compareDesc('2026-01-01', '2026-08-08') // 1 */
 export function compareDesc(dateLeft: DayInput, dateRight: DayInput): -1 | 0 | 1
 
+/**
+ * Takes an **array**, not a rest argument.
+ * @example min(['2026-08-08', '2026-01-01']) // '2026-01-01'
+ */
 export function min(dates: DayInput[]): string
+/**
+ * Takes an **array**, not a rest argument, exactly as `min` does.
+ * @example max(['2026-01-01', '2026-08-08']) // '2026-08-08'
+ */
 export function max(dates: DayInput[]): string
 
+/** ISO weekday 7. @example isSunday('2026-08-09') // true */
 export function isSunday(date: DayInput): boolean
+/** ISO weekday 1. @example isMonday('2026-08-10') // true */
 export function isMonday(date: DayInput): boolean
+/** ISO weekday 2. @example isTuesday('2026-08-11') // true */
 export function isTuesday(date: DayInput): boolean
+/** ISO weekday 3. @example isWednesday('2026-08-12') // true */
 export function isWednesday(date: DayInput): boolean
+/** ISO weekday 4. @example isThursday('2026-08-13') // true */
 export function isThursday(date: DayInput): boolean
+/** ISO weekday 5. @example isFriday('2026-08-14') // true */
 export function isFriday(date: DayInput): boolean
+/** ISO weekday 6. @example isSaturday('2026-08-08') // true */
 export function isSaturday(date: DayInput): boolean
+/**
+ * ISO Saturday and Sunday (6 and 7). Not configurable, and no holiday calendar.
+ * @example isWeekend('2026-08-08') // true   a Saturday
+ * @example isWeekend('2026-08-10') // false  a Monday
+ */
 export function isWeekend(date: DayInput): boolean
+/** @example isFirstDayOfMonth('2026-08-01') // true */
 export function isFirstDayOfMonth(date: DayInput): boolean
+/** @example isLastDayOfMonth('2024-02-29') // true  leap year */
 export function isLastDayOfMonth(date: DayInput): boolean
 
+/**
+ * Both ends **inclusive**, so a one-day interval returns one day.
+ * @example eachDayOfInterval({ start: '2026-08-08', end: '2026-08-10' })
+ * // ['2026-08-08', '2026-08-09', '2026-08-10']
+ */
 export function eachDayOfInterval(interval: Interval): string[]
+/**
+ * The FIRST of each month touched, both ends inclusive.
+ * @example eachMonthOfInterval({ start: '2026-01-15', end: '2026-03-02' })
+ * // ['2026-01-01', '2026-02-01', '2026-03-01']
+ */
 export function eachMonthOfInterval(interval: Interval): string[]
+/**
+ * The FIRST of January of each year touched, both ends inclusive.
+ * @example eachYearOfInterval({ start: '2025-06-01', end: '2026-02-01' })
+ * // ['2025-01-01', '2026-01-01']
+ */
 export function eachYearOfInterval(interval: Interval): string[]
+/**
+ * Both ends **inclusive**, so a date equal to an endpoint is within.
+ * @example isWithinInterval('2026-08-10', { start: '2026-08-08', end: '2026-08-10' }) // true
+ */
 export function isWithinInterval(date: DayInput, interval: Interval): boolean
+/**
+ * Pull a day inside the interval, or return it unchanged if it is already inside.
+ * @example clamp('2026-12-25', { start: '2026-08-08', end: '2026-08-10' }) // '2026-08-10'
+ */
 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.
+ * @example areIntervalsOverlapping({ start: '2026-08-01', end: '2026-08-08' }, { start: '2026-08-08', end: '2026-08-10' }) // false
+ * @example areIntervalsOverlapping({ start: '2026-08-01', end: '2026-08-08' }, { start: '2026-08-08', end: '2026-08-10' }, { inclusive: true }) // true
  */
 export function areIntervalsOverlapping(
   intervalLeft: Interval,

package/index.js

@@ -598,16 +598,16 @@ function toInterval(interval) {
  *   annotation is accepted on input and dropped from the result. Every other export carries it.
  * @throws {TypeError} If `moment` is not one of the accepted shapes
  * @throws {RangeError} On an Invalid Date, a non-finite number, or an unknown zone
- * @example day()                              // '2026-08-08'  now, UTC
- * @example day('Asia/Tokyo')                  // '2026-08-09'  today in Tokyo
- * @example day(row.createdAt)                 // '2026-08-07'  a Date, UTC
- * @example day(row.createdAt, 'America/New_York') // '2026-08-06'
+ * @example day()                              // today, in UTC
+ * @example day('Asia/Tokyo')                  // today in Tokyo
+ * @example day(row.createdAt)                 // a Date, read in UTC
+ * @example day(row.createdAt, 'America/New_York') // the same instant, New York's day
  * @example day(1761616161771)                 // '2025-10-28'  epoch ms
  * @example day('1999-01-01T00:00:00Z')        // '1999-01-01'  an ISO timestamp
  * @example day(zdt.toString())                // the zone in the string wins
- * @example day(row.created_at)                // '2026-08-08'  a SQLite DATETIME
- * @example day('2026-08-08 12:00:00', 'utc')  // throws: the clock names no zone
- * @example addDays(day(), 2)                  // '2026-08-10'
+ * @example day(row.created_at)                // a SQLite DATETIME
+ * @example day('2026-08-08 12:00:00', 'utc')  // throws TypeError, the clock names no zone
+ * @example addDays(day(), 2)                  // two days from today
  */
 export function day(moment, tz) {
   // Already a day, in every accepted spelling. `bareDay` is the same predicate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "daymath",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Calendar date math (ISO 8601 day / PlainDate). date-fns-shaped. No Date. No time zones.",
   "type": "module",
   "main": "./index.js",
@@ -29,11 +29,13 @@
     "test:runtimes": "node scripts/cross-runtime.mjs",
     "test:runtimes:write": "node scripts/cross-runtime.mjs --write",
     "test:intl-day": "node scripts/intl-day.mjs",
+    "test:examples": "node scripts/examples.mjs",
+    "test:examples:write": "node scripts/examples.mjs --write",
     "test:intl-day:sweep": "node scripts/intl-day.mjs --sweep",
     "size": "node scripts/bundle-size.mjs --run",
     "size:check": "node scripts/bundle-size.mjs --check",
     "size:write": "node scripts/bundle-size.mjs --write",
-    "prepublishOnly": "npm run test:coverage",
+    "prepublishOnly": "npm run test:coverage && npm run test:examples",
     "publish:github": "node scripts/publish-github-packages.mjs"
   },
   "keywords": [