daymath 0.3.0 → 0.4.0

package/README.md

@@ -5,10 +5,11 @@
 [![codecov](https://codecov.io/gh/leemr/daymath/graph/badge.svg)](https://codecov.io/gh/leemr/daymath)
 [![license](https://img.shields.io/npm/l/daymath.svg)](./LICENSE)
 [![node](https://img.shields.io/node/v/daymath.svg)](https://www.npmjs.com/package/daymath)
+[![bundle](https://img.shields.io/bundlejs/size/daymath)](https://bundlejs.com/?q=daymath)
 
 **ISO 8601** calendar day math. **date-fns-shaped** names. **Temporal.PlainDate** under the hood.
 
-No `Date`. No time zones. No silent “local now.” ISO 8601 ❤️
+No `Date`. No time zones. No silent “local now”. ISO 8601 ❤️
 
 [**Play →**](https://leemr.github.io/daymath/) · [npm](https://www.npmjs.com/package/daymath) · [Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md) · [FUTURE](./FUTURE.md)
 
@@ -27,7 +28,7 @@ npm install @leemr/daymath
 Most people should keep using **`daymath` on npmjs**.
 
 ```js
-import { addDays, addMonths, differenceInDays, isSameDay } from 'daymath'
+import { day, addDays, addMonths, differenceInDays, isSameDay } from 'daymath'
 
 addDays('2026-08-06', 1)      // '2026-08-07'
 addMonths('2026-01-31', 1)    // '2026-02-28'
@@ -35,6 +36,67 @@ differenceInDays('2026-08-06', '2026-08-01') // 5
 isSameDay('2026-08-06', '2026-08-06')        // true
 ```
 
+`day` is the way in. It turns a moment into a day, and it is the only function
+that reads a clock.
+
+Start here. No arguments means today, in UTC.
+
+```js
+day()                                  // '2026-08-08'
+addDays(day(), 2)                      // '2026-08-10'
+```
+
+Then hand it whatever you already have. It converts; it never stores what you gave it.
+
+```js
+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
+```
+
+Name a zone when the answer depends on one.
+
+```js
+day('Asia/Tokyo')                      // '2026-08-09'  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
+```
+
+Both defaults are **stated**, not assumed.
+UTC is still 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.
+
+Four 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
+  unit rather than sniffing it, because no rule can separate the two: 13 digits
+  means milliseconds for 2001–2286 and seconds for the year 275760, and both are
+  inside the supported range.
+- A **day carries no time**, so a zone does not apply to one.
+  `day('2026-05-05', 'Asia/Tokyo')` is `'2026-05-05'`.
+- A **timestamp carrying `Z` or an offset** names an exact instant, so it is read
+  as a moment.
+- A **string carrying a `[Zone]`** names its own zone, so it keeps its own day and
+  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.
+- **`'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,
+an instant, then a zone. The zone test is by **shape** — an IANA name, which carries no `:`, or
+a bare offset such as `+05:30`. Temporal's own zone grammar cannot decide the role:
+it accepts a whole timestamp and reads the zone out of it, so
+`day('1999-01-01T00:00:00Z')` would answer today. That grammar also differs between
+implementations — `'T12:00:00Z'` is a zone to native Temporal and not to the
+polyfill — which would make the answer depend on the runtime.
+
 ```bash
 node examples/basic.mjs   # from a clone
 ```
@@ -46,9 +108,14 @@ node examples/basic.mjs   # from a clone
 | In | Out |
 |----|-----|
 | `YYYY-MM-DD` or expanded `±YYYYYY-MM-DD` | same forms (Temporal `toString`) |
-| or `Temporal.PlainDate` | string |
+| or `Temporal.PlainDate`, from any implementation | string |
 
-`Date` **throws** (including `isValid`). `isValid('asdf')` → `false`.
+A `Date` **throws** everywhere except `day()`, including in `isValid`.
+`isValid('asdf')` → `false`.
+
+`day()` is the single door a `Date` comes through, and it makes you name the zone
+or take the stated UTC default. Nothing carries a zone past that point, and
+nothing gives you a `Date` back.
 
 Range: `-271821-04-19` … `+275760-09-13` — the `Temporal.PlainDate` limit, roughly ±10⁸ days from the epoch. A day outside it throws a `RangeError`.
 
@@ -66,6 +133,8 @@ Range: `-271821-04-19` … `+275760-09-13` — the `Temporal.PlainDate` limit, r
 
 ## API
 
+**Start here** — `day`  
+
 **Parse** — `parse` · `format` · `isValid`  
 
 **Add/sub** — Days · Weeks · Months · Years · Quarters  
@@ -86,11 +155,92 @@ Amounts are finite integers.
 
 ## Temporal
 
-Uses global `Temporal` when present; otherwise [`temporal-polyfill`](https://www.npmjs.com/package/temporal-polyfill).
+Uses global `Temporal` when present; otherwise [`temporal-polyfill`](https://www.npmjs.com/package/temporal-polyfill),
+which does that resolution itself — so on a runtime with native Temporal the polyfill steps aside.
+
+A `Temporal.PlainDate` from *any* implementation is accepted — native, the bundled polyfill,
+or a second copy of it in the same dependency tree. daymath reads its ISO day and builds its
+own instance, so it never depends on `instanceof` agreeing across copies. The common case is
+`Temporal.Now.plainDateISO()`: daymath has no `today()` on purpose, so that is where a caller
+gets one.
+
+A non-ISO calendar is refused, as an object and as a string alike. Temporal can put one on a
+`PlainDate`, and it names the same *day* with different numbers:
+
+| calendar | year | month | day | `toString()` |
+|---|---|---|---|---|
+| `iso8601` | 2026 | 1 | 31 | `2026-01-31` |
+| `buddhist` | **2569** | 1 | 31 | `2026-01-31[u-ca=buddhist]` |
+| `hebrew` | 5786 | 5 | 13 | `2026-01-31[u-ca=hebrew]` |
+| `chinese` | 2025 | 13 | 13 | `2026-01-31[u-ca=chinese]` |
+
+Thai Buddhist years run 543 ahead, so the same day is 2569. Worse, the same number means two
+different days depending on where you write it:
+
+```js
+Temporal.PlainDate.from('2026-01-31[u-ca=buddhist]')            // ISO 2026-01-31, .year 2569
+Temporal.PlainDate.from({year: 2026, month: 1, day: 31,
+                         calendar: 'buddhist'})                  // ISO 1483-01-31, .year 2026
+```
+
+543 years apart. The date part of a string is always ISO; the annotation changes how fields are
+*read*, never how the string *parses*. daymath could strip the annotation and answer
+`2026-01-31`, which is the right day — but `getYear` would then return `2026` where your own
+object says `2569`. So it throws, naming the calendar and the way out:
+
+```js
+getYear(buddhistDate)
+// RangeError: daymath: date must use the ISO 8601 calendar, not "buddhist"
+//             (convert with withCalendar('iso8601'))
+
+format(buddhistDate.withCalendar('iso8601'))   // '2026-01-31'
+```
+
+`[u-ca=iso8601]` is the one annotation daymath accepts, and it drops it. Temporal writes it
+itself for `toString({ calendarName: 'always' })`, and it names the very calendar daymath
+reads, so refusing your own round-trip would be arbitrary.
+
+```js
+const written = plainDate.toString({ calendarName: 'always' })  // '2026-01-31[u-ca=iso8601]'
+getYear(written)                                                // 2026
+```
+
+A calendar is refused where it is **applied**. On a day string it is, and with a `[Zone]`
+bracket it is, because the fields get renumbered. Without a bracket the string names an
+`Instant`, which has no year, month or day for a calendar to renumber, so the annotation is
+inert and `day()` answers:
+
+```js
+day('2026-08-08T20:00:00Z[u-ca=buddhist]')                    // '2026-08-08'
+day('2026-08-08T12:00[America/New_York][u-ca=buddhist]')      // throws
+```
+
+Accepting `buddhist` and `roc` is planned; see `FUTURE.md` for the rule that would allow it.
+
+Error messages quote no Temporal text, because implementations word the same failure
+differently. The original error is on `cause`.
+
+Behaviour is checked against a recorded baseline on Node, Deno (which ships **native**
+Temporal) and Bun — every export, `npm run test:runtimes`. The exact call count lives
+in `scripts/cross-runtime.baseline.json`, which is the only place it cannot go stale.
+
+## Requirements
+
+ESM only. **Node 20.19+, or 22.12+.**
+
+That floor is `require()`, not `import`. Node's `require(esm)` landed in 20.19 and 22.12, so
+those are the versions where `require('daymath')` works. `engines` states the range exactly,
+including the gap at 22.0–22.11. `temporal-polyfill` is ESM-only too, so a CJS build of daymath
+would not escape this. Bundlers and browsers are unaffected. A Jest consumer needs a
+`transformIgnorePatterns` entry, because Jest does not use Node's resolution.
+
+Node 18 was supported through 0.3.0 and is dropped here. It went end-of-life in April 2025.
 
 ## Types & tests
 
-Plain JS + `index.d.ts` (no compile step). CI runs on Node 18, 20, 22, 24, and 26; the coverage gate runs on 24.
+Plain JS + `index.d.ts` (no compile step). CI runs on Node 20, 22, 24, and 26; the
+coverage gate runs on 26, which is also the version in `.node-version` and the one used
+to publish. The matrix still proves the floor.
 
 ```bash
 npm test

package/index.d.ts

@@ -26,6 +26,31 @@ export type WeekOptions = {
   weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7
 }
 
+/**
+ * The calendar day of a moment, in a zone. The way in.
+ *
+ * Both defaults are stated: the moment is now, the zone is UTC. A number is
+ * read as epoch **milliseconds**, exactly as `new Date(n)` reads it. An ISO day
+ * string is already a day, so a zone does not apply to it. An ISO timestamp
+ * carrying `Z` or an offset names an exact instant, so it is read as a moment.
+ *
+ * A string carrying a `[Zone]` annotation names its own zone, so it answers its
+ * 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.
+ *
+ * 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
+ * no `:`, or a bare offset — so a timestamp can never be read as a zone.
+ */
+export function day(tz?: string): string
+export function day(
+  moment: Date | number | DayInput | null | undefined,
+  tz?: string,
+): string
+
 /**
  * True for a valid daymath day string / PlainDate.
  * Invalid strings → false. `Date` → throws TypeError (not a quiet false).
@@ -81,11 +106,17 @@ export function endOfWeek(date: DayInput, options?: WeekOptions): string
 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 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 differenceInCalendarQuarters(
+  dateLeft: DayInput,
+  dateRight: DayInput,
+): number
 
 export function isBefore(date: DayInput, dateToCompare: DayInput): boolean
 export function isAfter(date: DayInput, dateToCompare: DayInput): boolean

package/index.js

@@ -1,7 +1,8 @@
-/** 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
+/** daymath — calendar date math (ISO 8601 day). date-fns-shaped. No Date. No time zones. */
+// temporal-polyfill already resolves this: its entry is `globalThis.Temporal ||
+// bundled`, so a runtime with native Temporal gets native. Re-reading
+// globalThis here only duplicated that check and hid where it happens.
+import { Temporal } from 'temporal-polyfill'
 
 /**
  * ISO 8601 calendar day string:
@@ -13,8 +14,73 @@ const Temporal = globalThis.Temporal ?? TemporalPolyfill
  * the epoch). Outside it, Temporal throws and we re-throw with the `daymath:`
  * prefix.
  */
-const ISO_DAY =
-  /^(?:[+-]\d{6}|\d{4})-\d{2}-\d{2}$/
+const ISO_DAY = /^(?:[+-]\d{6}|\d{4})-\d{2}-\d{2}$/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`.
+ *
+ * String operations, not a regex, and the reason is measured. The annotation can
+ * sit behind another one — `'…[America/New_York][u-ca=buddhist]'` — so the head
+ * may itself contain `[`. A pattern that allows that needs `^(.*)\[…\]$`, whose
+ * `.*` backtracks: `'[u-ca='.repeat(64000)` cost 9.0 s, growing with the square
+ * of the input. `lastIndexOf` answers the same question in one pass. CodeQL
+ * `js/polynomial-redos` caught the regex form; timing it confirmed the report.
+ * @param {string} text
+ * @returns {{ head: string, calendar: string } | null}
+ */
+function calendarAnnotation(text) {
+  if (!text.endsWith(']')) return null
+  const open = text.lastIndexOf('[')
+  if (open === -1) return null
+  const inner = text.slice(open + 1, -1)
+  const body = inner.startsWith('!') ? inner.slice(1) : inner
+  if (!body.startsWith('u-ca=')) return null
+  const calendar = body.slice(5)
+  // A `]` inside means the brackets do not nest as they appear, so this is not
+  // an annotation. `'[u-ca=[u-ca=[u-ca=x]]]'` reads as the calendar `x]]` here
+  // and as a malformed day everywhere else, which is what it is.
+  if (calendar === '' || calendar.includes(']')) return null
+  return { head: text.slice(0, open), calendar }
+}
+
+/**
+ * True when the string carries a time-zone annotation, `[Zone]` or `[!Zone]`.
+ * It is the one annotation with no `=`, which separates it from `[u-ca=…]`, and
+ * Temporal writes it first, so only the leading bracket can be one.
+ *
+ * Asking "does the string name a zone?" is a different question from "does it
+ * resolve?". A string can name one and still fail: an offset that disagrees with
+ * the zone, or a misspelled name. Both must be errors, never a silent fallback
+ * to the UTC default.
+ *
+ * String operations again. An unanchored `/\[!?[^\]=]+\]/` restarts at every
+ * position: `'[!'.repeat(64000)` cost 6.8 s, and it is the same defect an
+ * earlier commit removed from the calendar pattern.
+ * @param {string} text
+ */
+function hasZoneAnnotation(text) {
+  const open = text.indexOf('[')
+  if (open === -1) return false
+  const close = text.indexOf(']', open)
+  if (close === -1) return false
+  return !text.slice(open + 1, close).includes('=')
+}
+
+/**
+ * A time zone, by shape: an IANA name, or a bare offset.
+ *
+ * A name is letter-led, slash-separated segments of letters, digits, `_`, `+`,
+ * `-` and `.`. It carries no `:`, which is what keeps an ISO time out. The
+ * `(?![Tt]\d)` guard rejects the compact spelling `T120000Z`, which has no `:`
+ * to catch it. Both matter: `T12:00:00Z` is a zone to native Temporal and not
+ * to temporal-polyfill, so letting either through splits the answer by runtime.
+ *
+ * Verified against every zone this runtime knows: 0 of 418 rejected, plus the
+ * aliases `UTC`, `GMT`, `US/Eastern`, `Asia/Calcutta` and `Etc/GMT+5`.
+ */
+const ZONE_LIKE =
+  /^(?:(?![Tt]\d)[A-Za-z][A-Za-z0-9_+.-]*(?:\/[A-Za-z0-9_+.-]+)*|[+-]\d{2}(?::?\d{2})?)$/u
 
 /** @typedef {string | Temporal.PlainDate} DayInput */
 /**
@@ -31,8 +97,75 @@ const ISO_DAY =
 
 // ─── core conversion ───────────────────────────────────────────────
 
+/**
+ * The bare ISO day inside a string, or `null` if there is not one.
+ *
+ * An annotation is dropped, not judged: `assertIsoCalendar` owns that rule and
+ * runs before both callers, so by here the only calendar left is ISO. Temporal
+ * writes `[u-ca=iso8601]` itself for `toString({ calendarName: 'always' })`, and
+ * it names the very calendar daymath reads, so refusing a caller's own
+ * round-trip would be arbitrary.
+ *
+ * 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.
+ * @param {string} text
+ * @returns {string | null}
+ */
+function bareDay(text) {
+  const annotated = calendarAnnotation(text)
+  const bare = annotated ? annotated.head : text
+  return ISO_DAY.test(bare) ? bare : null
+}
+
+/**
+ * Refuse a non-ISO calendar, wherever the annotation is attached.
+ *
+ * Checked on the *string*, before any parse. Implementations disagree past this
+ * point: native Temporal builds a `[u-ca=buddhist]` ZonedDateTime and the
+ * polyfill refuses to, so parsing first made the error depend on the runtime.
+ * @param {string} text
+ * @param {string} label
+ */
+function assertIsoCalendar(text, label) {
+  const annotated = calendarAnnotation(text)
+  if (annotated && annotated.calendar.toLowerCase() !== 'iso8601') {
+    throw new RangeError(
+      `daymath: ${label} must use the ISO 8601 calendar, not ${JSON.stringify(annotated.calendar)} (convert with withCalendar('iso8601'))`,
+    )
+  }
+}
+
+/**
+ * True for a `Temporal.PlainDate` from *any* implementation: native, the
+ * bundled polyfill, or a second copy of it in the same dependency tree.
+ * `instanceof` recognises only one of those. Every Temporal puts this tag on
+ * `PlainDate.prototype` as a non-writable property, so it is the portable brand.
+ * @param {unknown} value
+ * @returns {value is Temporal.PlainDate} a predicate, so callers narrow
+ */
+function isPlainDate(value) {
+  return Object.prototype.toString.call(value) === '[object Temporal.PlainDate]'
+}
+
 /**
  * Reject Date and non-calendar values. Accept ISO day string or PlainDate.
+ *
+ * A PlainDate becomes its ISO day string first, so every input reaches one
+ * validation path and daymath owns the resulting instance.
+ *
+ * A non-ISO calendar is refused rather than reinterpreted. `toString()` writes
+ * the ISO date then an optional `[u-ca=…]`, so the *day* would survive — but
+ * the field numbers would not. Thai Buddhist years run 543 ahead, so
+ * `2026-01-31[u-ca=buddhist]` is year 2569, and `getYear` would answer `2026`
+ * where the caller's own object says `2569`. A string carrying the annotation is
+ * refused for the same reason, and the error names both the calendar it found
+ * and the way through, `withCalendar('iso8601')`.
+ *
+ * `[u-ca=iso8601]` is the exception: it is accepted and dropped. Temporal writes
+ * it itself for `toString({ calendarName: 'always' })`, and it names the very
+ * calendar daymath reads, so refusing a caller's own round-trip would be
+ * arbitrary.
  * @param {unknown} value
  * @param {string} label
  * @returns {Temporal.PlainDate}
@@ -43,26 +176,28 @@ function toPlainDate(value, label = 'date') {
       `daymath: Date is not allowed for ${label} (pass ISO 8601 day string)`,
     )
   }
-  if (typeof value === 'string') {
-    if (!ISO_DAY.test(value)) {
-      throw new RangeError(
-        `daymath: ${label} must be ISO 8601 day YYYY-MM-DD or ±YYYYYY-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,
-      })
-    }
+  // Named `text`, not `day`: a local `day` would shadow the exported day().
+  const text = isPlainDate(value) ? value.toString() : value
+  if (typeof text !== 'string') {
+    throw new TypeError(
+      `daymath: ${label} must be ISO 8601 day string or Temporal.PlainDate`,
+    )
   }
-  if (value instanceof Temporal.PlainDate) {
-    return value
+  // Before the shape check: an annotated day is well formed, not malformed.
+  assertIsoCalendar(text, label)
+  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)})`,
+    )
+  }
+  try {
+    return Temporal.PlainDate.from(bare)
+  } catch (err) {
+    throw new RangeError(`daymath: invalid ${label} ${JSON.stringify(text)}`, {
+      cause: err,
+    })
   }
-  throw new TypeError(
-    `daymath: ${label} must be ISO 8601 day string or Temporal.PlainDate`,
-  )
 }
 
 /** @param {Temporal.PlainDate} plain @returns {string} */
@@ -82,9 +217,14 @@ function assertFiniteNumber(n, label) {
 
 /**
  * Run a Temporal op and keep the `daymath:` message contract when it fails.
- * Temporal throws bare `Out-of-bounds date` / `Non-positive day`; we prefix and
- * keep the original text plus `cause`. Covers both a result past the range and
- * an argument Temporal refuses outright, hence the neutral wording.
+ * Covers both a result past the range and an argument Temporal refuses
+ * outright, hence the neutral wording.
+ *
+ * The message carries no Temporal text. Implementations word the same failure
+ * differently — the polyfill says `Out-of-bounds date` where native V8 says
+ * `Temporal error: epoch days exceed maximum range.` — so quoting it made
+ * daymath's own message vary by runtime. `cause` still holds the original
+ * error, which is where the detail belongs.
  * @template T
  * @param {string} label
  * @param {() => T} op
@@ -94,10 +234,9 @@ function guardRange(label, op) {
   try {
     return op()
   } catch (err) {
-    throw new RangeError(
-      `daymath: ${label} could not produce a valid date (${/** @type {Error} */ (err).message})`,
-      { cause: err },
-    )
+    throw new RangeError(`daymath: ${label} could not produce a valid date`, {
+      cause: err,
+    })
   }
 }
 
@@ -123,7 +262,7 @@ function assertNonEmptyDates(dates) {
 
 /**
  * @param {WeekOptions} [options]
- * @returns {0|1|2|3|4|5|6}
+ * @returns {0|1|2|3|4|5|6|7} 7 is the default, so 0-6 was never the real range
  */
 function weekStartsOnFrom(options) {
   const w = options?.weekStartsOn ?? 7
@@ -138,7 +277,15 @@ function weekStartsOnFrom(options) {
  * @returns {{ start: Temporal.PlainDate, end: Temporal.PlainDate }}
  */
 function toInterval(interval) {
-  if (interval == null || typeof interval !== 'object') {
+  // `typeof x === 'object'` alone let a Date, an array or a PlainDate through,
+  // and the failure then surfaced as "start must be ISO 8601 day string" —
+  // naming a property the caller never meant to pass.
+  if (
+    interval === null || // typeof null is 'object', so it needs its own test
+    typeof interval !== 'object' || // and this already catches undefined
+    !('start' in interval) ||
+    !('end' in interval)
+  ) {
     throw new TypeError('daymath: interval must be { start, end }')
   }
   const start = toPlainDate(/** @type {Interval} */ (interval).start, 'start')
@@ -146,6 +293,212 @@ function toInterval(interval) {
   return { start, end }
 }
 
+// ─── the clock ─────────────────────────────────────────────────────
+
+/**
+ * The calendar day of a moment, in a zone. The way in.
+ *
+ * Both arguments have a **stated** default: the moment is now, and the zone is
+ * UTC. A default that is written down is not a guess; a default that is assumed
+ * is. UTC is still 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.
+ *
+ * `moment` accepts what the world actually hands you:
+ * - a `Date`, the only carrier of an instant JavaScript has
+ * - a number, read as **epoch milliseconds**, exactly as `new Date(n)` reads it,
+ *   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
+ * - 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
+ *   answers its own civil day and the `tz` default never applies
+ *
+ * `'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 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
+ * the shape is on `ZONE_LIKE`. Temporal's own zone grammar cannot decide the role, because it
+ * accepts a whole timestamp and reads the zone out of it, so
+ * `day('1999-01-01T00:00:00Z')` would answer today. The grammar also differs
+ * between implementations: `'2026-08-08T25:00:00Z'` and `'T12:00:00Z'` are both
+ * zones to native Temporal and neither is one to `temporal-polyfill`. Shape
+ * settles the role and the runtime split together.
+ *
+ * With `day()` this is the only export that reads a clock, so the only one
+ * whose answer depends on when you call it. Give it a moment and it becomes a
+ * pure function, which is how the cross-runtime battery covers it.
+ *
+ * @param {Date | number | DayInput | null} [moment] instant, epoch ms, day, or a zone
+ * @param {string} [tz] IANA time zone id, e.g. `'utc'`, `'Asia/Tokyo'`
+ * @returns {string} `YYYY-MM-DD`
+ * @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(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'
+ */
+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 isMoment = isDay || moment instanceof Date || typeof moment === 'number'
+
+  let zone = tz
+  /** @type {Temporal.Instant | undefined} */
+  let instant
+  /** @type {Temporal.ZonedDateTime | undefined} */
+  let zoned
+  if (!isMoment && moment !== undefined && moment !== null) {
+    if (typeof moment !== 'string') {
+      throw new TypeError(
+        'daymath: day() takes a Date, epoch milliseconds, or an ISO 8601 day',
+      )
+    }
+    // A `[Zone]` annotation makes the string a ZonedDateTime, and Temporal will
+    // not build one without it: a bare offset is refused. So the bracket is the
+    // caller naming a zone, and the string carries its own civil day. Reading
+    // the instant instead and applying UTC would move a browser's date by one.
+    //
+    // Naming a zone and resolving as one are different questions, so the
+    // annotation is detected first. A string can name a zone and still fail:
+    // `'…-05:00[America/New_York]'` has an offset the zone contradicts, and
+    // `'…[Asia/Tokoy]'` is a typo. Falling back to the instant would answer a
+    // UTC day for both, silently, which is the defect this branch exists to fix.
+    if (hasZoneAnnotation(moment)) {
+      // A calendar is refused only where it is applied. With a zone bracket it
+      // is: the fields get renumbered, and `toPlainDate()` carries the
+      // annotation into daymath's own output. Refused on the string, before the
+      // parse, because native Temporal builds a `[u-ca=buddhist]` ZonedDateTime
+      // and the polyfill refuses to — judging after the parse would make the
+      // message depend on the runtime.
+      assertIsoCalendar(moment, 'date')
+      if (tz !== undefined && tz !== null) {
+        throw new TypeError(
+          `daymath: day() got two time zones, ${JSON.stringify(moment)} and ${JSON.stringify(tz)}`,
+        )
+      }
+      try {
+        zoned = Temporal.ZonedDateTime.from(moment)
+      } catch (err) {
+        throw new RangeError(
+          `daymath: day() could not read ${JSON.stringify(moment)} in the time zone it names`,
+          { cause: err },
+        )
+      }
+    } else {
+      try {
+        // A timestamp carrying `Z` or an offset names an exact instant, so it
+        // reads as a moment. Temporal's own grammar is the definition of that.
+        //
+        // A calendar annotation here is inert and is ignored. An Instant has no
+        // year, month or day for a calendar to renumber, and without a zone
+        // bracket Temporal will not build anything that does. Refusing it would
+        // reject a right answer for a reason that cannot apply.
+        instant = Temporal.Instant.from(moment)
+      } catch {
+        // Not a moment, so the string must be a zone — decided by shape, before
+        // Temporal sees it. Temporal's zone grammar also accepts a whole
+        // timestamp and pulls the zone out of it, so letting it decide the role
+        // would read a date as a zone and silently answer today.
+        if (!ZONE_LIKE.test(moment)) {
+          throw new RangeError(
+            `daymath: day() got ${JSON.stringify(moment)}, which is neither a moment nor a time zone`,
+          )
+        }
+        if (tz !== undefined && tz !== null) {
+          throw new TypeError(
+            `daymath: day() got two time zones, ${JSON.stringify(moment)} and ${JSON.stringify(tz)}`,
+          )
+        }
+        zone = moment
+      }
+    }
+  }
+  zone ??= 'utc'
+
+  if (moment instanceof Date && Number.isNaN(moment.getTime())) {
+    throw new RangeError('daymath: day() got an Invalid Date')
+  }
+  if (typeof moment === 'number' && !Number.isFinite(moment)) {
+    throw new RangeError(`daymath: day() got a non-finite time value ${moment}`)
+  }
+
+  // Shape first, because implementations disagree past this point. The reasons
+  // are on ZONE_LIKE. The typeof test comes first because `.test()` coerces,
+  // and a caller-supplied toString could throw an error that is not ours.
+  if (typeof zone !== 'string' || !ZONE_LIKE.test(zone)) {
+    throw new RangeError(
+      `daymath: day() got an unknown time zone ${JSON.stringify(zone)}`,
+    )
+  }
+
+  // Checked before anything returns, so a mistyped zone fails the same way
+  // whatever the moment is. A caller mapping rows that are sometimes a Date and
+  // sometimes a day string would otherwise see the typo only on some rows.
+  //
+  // `ZonedDateTime.from` accepts exactly what `Temporal.Now` accepts and reads
+  // no clock, so a day input stays a pure function.
+  try {
+    Temporal.ZonedDateTime.from({ timeZone: zone, year: 1970, month: 1, day: 1 })
+  } catch (err) {
+    throw new RangeError(
+      `daymath: day() got an unknown time zone ${JSON.stringify(zone)}`,
+      { cause: err },
+    )
+  }
+
+  // A day carries no time, so a zone has nothing to shift. Applying one would
+  // invent a moment the caller never gave.
+  if (isDay) return toDayString(toPlainDate(moment))
+
+  // 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.
+  //
+  // The result still goes through `toPlainDate`. A ZonedDateTime keeps a
+  // `[u-ca=…]` annotation, and `PlainDate.toString()` writes it back out, so
+  // returning directly emitted `'2026-08-08[u-ca=buddhist]'` — a value daymath
+  // itself refuses. Every path adjudicates the calendar in one place or none.
+  if (zoned !== undefined) {
+    const plain = guardRange('day', () => zoned.toPlainDate())
+    return toDayString(toPlainDate(plain))
+  }
+
+  if (instant !== undefined) {
+    return guardRange('day', () =>
+      instant.toZonedDateTimeISO(zone).toPlainDate().toString(),
+    )
+  }
+
+  if (!isMoment) return Temporal.Now.plainDateISO(zone).toString()
+
+  // Truncate, because `new Date(n)` truncates, and the contract here is that a
+  // number reads exactly as it does. Verified equal on positive and negative
+  // fractions. Sub-millisecond precision cannot change a calendar day anyway.
+  // Every other shape returned above, so only a number or a Date reaches here.
+  // The cast says what the control flow already guarantees but tsc cannot see.
+  const epochMs =
+    typeof moment === 'number'
+      ? Math.trunc(moment)
+      : /** @type {Date} */ (moment).getTime()
+  return guardRange('day', () =>
+    Temporal.Instant.fromEpochMilliseconds(epochMs)
+      .toZonedDateTimeISO(zone)
+      .toPlainDate()
+      .toString(),
+  )
+}
+
 // ─── parse / format / valid ────────────────────────────────────────
 
 /**
@@ -608,9 +961,7 @@ export function differenceInQuarters(dateLeft, dateRight) {
 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))
-  )
+  return (left.year - right.year) * 4 + (getQuarter(left) - getQuarter(right))
 }
 
 // ─── compare / equal ───────────────────────────────────────────────
@@ -672,9 +1023,9 @@ export function isSameWeek(dateLeft, dateRight, options) {
   const right = toPlainDate(dateRight, 'dateRight')
   // own guard, so a week start below the minimum does not say startOfWeek
   return guardRange('isSameWeek', () =>
-    left.subtract({ days: daysIntoWeek(left, options) }).equals(
-      right.subtract({ days: daysIntoWeek(right, options) }),
-    ),
+    left
+      .subtract({ days: daysIntoWeek(left, options) })
+      .equals(right.subtract({ days: daysIntoWeek(right, options) })),
   )
 }
 
@@ -894,8 +1245,7 @@ export function isWithinInterval(date, interval) {
     throw new RangeError('daymath: interval start must not be after end')
   }
   return (
-    Temporal.PlainDate.compare(d, start) >= 0 &&
-    Temporal.PlainDate.compare(d, end) <= 0
+    Temporal.PlainDate.compare(d, start) >= 0 && Temporal.PlainDate.compare(d, end) <= 0
   )
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "daymath",
-  "version": "0.3.0",
-  "description": "Calendar date math (ISO 8601 day / PlainDate). date-fns-shaped. No time zones.",
+  "version": "0.4.0",
+  "description": "Calendar date math (ISO 8601 day / PlainDate). date-fns-shaped. No Date. No time zones.",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",
@@ -18,21 +18,29 @@
   ],
   "scripts": {
     "test": "node --test test.js",
+    "lint": "oxlint -c oxlint.jsonc",
+    "lint:fix": "oxlint -c oxlint.jsonc --fix",
+    "typecheck": "tsc -p tsconfig.json",
+    "format": "oxfmt -c oxfmt.json index.js index.d.ts test.js scripts examples",
+    "format:check": "oxfmt -c oxfmt.json --check index.js index.d.ts test.js scripts examples",
     "test:coverage": "c8 --include=index.js --check-coverage --lines 100 --functions 100 --branches 100 --reporter=text --reporter=lcov node --test test.js",
     "test:differential": "node scripts/differential.mjs",
     "test:differential:quick": "node scripts/differential.mjs 2020 2030",
+    "test:runtimes": "node scripts/cross-runtime.mjs",
+    "test:runtimes:write": "node scripts/cross-runtime.mjs --write",
     "prepublishOnly": "npm run test:coverage",
     "publish:github": "node scripts/publish-github-packages.mjs"
   },
   "keywords": [
     "date",
     "calendar",
+    "civil-date",
     "plain-date",
-    "temporal",
-    "date-fns",
     "YYYY-MM-DD",
     "ISO-8601",
-    "PlainDate"
+    "Temporal",
+    "PlainDate",
+    "date-fns"
   ],
   "author": "leemr",
   "license": "MIT",
@@ -49,10 +57,13 @@
     "temporal-polyfill": "^1.0.3"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20.19.0 <21 || >=22.12.0"
   },
   "devDependencies": {
     "c8": "^12.0.0",
-    "date-fns": "4.4.0"
+    "date-fns": "4.4.0",
+    "oxfmt": "0.62.0",
+    "oxlint": "1.77.0",
+    "typescript": "7.0.2"
   }
 }