daymath 0.6.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.
@@ -53,12 +53,29 @@ day(row.createdAt)                     // '2026-08-07'  a Date
 day(1761616161771)                     // '2025-10-28'  epoch milliseconds
 day('1999-01-01T00:00:00Z')            // '1999-01-01'  an ISO timestamp
 day('2026-05-05')                      // '2026-05-05'  already a day
+day('2026-08-08 12:00:00')             // '2026-08-08'  a SQLite DATETIME
 ```
 
+A **SQLite `DATETIME` goes straight in**, and so does the whole surface — the clock
+is dropped by the same funnel every export shares, so this is not a `day()` feature.
+
+```js
+addDays(row.created_at, 30)            // '2026-09-07'  from '2026-08-08 12:00:00'
+startOfMonth('2026-08-08 01:57:31.913') // '2026-08-01'  strftime('%…%H:%M:%f')
+getYear('2026-08-08t12:00')            // 2026          T, t or a space; same rule
+```
+
+`datetime()`, `CURRENT_TIMESTAMP` and `strftime('%Y-%m-%d %H:%M:%f')` all emit that
+shape, so a column value needs no reshaping first. **Pass a zone with one and it
+throws.** Naming a zone means convert, and a clock with no zone gives nothing to
+convert from — and `datetime()` defaults to UTC, so a silent answer would hand the
+UTC day to the one caller who asked for a local one. Put the zone in the string
+(`Z`, an offset, or `[Zone]`) and it converts normally.
+
 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
@@ -69,7 +86,7 @@ UTC is still not your day for part of every day — it runs ahead of `America/Ne
 for 16.7% of the day, and behind `Asia/Tokyo` for 37.5% — so name your zone when
 that matters.
 
-Four rules worth knowing:
+Six rules worth knowing:
 
 - A **number is epoch milliseconds**, exactly as `new Date(n)` reads it. A seconds
   timestamp read as milliseconds lands in 1970, with no error. daymath states the
@@ -84,9 +101,12 @@ Four rules worth knowing:
   the UTC default never applies. `day(zdt.toString())` equals `zdt.toPlainDate()`.
   A browser sending `'2026-08-08T20:00:00-04:00[America/New_York]'` gets back the
   8th, which is the date its user saw. Passing `tz` as well throws.
-- A string with **neither** is refused. `'2026-08-08T12:00'` names no instant and
-  no zone, so daymath would have to pick one, and it will not pick for you. Name
-  the zone — `'2026-08-08T12:00[America/New_York]'` — and it is accepted.
+- A **zoneless wall clock is a day.** `'2026-08-08 12:00:00'`, `'2026-08-08T12:00'`
+  and the lowercase `t` all answer `'2026-08-08'`; the clock is dropped, never read.
+  The **hour is the only bound**, because the hour is the only field that can change
+  the date: `24:00` is refused, a leap second and a fraction of any length are not.
+  Pass `tz` with one and it **throws**. Name the zone in the string —
+  `'2026-08-08T12:00[America/New_York]'` — and it converts.
 - **`'11/12/2026'` is refused.** Nobody can tell November from December in it.
 
 A lone string takes one of four roles, decided in this order: a day, a zoned time,
@@ -194,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

