daymath 0.2.3 → 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.”
+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,16 @@ 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`.
 
 ## date-fns parity (names, not `Date`)
 
@@ -57,13 +126,15 @@ node examples/basic.mjs   # from a clone
 | Values | ISO day **strings**, not `Date` |
 | `isSameDay` | Alias of `isEqual` |
 | `isValid` | Valid daymath day; **`Date` throws** |
-| `getMonth` / `setMonth` | **0–11** (0 = January) |
-| `getDay` | **0–6** (0 = Sunday) |
-| `weekStartsOn` | default `0` (Sunday) |
+| `getMonth` / `setMonth` | **1–12** (1 = January) — ISO, **not** date-fns |
+| `getDay` | **1–7** (1 = Monday, 7 = Sunday) — ISO, **not** date-fns |
+| `weekStartsOn` | default `7` (Sunday); `0` also accepted |
 | Intervals | `{ start, end }` |
 
 ## API
 
+**Start here** — `day`  
+
 **Parse** — `parse` · `format` · `isValid`  
 
 **Add/sub** — Days · Weeks · Months · Years · Quarters  
@@ -84,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, and 22.
+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

@@ -4,6 +4,9 @@ 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`)
+ *
+ * Usable range is the Temporal `PlainDate` range `-271821-04-19` …
+ * `+275760-09-13`; a day outside it throws a `RangeError`.
  * `Date` is rejected at runtime (TypeError).
  */
 export type DayInput = string | Temporal.PlainDate
@@ -15,12 +18,39 @@ export type Interval = {
 }
 
 /**
- * Week options. `weekStartsOn`: 0 = Sunday … 6 = Saturday (date-fns default 0).
+ * Week options. `weekStartsOn`: ISO 1 = Monday … 7 = Sunday (default 7).
+ * `0` is also accepted for Sunday — 0 ≡ 7 (mod 7), so pre-0.3.0 callers keep
+ * working with no change in behaviour.
  */
 export type WeekOptions = {
-  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6
+  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).
@@ -46,11 +76,11 @@ export function subQuarters(date: DayInput, amount: number): string
 
 /** Full year number. */
 export function getYear(date: DayInput): number
-/** Month index like Date/date-fns: 0 = January … 11 = December. */
+/** Month number, ISO 8601: 1 = January … 12 = December. Not date-fns's 0-based index. */
 export function getMonth(date: DayInput): number
 /** Day of month 1…31. */
 export function getDate(date: DayInput): number
-/** Weekday like Date/date-fns: 0 = Sunday … 6 = Saturday. */
+/** Weekday, ISO 8601: 1 = Monday … 7 = Sunday. Only Sunday differs from date-fns. */
 export function getDay(date: DayInput): number
 export function getDayOfYear(date: DayInput): number
 export function getDaysInMonth(date: DayInput): number
@@ -59,7 +89,7 @@ export function getQuarter(date: DayInput): number
 export function isLeapYear(date: DayInput): boolean
 
 export function setYear(date: DayInput, year: number): string
-/** `month`: 0 = January … 11 = December (date-fns). */
+/** `month`: 1 = January … 12 = December (ISO 8601). */
 export function setMonth(date: DayInput, month: number): string
 export function setDate(date: DayInput, dayOfMonth: number): string
 
@@ -76,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