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 ❤️
Play → · npm · Changelog · Contributing · FUTURE
npm install daymathSame code also publishes to GitHub Packages as @leemr/daymath (scoped; see GitHub npm registry docs):
# one-time: map the scope (auth with a PAT that has read:packages, or GITHUB_TOKEN in Actions)
echo '@leemr:registry=https://npm.pkg.github.com' >> .npmrc
npm install @leemr/daymathMost people should keep using daymath on npmjs.
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
isSameDay('2026-08-06', '2026-08-06') // truenode examples/basic.mjs # from a cloneDate 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 (including isValid). isValid('asdf') → false.
Range: -271821-04-19 … +275760-09-13 — the Temporal.PlainDate limit, roughly ±10⁸ days from the epoch. A day outside it throws a RangeError.
| Topic | daymath |
|---|---|
| Values | ISO day strings, not Date |
isSameDay |
Alias of isEqual |
isValid |
Valid daymath day; Date throws |
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 } |
Parse — parse · format · isValid
Add/sub — Days · Weeks · Months · Years · Quarters
Get/set — getYear · getMonth · getDate · getDay · getDayOfYear · getDaysInMonth · getQuarter · isLeapYear · setYear · setMonth · setDate
Bounds — startOf/endOf Month · Year · Quarter · Week
Diffs — Days · Weeks · Months · CalendarMonths · Years · CalendarYears · Quarters · CalendarQuarters
Compare — isBefore · isAfter · isEqual · isSameDay · isSameWeek · Month · Year · Quarter · compareAsc · compareDesc · min · max
Weekday — isSunday…isSaturday · isWeekend · first/last day of month
Intervals — eachDayOfInterval · eachMonthOfInterval · eachYearOfInterval · isWithinInterval · clamp · areIntervalsOverlapping
Amounts are finite integers.
Uses global Temporal when present; otherwise temporal-polyfill.
Plain JS + index.d.ts (no compile step). CI runs on Node 18, 20, 22, 24, and 26; the coverage gate runs on 24.
npm test
npm run test:coverage # c8: 100% lines/funcs/branches on index.js + lcovCI uploads coverage to Codecov (see CONTRIBUTING.md for one-time app/token setup).
PRs welcome via fork — see CONTRIBUTING.md. Security reports: SECURITY.md.
MIT