@@ -4,6 +4,17 @@ 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`)
+ * - either of those with a zoneless wall clock on it, `YYYY-MM-DD HH:MM[:SS[.fff]]`,
+ *   with `T`, `t` or a space between them. The clock is dropped and never read, so
+ *   `getYear('2026-08-08 12:00:00')` is `2026`. This is the shape SQLite stores:
+ *   `datetime()`, `CURRENT_TIMESTAMP` and `strftime('%Y-%m-%d %H:%M:%f')` all emit
+ *   it, so a column value needs no reshaping. The **hour is the only bound**,
+ *   because the hour is the only field that can change the date: `24:00` is refused
+ *   because ISO `24:00` starts the next day, while a leap second `23:59:60` and a
+ *   fraction of any length stay inside their own day and are accepted.
+ *
+ * A clock naming a zone — `Z`, an offset, or `[Zone]` — is NOT day input. It names
+ * an instant, and `day()` is the only door an instant enters by.
  *
  * Usable range is the Temporal `PlainDate` range `-271821-04-19` …
  * `+275760-09-13`; a day outside it throws a `RangeError`.
@@ -50,8 +61,12 @@ export type WeekOptions = {
  * own civil day and the UTC default never applies. Passing `tz` as well throws.
  *
  * `'11/12/2026'` is refused, because nobody can tell November from December in
- * it. `'2026-08-08T12:00'` is refused too: no offset and no zone, so daymath
- * would have to pick one. Name the zone and it is accepted.
+ * it.
+ *
+ * A zoneless wall clock is a day, so `'2026-08-08 12:00:00'` — a SQLite
+ * `DATETIME` — answers `'2026-08-08'` and the clock is dropped. Pass `tz` with
+ * one and it throws: naming a zone means convert, and a clock with no zone gives
+ * nothing to convert from. Put the zone in the string and it converts.
  *
  * A lone string takes one of four roles, in this order: a day, a zoned time, an
  * instant, then a zone. The zone test is by shape — an IANA name, which carries
@@ -65,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

@@ -55,6 +55,45 @@ const RUNTIME_CALENDARS = new Set(
  */
 const ISO_DAY = /^(?:[+-]\d{6}|\d{4})-\d{2}-\d{2}$/u
 
+/**
+ * A day with a wall clock and no zone: `YYYY-MM-DD HH:MM[:SS[.fff]]`, with `T`,
+ * `t` or a space between them. Group 1 is the day. The clock gets dropped.
+ *
+ * This is what SQLite hands you — `datetime('now')`, `CURRENT_TIMESTAMP` and
+ * `strftime('%Y-%m-%d %H:%M:%f')` all emit a space, seconds and optional
+ * fractions — so a column value needs no reshaping before daymath reads it.
+ *
+ * **All three separators, because a separator is punctuation and never
+ * information.** Temporal accepts a space and a lowercase `t` wherever it accepts
+ * `T`, and the ZONED forms of all three already answered, so the only hole was a
+ * clock naming NO zone.
+ *
+ * **The hour is the only bound, because the hour is the only field that can
+ * change the date. That is the whole rule: daymath drops a clock only when the
+ * clock cannot move the day.** A leap second and a fraction of any length stay
+ * inside their own day, so both are accepted, matching what `day('…23:59:60Z')`
+ * already answered.
+ *
+ * **`24:00` is refused, and the reason is that SQLite disagrees with itself
+ * about it.** ISO `24:00` is midnight starting the NEXT day, and SQLite's own
+ * `julianday('2026-08-08 24:00:00')` is 2461261.5 — byte-identical to
+ * `julianday('2026-08-09 00:00:00')` — while its `date()` and
+ * `strftime('%Y-%m-%d')` on the same string both answer `'2026-08-08'`. So no
+ * answer daymath could give agrees with the database: the 9th contradicts its
+ * `date()`, the 8th contradicts its `julianday()`. Refusing is the only option
+ * that never silently disagrees. Temporal refuses `24:00` on every path too, so
+ * accepting would also mean doing carry arithmetic the engine will not do.
+ *
+ * That also separates it from the two cases above. `t` and `:60` were holes
+ * because the ZONED twin already answered; every `24:00` spelling is refused
+ * today, zoned and zoneless, so refusing it is the consistent choice.
+ *
+ * `Z`, an offset and a `[Zone]` cannot reach this pattern — it is anchored — so
+ * a string that names a real instant still takes the instant path in `day()`.
+ */
+const ISO_DAY_TIME =
+  /^((?:[+-]\d{6}|\d{4})-\d{2}-\d{2})[Tt ](?:[01]\d|2[0-3]):[0-5]\d(?::(?:[0-5]\d|60)(?:\.\d+)?)?$/u
+
 /**
  * Temporal's calendar annotation, `[u-ca=…]` or the critical `[!u-ca=…]`.
  * Returns what it is attached to, and the calendar it names, or `null`.
@@ -153,13 +192,19 @@ const ZONE_LIKE =
  * One predicate, because `toPlainDate` and `day()` both ask this question. They
  * asked it separately once, and day() alone then refused a string that every
  * other export accepted.
+ *
+ * `clock` reports whether a zoneless wall clock came off the string. Every export ignores it and
+ * answers the same day either way; only `day()` reads it, because `day()` is the only one that
+ * takes a zone and so the only one that can be asked to convert what it just discarded.
  * @param {string} text
- * @returns {string | null}
+ * @returns {{ day: string, clock: boolean } | null}
  */
 function bareDay(text) {
   const annotated = calendarAnnotation(text)
   const bare = annotated ? annotated.head : text
-  return ISO_DAY.test(bare) ? bare : null
+  if (ISO_DAY.test(bare)) return { day: bare, clock: false }
+  const clocked = ISO_DAY_TIME.exec(bare)
+  return clocked === null ? null : { day: clocked[1], clock: true }
 }
 
 /**
@@ -341,14 +386,15 @@ function toPlainDate(value, label = 'date') {
   const bare = bareDay(text)
   if (bare === null) {
     throw new RangeError(
-      `daymath: ${label} must be ISO 8601 day YYYY-MM-DD or ±YYYYYY-MM-DD (got ${JSON.stringify(text)})`,
+      `daymath: ${label} must be ISO 8601 day YYYY-MM-DD or ±YYYYYY-MM-DD, optionally with a zoneless clock HH:MM[:SS[.fff]] after a T, t or space, where only the hour is bounded (00-23) (got ${JSON.stringify(text)})`,
     )
   }
   try {
     // The bare day is parsed with the ISO resolver's own entry point. `getAny` is passed as the
     // resolver rather than called, because `fromString` calls it with whatever the string names,
-    // and a bare day names nothing.
-    const plain = PlainDateFns.fromString(bare, getAny)
+    // and a bare day names nothing. A wall clock is already off the string by this line, so no
+    // export ever parses one and every answer stays a day.
+    const plain = PlainDateFns.fromString(bare.day, getAny)
     // The annotation rides along, so getYear answers 2569 for a Buddhist day and every
     // returned string keeps the calendar the caller named.
     return calendar === undefined
@@ -502,6 +548,9 @@ function toInterval(interval) {
  *   truncated the same way, so a fractional value is not an error
  * - an ISO 8601 day string, or a `Temporal.PlainDate` from any implementation,
  *   both of which are already a day
+ * - a day carrying a zoneless wall clock, `'YYYY-MM-DD HH:MM[:SS[.fff]]'`, with
+ *   `T`, `t` or a space between them: a day with noise on it, and the clock is
+ *   dropped. Only the hour is bounded, at 00-23
  * - an ISO 8601 timestamp carrying `Z` or an offset, which names an exact
  *   instant, so there is nothing left to guess
  * - a string carrying a `[Zone]` annotation, which names its own zone, so it
@@ -518,9 +567,15 @@ function toInterval(interval) {
  * ways in one function.
  *
  * `'11/12/2026'` is refused. Nobody can tell November from December in it.
- * `'2026-08-08T12:00'` is refused too: no offset and no zone, so daymath would
- * have to pick one, and it will not pick on the caller's behalf. Name the zone
- * — `'2026-08-08T12:00[America/New_York]'` — and it is accepted.
+ *
+ * A **zoneless wall clock is a day**, so `'2026-08-08 12:00:00'` and
+ * `'2026-08-08T12:00'` both answer `'2026-08-08'`. The clock is dropped, never
+ * read. That is what SQLite hands you from `datetime()` and `CURRENT_TIMESTAMP`,
+ * and it takes the day path here exactly as a bare day does.
+ *
+ * **Pass `tz` with one and it throws.** Naming a zone means convert, and a clock
+ * with no zone gives nothing to convert from. Name the zone in the string —
+ * `'2026-08-08T12:00[America/New_York]'`, or `Z`, or an offset — and it converts.
  *
  * A lone string takes one of four roles, decided in this order: a day, then a
  * zoned time, then an instant, then a zone. The zone test is by **shape**, and
@@ -543,20 +598,22 @@ 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 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
   // toPlainDate uses, so day() cannot drift from the other 68 exports.
-  const isDay =
-    isPlainDate(moment) || (typeof moment === 'string' && bareDay(moment) !== null)
+  const bare = typeof moment === 'string' ? bareDay(moment) : null
+  const isDay = isPlainDate(moment) || bare !== null
   const isMoment = isDay || moment instanceof Date || typeof moment === 'number'
 
   let zone = tz
@@ -672,7 +729,25 @@ export function day(moment, tz) {
   // plain ISO day comes out. Carrying it here also could not be made
   // consistent, because an `Instant` has no fields for a calendar to renumber,
   // so that path has nothing to carry and would answer bare ISO regardless.
-  if (isDay) return toDayString(isoOf(toPlainDate(moment)))
+  if (isDay) {
+    // The value is judged FIRST, so a day that does not exist reports itself rather than the zone.
+    // The guard below is about the argument PAIR, so it must never pre-empt a fault in either half.
+    const answer = toDayString(isoOf(toPlainDate(moment)))
+    // The one argument pair daymath refuses rather than answers. On 2026-08-24 SQLite's
+    // `datetime('now')` read 2026-08-24 01:57:31 and `datetime('now','localtime')` read
+    // 2026-08-23 21:57:31 — different days — because `datetime()` defaults to UTC. So the caller
+    // who stores the default and asks for a local day is the one a silent answer would mislead.
+    //
+    // Only this pair. A bare day plus a zone still answers, because no information was discarded
+    // there. Sibling of the `two time zones` refusals above, which a wall clock never reaches:
+    // both of those sit inside `if (!isMoment …)`.
+    if (bare?.clock && tz !== undefined && tz !== null) {
+      throw new TypeError(
+        `daymath: day() cannot apply the zone ${JSON.stringify(tz)} to ${JSON.stringify(moment)}, because that clock names no zone (add Z or an offset to it, or drop the zone)`,
+      )
+    }
+    return answer
+  }
 
   // The string named its own zone, so that zone decides the day, not the
   // default. This is the one path where `zone` is deliberately not consulted.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "daymath",
-  "version": "0.6.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": [
@@ -67,9 +69,9 @@
   "devDependencies": {
     "c8": "^12.0.0",
     "date-fns": "4.4.0",
-    "esbuild": "0.28.1",
-    "oxfmt": "0.62.0",
-    "oxlint": "1.77.0",
+    "esbuild": "0.28.2",
+    "oxfmt": "0.64.0",
+    "oxlint": "1.78.0",
     "typescript": "7.0.2"
   }
 }