Method-style extensions for the Temporal API. Based on Day.js syntax.
Docs · What this is · Usage · Contract · Development · Plan
Temporal fixes JavaScript dates: separate types for dates, time and
an instant, real time zones, immutability. What it lacks is the dayjs reading
order — dayjs(a).isBefore(b) reads like a sentence left to right; Temporal.PlainDate.compare(a, b) < 0
does not. Chronos is a static wrapper to improve readability:
Chronos(today).isBefore(deadline);Chronos is not a date library, and does not want to become one. Temporal is the date library. Chronos is a few dozen small functions that make Temporal read better.
Copy what you need. Every helper is a few lines over a native Temporal call. If you want three of them, lift those three into your project.
Note
The API below is the target in docs/plan.md, not
yet what src exports.
import { Chronos } from "chronos-temporal";
const today = Temporal.Now.plainDateISO();
Chronos(today).isBefore(deadline); // deadline is a plain Temporal.PlainDate
Chronos(today).isSame(deadline, "month");
Chronos(today).isBetween(start, end, { inclusive: true });
Chronos(today).startOf("month").add({ days: 14 }); // returns Temporal: native chain continues
const date = Chronos.parse("06.10.2026", Temporal.PlainDate, "DD.MM.YYYY"); // strict ISO by default
Chronos(date).format("DD.MM.YYYY"); // same tokens as parse
Chronos(date).fromNow(); // "vor 3 Tagen"; de-AT unless given a localeUnits follow the receiver. A PlainDate takes year, month, week, day; an
Instant takes time units only. TypeScript rejects the rest.
Where Temporal already reads well, Chronos stays out of the way: add,
subtract and ISO parsing are plain Temporal.
A global Temporal. Node 26, Chrome and Edge 144+ and Firefox 139+ ship it.
Safari does not yet. Until it does, load a polyfill once at your entry point:
import "temporal-polyfill/global";Chronos(x) lives for one expression. These rules keep it from becoming dayjs:
- Only the receiver is wrapped. Arguments are raw Temporal values.
- Anything that yields a date yields raw Temporal, never a
Chronos. - No strings or epoch numbers stand in for dates. Parse first, then call.
Chronosnever appears in a signature, a prop, stored state or JSON.- No built-in prototype is touched.
Removing Chronos from a project should mean rewriting call sites, never data flow.
Built with Vite+: tsdown packs, Vitest tests, Oxlint and Oxfmt check.
vp install
# Tests, once or watching
vp test
vp test --watch
# Format, lint and type check; then fix what can be fixed
vp check
vp check --fix
# Docs site, live or built to docs/.vitepress/dist
vp run docs:dev
vp run docs:build
# Release: bump the version, tag and push; the Release workflow publishes
vp run release
# Build dist/
vp packMIT © Leah Grones