Architecture ​

Correctness is not only handling edge cases. Correctness is whether the model lets ordinary code express the right thing without dragging the entire machinery into the caller’s hands.

One Identity, Projected Views ​

A ZDate stores exactly one thing: epoch nanoseconds in a bigint. Zones, calendars, and locales never touch identity — they are parameters of a ZView, and a view is a lazy, cached projection of the epoch. Two dates are equal when their epochs are equal, no matter what views they were read through. This is the structural fix for the classic bug family where converting, formatting, or comparing quietly changes what instant you hold.

Date had this model too — epoch inside, component getters outside — but froze it at two views (UTC and local), one calendar, millisecond precision, and mutable state. zdate keeps the model and generalizes every axis.

Lazy Resolution ​

Views resolve fields on first read and cache them. Constructing a ZDate does no calendar or zone work; a hot path that only compares epochs never pays for projection at all.

Pay Intl Rarely ​

The platform's Intl API is authoritative for time zone and calendar reference data, and expensive to call. zdate's discipline is to pay it rarely and cache what it says:

  • Zone offsets resolve against per-year offset range tables built once per zone-year. After the first touch, DST resolution is bigint comparisons, not formatToParts calls.
  • UTC field projection is implemented directly (Howard Hinnant's civil-from-days algorithm), avoiding platform Date allocation and legacy behavior.
  • Calendar engines own their conversion and arithmetic; the observational calendars consult Intl for reference data and cache per-year results around their own math.

Calendar Engines ​

Each of the 18 calendars is an engine implementing conversion (ISO <-> calendar), field validation, month lengths, and leap rules. Engines are registered with ZCalendar; every engine is verified by ISO -> calendar -> ISO round-trip tests across 1200 years. See Round-Trip Verification. The calendar engines verified range is actually much wider than the round-trip verification, see Engine Notes.

Strict Boundaries ​

Parsing resolves an external claim about time into one instant, or refuses. Internal wall-time math uses one fixed rule at DST transitions. Repair is a separate, explicit operation with per-condition policies. Each concern has one home, so no option on one surface can quietly change the meaning of another. See Parsing and Repairing Timestamps.

Precision ​

Epochs are nanoseconds. Current-time capture is chosen per runtime: browsers use Temporal's instant when available, because performance.now() is precision-reduced there for Spectre mitigation; Node, Bun, and Deno deliberately use performance.timeOrigin + performance.now() — measurably faster than Temporal, with nanosecond resolution already; browsers without Temporal derive from the same Performance API at reduced precision. Supported range: years −267,000 to +267,000.