daymath 0.2.0 → 0.2.2

package/README.md

@@ -1,95 +1,83 @@
 # daymath
 
-Calendar date math for **ISO 8601** `YYYY-MM-DD` strings. **date-fns-shaped** names. **Temporal.PlainDate** under the hood.
+[![npm](https://img.shields.io/npm/v/daymath.svg)](https://www.npmjs.com/package/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)
+
+**ISO 8601** calendar day math. **date-fns-shaped** names. **Temporal.PlainDate** under the hood.
 
 No `Date`. No time zones. No silent “local now.”
 
+[**Play in the browser →**](https://leemr.github.io/daymath/) · [npm](https://www.npmjs.com/package/daymath) · [FUTURE.md](./FUTURE.md)
+
 ```bash
 npm install daymath
 ```
 
-## Why
-
-`Date` is a timestamp. Calendar work (“add one month”, “days between hire and start”) is not. This package only does plain calendar days.
-
-## Usage
-
 ```js
-import {
-  addDays,
-  addMonths,
-  differenceInDays,
-  isBefore,
-  isSameDay,
-  startOfMonth,
-  eachDayOfInterval,
-} from 'daymath'
-
-addDays('2026-08-06', 1)                    // '2026-08-07'
-addMonths('2026-01-31', 1)                  // '2026-02-28' (constrain)
+import { addDays, addMonths, differenceInDays, isSameDay } from 'daymath'
+
+addDays('2026-08-06', 1)      // '2026-08-07'
+addMonths('2026-01-31', 1)    // '2026-02-28'
 differenceInDays('2026-08-06', '2026-08-01') // 5
-isBefore('2026-08-05', '2026-08-06')         // true
-isSameDay('2026-08-06', '2026-08-06')        // true (alias of isEqual)
-startOfMonth('2026-08-06')                  // '2026-08-01'
-eachDayOfInterval({
-  start: '2026-08-05',
-  end: '2026-08-07',
-}) // ['2026-08-05', '2026-08-06', '2026-08-07']
+isSameDay('2026-08-06', '2026-08-06')        // true
 ```
 
-**Inputs:** ISO 8601 `YYYY-MM-DD` or `Temporal.PlainDate`.  
-**Outputs:** always `YYYY-MM-DD` string (for math helpers).
+## Why
+
+`Date` is a timestamp. Hire dates, passport expiry, trip days are **calendar** values. daymath only does plain days as ISO strings.
+
+| In | Out |
+|----|-----|
+| `YYYY-MM-DD` or expanded `±YYYYYY-MM-DD` | same forms (Temporal `toString`) |
+| or `Temporal.PlainDate` | string |
 
-`Date` throws. Time-bearing strings throw. Sloppy forms like `2026-8-6` throw.
+`Date` **throws** (including `isValid`). `isValid('asdf')` → `false`.
 
-## date-fns parity notes
+## date-fns parity (names, not `Date`)
 
 | Topic | daymath |
 |-------|---------|
-| Value type | `YYYY-MM-DD` string (not `Date`) |
-| `isSameDay` | Alias of `isEqual` (same calendar day) |
-| `getMonth` / `setMonth` | **0–11** like Date/date-fns (0 = January) |
-| `getDay` | **0–6** like Date/date-fns (0 = Sunday) |
-| `weekStartsOn` | `0` = Sunday … `6` = Saturday (default `0`) |
-| Intervals | `{ start, end }` inclusive for `each*` / `isWithin` / `clamp` |
-| `areIntervalsOverlapping` | Default `{ inclusive: false }` (date-fns); pass `true` for closed |
+| 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) |
+| Intervals | `{ start, end }` |
 
-## API (0.2)
+## API
 
-### Parse / format
-`parse` · `format` · `isValid`
+**Parse** — `parse` · `format` · `isValid`  
 
-### Add / sub
-`addDays` / `subDays` · `addWeeks` / `subWeeks` · `addMonths` / `subMonths` · `addYears` / `subYears` · `addQuarters` / `subQuarters`
+**Add/sub** — Days · Weeks · Months · Years · Quarters  
 
-### Get / set
-`getYear` · `getMonth` · `getDate` · `getDay` · `getDayOfYear` · `getDaysInMonth` · `getQuarter` · `isLeapYear`  
-`setYear` · `setMonth` · `setDate`
+**Get/set** — `getYear` · `getMonth` · `getDate` · `getDay` · `getDayOfYear` · `getDaysInMonth` · `getQuarter` · `isLeapYear` · `setYear` · `setMonth` · `setDate`  
 
-### Start / end
-`startOfMonth` / `endOfMonth` · `startOfYear` / `endOfYear` · `startOfQuarter` / `endOfQuarter` · `startOfWeek` / `endOfWeek`
+**Bounds** — `startOf`/`endOf` Month · Year · Quarter · Week  
 
-### Differences
-`differenceInDays` · `differenceInWeeks` · `differenceInMonths` · `differenceInCalendarMonths` · `differenceInYears` · `differenceInCalendarYears` · `differenceInQuarters` · `differenceInCalendarQuarters`
+**Diffs** — Days · Weeks · Months · CalendarMonths · Years · CalendarYears · Quarters · CalendarQuarters  
 
-### Compare
-`isBefore` · `isAfter` · `isEqual` · `isSameDay` · `isSameWeek` · `isSameMonth` · `isSameYear` · `isSameQuarter` · `compareAsc` · `compareDesc` · `min` · `max`
+**Compare** — `isBefore` · `isAfter` · `isEqual` · `isSameDay` · `isSameWeek` · Month · Year · Quarter · `compareAsc` · `compareDesc` · `min` · `max`  
 
-### Weekday / month edges
-`isSunday`…`isSaturday` · `isWeekend` · `isFirstDayOfMonth` · `isLastDayOfMonth`
+**Weekday** — `isSunday`…`isSaturday` · `isWeekend` · first/last day of month  
 
-### Intervals
-`eachDayOfInterval` · `eachMonthOfInterval` · `eachYearOfInterval` · `isWithinInterval` · `clamp` · `areIntervalsOverlapping`
+**Intervals** — `eachDayOfInterval` · `eachMonthOfInterval` · `eachYearOfInterval` · `isWithinInterval` · `clamp` · `areIntervalsOverlapping`
 
-Amounts must be finite integers.
+Amounts are finite integers.
 
 ## Temporal
 
 Uses global `Temporal` when present; otherwise [`temporal-polyfill`](https://www.npmjs.com/package/temporal-polyfill).
 
-## Types
+## Types & tests
 
-Ships `index.d.ts` (no TypeScript compile step). Source is plain JS.
+Plain JS + `index.d.ts` (no compile step).
+
+```bash
+npm test
+npm run test:coverage   # 100% lines on index.js
+```
 
 ## License
 

package/index.d.ts

@@ -1,8 +1,10 @@
 import type { Temporal } from 'temporal-polyfill'
 
 /**
- * Calendar day input: ISO 8601 `YYYY-MM-DD` string, or a Temporal.PlainDate.
- * `Date` is rejected at runtime.
+ * Calendar day input: ISO 8601 day string, or a Temporal.PlainDate.
+ * - `YYYY-MM-DD` (years 0000–9999)
+ * - expanded `±YYYYYY-MM-DD` (e.g. `+010000-01-01`)
+ * `Date` is rejected at runtime (TypeError).
  */
 export type DayInput = string | Temporal.PlainDate
 
@@ -19,12 +21,16 @@ export type WeekOptions = {
   weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6
 }
 
+/**
+ * True for a valid daymath day string / PlainDate.
+ * Invalid strings → false. `Date` → throws TypeError (not a quiet false).
+ */
 export function isValid(value: unknown): boolean
 
-/** Validate / normalize to ISO 8601 `YYYY-MM-DD`. */
+/** Validate / normalize to ISO 8601 day string (Temporal `toString` form). */
 export function parse(date: DayInput): string
 
-/** Format as `YYYY-MM-DD` (only pattern supported). */
+/** Format as ISO day (only `yyyy-MM-dd` / `YYYY-MM-DD` patterns supported). */
 export function format(date: DayInput, pattern?: 'yyyy-MM-dd' | 'YYYY-MM-DD'): string
 
 export function addDays(date: DayInput, amount: number): string

package/index.js

@@ -1,8 +1,16 @@
-/** daymath — calendar date math (YYYY-MM-DD). date-fns-shaped. No Date / time zones. */
+/** daymath — calendar date math (ISO 8601 day). date-fns-shaped. No Date / time zones. */
 import { Temporal as TemporalPolyfill } from 'temporal-polyfill'
 
 const Temporal = globalThis.Temporal ?? TemporalPolyfill
 
+/**
+ * ISO 8601 calendar day string:
+ * - `YYYY-MM-DD` (years 0000–9999)
+ * - expanded `±YYYYYY-MM-DD` (Temporal form, e.g. `+010000-01-01`)
+ */
+const ISO_DAY =
+  /^(?:[+-]\d{6}|\d{4})-\d{2}-\d{2}$/
+
 /** @typedef {string | Temporal.PlainDate} DayInput */
 /**
  * @typedef {object} Interval
@@ -17,7 +25,7 @@ const Temporal = globalThis.Temporal ?? TemporalPolyfill
 // ─── core conversion ───────────────────────────────────────────────
 
 /**
- * Reject Date and non-calendar values. Accept YYYY-MM-DD string or PlainDate.
+ * Reject Date and non-calendar values. Accept ISO day string or PlainDate.
  * @param {unknown} value
  * @param {string} label
  * @returns {Temporal.PlainDate}
@@ -25,14 +33,13 @@ const Temporal = globalThis.Temporal ?? TemporalPolyfill
 function toPlainDate(value, label = 'date') {
   if (value instanceof Date) {
     throw new TypeError(
-      `daymath: Date is not allowed for ${label} (pass YYYY-MM-DD string)`,
+      `daymath: Date is not allowed for ${label} (pass ISO 8601 day string)`,
     )
   }
   if (typeof value === 'string') {
-    // Strict ISO 8601 calendar date: YYYY-MM-DD only.
-    if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    if (!ISO_DAY.test(value)) {
       throw new RangeError(
-        `daymath: ${label} must be YYYY-MM-DD (got ${JSON.stringify(value)})`,
+        `daymath: ${label} must be ISO 8601 day YYYY-MM-DD or ±YYYYYY-MM-DD (got ${JSON.stringify(value)})`,
       )
     }
     try {
@@ -47,7 +54,7 @@ function toPlainDate(value, label = 'date') {
     return value
   }
   throw new TypeError(
-    `daymath: ${label} must be YYYY-MM-DD string or Temporal.PlainDate`,
+    `daymath: ${label} must be ISO 8601 day string or Temporal.PlainDate`,
   )
 }
 
@@ -105,8 +112,17 @@ function toInterval(interval) {
 
 // ─── parse / format / valid ────────────────────────────────────────
 
-/** @param {unknown} value */
+/**
+ * True if value is a valid daymath day (ISO day string or PlainDate).
+ * Invalid strings → false. `Date` → throws (not a quiet false — swap trap).
+ * @param {unknown} value
+ */
 export function isValid(value) {
+  if (value instanceof Date) {
+    throw new TypeError(
+      'daymath: Date is not allowed for isValid (pass ISO 8601 day string)',
+    )
+  }
   try {
     toPlainDate(value)
     return true
@@ -116,7 +132,7 @@ export function isValid(value) {
 }
 
 /**
- * Validate / normalize a calendar day string (ISO 8601 YYYY-MM-DD).
+ * Validate / normalize an ISO 8601 calendar day string.
  * @param {DayInput} date
  * @returns {string}
  */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "daymath",
-  "version": "0.2.0",
-  "description": "Calendar date math (YYYY-MM-DD / PlainDate). date-fns-shaped. No time zones.",
+  "version": "0.2.2",
+  "description": "Calendar date math (ISO 8601 day / PlainDate). date-fns-shaped. No time zones.",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",
@@ -18,8 +18,10 @@
   ],
   "scripts": {
     "test": "node --test test.js",
-    "prepublishOnly": "npm test"
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-include=index.js test.js",
+    "prepublishOnly": "npm run test:coverage"
   },
+
   "keywords": [
     "date",
     "calendar",