Skip to content
lgronesPublic

About

Day.js-style syntactic sugar for the Temporal API

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Chronos

Method-style extensions for the Temporal API. Based on Day.js syntax.

MIT licence TypeScript 7 Vite+ Status: early

Docs · What this is · Usage · Contract · Development · Plan

What this is

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.

Usage

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 locale

Units 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.

Requirements

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";

Contract

Chronos(x) lives for one expression. These rules keep it from becoming dayjs:

  1. Only the receiver is wrapped. Arguments are raw Temporal values.
  2. Anything that yields a date yields raw Temporal, never a Chronos.
  3. No strings or epoch numbers stand in for dates. Parse first, then call.
  4. Chronos never appears in a signature, a prop, stored state or JSON.
  5. No built-in prototype is touched.

Removing Chronos from a project should mean rewriting call sites, never data flow.

Development

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 pack

Licence

MIT © Leah Grones

About

Day.js-style syntactic sugar for the Temporal API

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages