daymath 0.2.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # daymath
 
-Calendar date math for **ISO 8601** `YYYY-MM-DD` strings. **date-fns-shaped** names. **Temporal.PlainDate** under the hood.
+Calendar date math for **ISO 8601** day strings. **date-fns-shaped** names. **Temporal.PlainDate** under the hood.
 
 No `Date`. No time zones. No silent “local now.”
 
@@ -31,23 +31,30 @@ 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'
+addDays('9999-12-31', 1)                    // '+010000-01-01' (expanded year)
 eachDayOfInterval({
   start: '2026-08-05',
   end: '2026-08-07',
 }) // ['2026-08-05', '2026-08-06', '2026-08-07']
 ```
 
-**Inputs:** ISO 8601 `YYYY-MM-DD` or `Temporal.PlainDate`.  
-**Outputs:** always `YYYY-MM-DD` string (for math helpers).
+**Inputs:** ISO 8601 day string or `Temporal.PlainDate`.  
+- `YYYY-MM-DD` (years 0000–9999)  
+- expanded `±YYYYYY-MM-DD` (e.g. `+010000-01-01`)  
 
-`Date` throws. Time-bearing strings throw. Sloppy forms like `2026-8-6` throw.
+**Outputs:** Temporal’s ISO day string (same forms).
+
+`Date` throws (including `isValid(date)`). Bad strings: math helpers throw; `isValid('asdf')` → `false`. Time-bearing / sloppy forms throw.
+
+See [FUTURE.md](./FUTURE.md) for backlog (bundle size, business days, …).
 
 ## date-fns parity notes
 
 | Topic | daymath |
 |-------|---------|
-| Value type | `YYYY-MM-DD` string (not `Date`) |
+| Value type | ISO day string (not `Date`) |
 | `isSameDay` | Alias of `isEqual` (same calendar day) |
+| `isValid` | Our predicate: valid day string / PlainDate. `Date` **throws** (not date-fns’s Date check) |
 | `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`) |

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.1",
+  "description": "Calendar date math (ISO 8601 day / PlainDate). date-fns-shaped. No time zones.",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",