daymath 0.0.1 → 0.1.0

package/README.md

@@ -1,18 +1,63 @@
 # daymath
 
-Calendar date math (`YYYY-MM-DD` / plain dates). date-fns-shaped. No time zones.
+Calendar date math for `YYYY-MM-DD` strings. **date-fns-shaped** names. **Temporal.PlainDate** under the hood.
 
-**Status:** name reserved. API not shipped yet.
+No `Date`. No time zones. No silent “local now.”
 
 ```bash
 npm install daymath
 ```
 
-## Planned
+## Why
 
-- String-first date math (add/sub days, diffs, compare)
-- Temporal.PlainDate under the hood
-- No `Date`, no silent local-now surprises
+`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,
+  parse,
+} from 'daymath'
+
+addDays('2026-08-06', 1)           // '2026-08-07'
+addMonths('2026-01-31', 1)         // '2026-02-28' (constrain)
+differenceInDays('2026-08-06', '2026-08-01') // 5
+isBefore('2026-08-05', '2026-08-06') // true
+parse('2026-08-06')                // '2026-08-06'
+```
+
+Inputs: `YYYY-MM-DD` string or `Temporal.PlainDate`.  
+Outputs: always `YYYY-MM-DD` string (for math helpers).
+
+`Date` throws. Time-bearing ISO strings throw. Sloppy forms like `2026-8-6` throw.
+
+## API
+
+| Function | Notes |
+|----------|--------|
+| `parse` / `format` / `isValid` | Strict `YYYY-MM-DD` |
+| `addDays` / `subDays` | |
+| `addWeeks` / `subWeeks` | |
+| `addMonths` / `subMonths` | Calendar months; end-of-month constrains |
+| `addYears` / `subYears` | Leap day constrains |
+| `differenceInDays` | `dateLeft − dateRight` (date-fns order) |
+| `isBefore` / `isAfter` / `isEqual` | |
+| `compareAsc` / `compareDesc` | For `.sort()` |
+| `min` / `max` | Non-empty arrays |
+
+Amounts must be finite integers.
+
+## Temporal
+
+Uses global `Temporal` when present; otherwise [`temporal-polyfill`](https://www.npmjs.com/package/temporal-polyfill).
+
+## Types
+
+Ships `index.d.ts` (no TypeScript compile step for authors). Source is plain JS.
 
 ## License
 

package/index.d.ts

@@ -0,0 +1,37 @@
+import type { Temporal } from 'temporal-polyfill'
+
+/**
+ * Calendar day input: `YYYY-MM-DD` string, or a Temporal.PlainDate.
+ * `Date` is rejected at runtime.
+ */
+export type DayInput = string | Temporal.PlainDate
+
+export function isValid(value: unknown): boolean
+
+/** Validate / normalize to `YYYY-MM-DD`. */
+export function parse(date: DayInput): string
+
+/** Format as `YYYY-MM-DD` (only pattern supported). */
+export function format(date: DayInput, pattern?: 'yyyy-MM-dd' | 'YYYY-MM-DD'): string
+
+export function addDays(date: DayInput, amount: number): string
+export function subDays(date: DayInput, amount: number): string
+export function addWeeks(date: DayInput, amount: number): string
+export function subWeeks(date: DayInput, amount: number): string
+export function addMonths(date: DayInput, amount: number): string
+export function subMonths(date: DayInput, amount: number): string
+export function addYears(date: DayInput, amount: number): string
+export function subYears(date: DayInput, amount: number): string
+
+/** Full days: `dateLeft − dateRight` (date-fns argument order). */
+export function differenceInDays(dateLeft: DayInput, dateRight: DayInput): number
+
+export function isBefore(date: DayInput, dateToCompare: DayInput): boolean
+export function isAfter(date: DayInput, dateToCompare: DayInput): boolean
+export function isEqual(dateLeft: DayInput, dateRight: DayInput): boolean
+
+export function compareAsc(dateLeft: DayInput, dateRight: DayInput): -1 | 0 | 1
+export function compareDesc(dateLeft: DayInput, dateRight: DayInput): -1 | 0 | 1
+
+export function min(dates: DayInput[]): string
+export function max(dates: DayInput[]): string

package/index.js

@@ -1,4 +1,277 @@
-/** daymath — reserved. Real API coming. */
-export function addDays(date, days) {
-  throw new Error('daymath: not implemented yet (name reserved).')
+/** daymath — calendar date math (YYYY-MM-DD). date-fns-shaped. No Date / time zones. */
+import { Temporal as TemporalPolyfill } from 'temporal-polyfill'
+
+const Temporal = globalThis.Temporal ?? TemporalPolyfill
+
+/** @typedef {string | Temporal.PlainDate} DayInput */
+
+/**
+ * Reject Date and non-calendar values. Accept YYYY-MM-DD string or PlainDate.
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {Temporal.PlainDate}
+ */
+function toPlainDate(value, label = 'date') {
+  if (value instanceof Date) {
+    throw new TypeError(
+      `daymath: Date is not allowed for ${label} (pass YYYY-MM-DD string)`,
+    )
+  }
+  if (typeof value === 'string') {
+    // Strict calendar day: no time, no offset, no week dates.
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+      throw new RangeError(
+        `daymath: ${label} must be YYYY-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,
+      })
+    }
+  }
+  if (value instanceof Temporal.PlainDate) {
+    return value
+  }
+  throw new TypeError(
+    `daymath: ${label} must be YYYY-MM-DD string or Temporal.PlainDate`,
+  )
+}
+
+/** @param {Temporal.PlainDate} plain @returns {string} */
+function toDayString(plain) {
+  return plain.toString()
+}
+
+/** @param {unknown} value */
+export function isValid(value) {
+  try {
+    toPlainDate(value)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Validate / normalize a calendar day string.
+ * @param {DayInput} date
+ * @returns {string}
+ */
+export function parse(date) {
+  return toDayString(toPlainDate(date))
+}
+
+/**
+ * Format as YYYY-MM-DD (only supported pattern for now).
+ * @param {DayInput} date
+ * @param {string} [pattern='yyyy-MM-dd']
+ * @returns {string}
+ */
+export function format(date, pattern = 'yyyy-MM-dd') {
+  if (pattern !== 'yyyy-MM-dd' && pattern !== 'YYYY-MM-DD') {
+    throw new RangeError(
+      `daymath: only "yyyy-MM-dd" format is supported (got ${JSON.stringify(pattern)})`,
+    )
+  }
+  return toDayString(toPlainDate(date))
+}
+
+/**
+ * @param {DayInput} date
+ * @param {number} amount
+ * @returns {string}
+ */
+export function addDays(date, amount) {
+  assertFiniteNumber(amount, 'amount')
+  return toDayString(toPlainDate(date).add({ days: amount }))
+}
+
+/**
+ * @param {DayInput} date
+ * @param {number} amount
+ * @returns {string}
+ */
+export function subDays(date, amount) {
+  assertFiniteNumber(amount, 'amount')
+  return addDays(date, -amount)
+}
+
+/**
+ * @param {DayInput} date
+ * @param {number} amount
+ * @returns {string}
+ */
+export function addWeeks(date, amount) {
+  assertFiniteNumber(amount, 'amount')
+  return addDays(date, amount * 7)
+}
+
+/**
+ * @param {DayInput} date
+ * @param {number} amount
+ * @returns {string}
+ */
+export function subWeeks(date, amount) {
+  assertFiniteNumber(amount, 'amount')
+  return addWeeks(date, -amount)
+}
+
+/**
+ * Calendar months (Temporal overflow: constrain — e.g. Jan 31 + 1 month → Feb 28/29).
+ * @param {DayInput} date
+ * @param {number} amount
+ * @returns {string}
+ */
+export function addMonths(date, amount) {
+  assertFiniteNumber(amount, 'amount')
+  return toDayString(toPlainDate(date).add({ months: amount }))
+}
+
+/**
+ * @param {DayInput} date
+ * @param {number} amount
+ * @returns {string}
+ */
+export function subMonths(date, amount) {
+  assertFiniteNumber(amount, 'amount')
+  return addMonths(date, -amount)
+}
+
+/**
+ * @param {DayInput} date
+ * @param {number} amount
+ * @returns {string}
+ */
+export function addYears(date, amount) {
+  assertFiniteNumber(amount, 'amount')
+  return toDayString(toPlainDate(date).add({ years: amount }))
+}
+
+/**
+ * @param {DayInput} date
+ * @param {number} amount
+ * @returns {string}
+ */
+export function subYears(date, amount) {
+  assertFiniteNumber(amount, 'amount')
+  return addYears(date, -amount)
+}
+
+/**
+ * Full calendar days: dateLeft − dateRight (date-fns order).
+ * @param {DayInput} dateLeft
+ * @param {DayInput} dateRight
+ * @returns {number}
+ */
+export function differenceInDays(dateLeft, dateRight) {
+  const left = toPlainDate(dateLeft, 'dateLeft')
+  const right = toPlainDate(dateRight, 'dateRight')
+  return left.since(right, { largestUnit: 'day' }).days
+}
+
+/**
+ * @param {DayInput} date
+ * @param {DayInput} dateToCompare
+ * @returns {boolean}
+ */
+export function isBefore(date, dateToCompare) {
+  return (
+    Temporal.PlainDate.compare(
+      toPlainDate(date),
+      toPlainDate(dateToCompare, 'dateToCompare'),
+    ) < 0
+  )
+}
+
+/**
+ * @param {DayInput} date
+ * @param {DayInput} dateToCompare
+ * @returns {boolean}
+ */
+export function isAfter(date, dateToCompare) {
+  return (
+    Temporal.PlainDate.compare(
+      toPlainDate(date),
+      toPlainDate(dateToCompare, 'dateToCompare'),
+    ) > 0
+  )
+}
+
+/**
+ * @param {DayInput} dateLeft
+ * @param {DayInput} dateRight
+ * @returns {boolean}
+ */
+export function isEqual(dateLeft, dateRight) {
+  return (
+    Temporal.PlainDate.compare(
+      toPlainDate(dateLeft, 'dateLeft'),
+      toPlainDate(dateRight, 'dateRight'),
+    ) === 0
+  )
+}
+
+/**
+ * @param {DayInput} dateLeft
+ * @param {DayInput} dateRight
+ * @returns {-1 | 0 | 1}
+ */
+export function compareAsc(dateLeft, dateRight) {
+  return /** @type {-1 | 0 | 1} */ (
+    Temporal.PlainDate.compare(
+      toPlainDate(dateLeft, 'dateLeft'),
+      toPlainDate(dateRight, 'dateRight'),
+    )
+  )
+}
+
+/**
+ * @param {DayInput} dateLeft
+ * @param {DayInput} dateRight
+ * @returns {-1 | 0 | 1}
+ */
+export function compareDesc(dateLeft, dateRight) {
+  return /** @type {-1 | 0 | 1} */ (-compareAsc(dateLeft, dateRight))
+}
+
+/**
+ * @param {DayInput[]} dates
+ * @returns {string}
+ */
+export function min(dates) {
+  assertNonEmptyDates(dates)
+  return toDayString(
+    dates.map((d) => toPlainDate(d)).reduce((a, b) => (Temporal.PlainDate.compare(a, b) <= 0 ? a : b)),
+  )
+}
+
+/**
+ * @param {DayInput[]} dates
+ * @returns {string}
+ */
+export function max(dates) {
+  assertNonEmptyDates(dates)
+  return toDayString(
+    dates.map((d) => toPlainDate(d)).reduce((a, b) => (Temporal.PlainDate.compare(a, b) >= 0 ? a : b)),
+  )
+}
+
+/** @param {unknown} n @param {string} label */
+function assertFiniteNumber(n, label) {
+  if (typeof n !== 'number' || !Number.isFinite(n)) {
+    throw new TypeError(`daymath: ${label} must be a finite number`)
+  }
+  if (!Number.isInteger(n)) {
+    throw new RangeError(`daymath: ${label} must be an integer`)
+  }
+}
+
+/** @param {unknown} dates */
+function assertNonEmptyDates(dates) {
+  if (!Array.isArray(dates) || dates.length === 0) {
+    throw new RangeError('daymath: expected a non-empty array of dates')
+  }
 }

package/package.json

@@ -1,22 +1,32 @@
 {
   "name": "daymath",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Calendar date math (YYYY-MM-DD / PlainDate). date-fns-shaped. No time zones.",
   "type": "module",
   "main": "./index.js",
+  "types": "./index.d.ts",
   "exports": {
-    ".": "./index.js"
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
   },
   "files": [
     "index.js",
+    "index.d.ts",
     "README.md"
   ],
+  "scripts": {
+    "test": "node --test test.js",
+    "prepublishOnly": "npm test"
+  },
   "keywords": [
     "date",
     "calendar",
     "plain-date",
     "temporal",
-    "date-fns"
+    "date-fns",
+    "YYYY-MM-DD"
   ],
   "author": "leemr",
   "license": "MIT",
@@ -27,5 +37,11 @@
   "bugs": {
     "url": "https://github.com/leemr/daymath/issues"
   },
-  "homepage": "https://github.com/leemr/daymath#readme"
+  "homepage": "https://github.com/leemr/daymath#readme",
+  "dependencies": {
+    "temporal-polyfill": "^1.0.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
 }