Introduction

zdate is an immutable TypeScript date/time system with its own model: one nanosecond epoch identity, projected views, strict parsing, and 18 calendar engines. It is not a wrapper around Date or Temporal. Its complexity lives beneath a small ergonomic API built from composable operations.

A ZDate is an instant. The instant is stored once, as epoch nanoseconds in a bigint. Everything else — the year in a calendar, the hour in a time zone, a localized month name — is a view projected from that identity on demand. Views never change the instant; the instant never depends on a view.

import {zdate} from '@sajajs/zdate'

const d = zdate('2024-01-15T12:00:00-05:00[America/New_York]')

d.epoch          // 1705338000000000000n — the identity
d.utc.hour       // 17 — a view
d.local.hour     // hour in your zone — another view
d.with({calendar: 'hebrew'}).local.year   // 5784 — still the same instant

Six Verbs

The ZDate API is six verbs: with, format, compare, by, to, and diff. They compose with a small set of supporting types — durations, intervals, date-only and time-only values — instead of expanding into a separate class for every date-shaped concept. The API is smaller because the model carries more of the work.

Origin

I needed zdate's capabilities long before it was zdate — back then it was a date util folder. I eventually formed a vision, believed I was on to something, and ran with it. If Temporal had been available, I might never have created zdate. The wait was a blessing in disguise; without it I would never have discovered zdate and the great moments that came with it.

Read more in Why zdate.

Design Goals

• One identity. An instant is epoch nanoseconds; nothing else carries identity.
• Deterministic semantics. Parsing has one behavior, with no modes or options. Input that cannot identify one instant is rejected, and repair is an explicit, visible operation.
• Everything in scope. Parsing machine formats, natural dates, pattern formatting, time zones, DST, and calendars are part of the library's contract, not left to the platform.
• A small surface. Six verbs and a handful of types cover daily work; depth stays inside the engine.

These goals constrain one another. Improving one at the expense of another is not a win.

Read more about zdate's architecture.