JS RuntimeExperimental

Temporal API and Timezone-Safe Dates

Mental Model

Temporal replaces JavaScript's mutable, zero-indexed Date with immutable domain types: Temporal.Instant for exact timestamps, Temporal.PlainDate for calendar dates without timezones, and Temporal.ZonedDateTime for IANA timezone and Daylight Saving Time arithmetic.

Interactive Simulator

Mutable Legacy Date vs Immutable Temporal Types

Lines of Code
Before
2
After
3
Reflows / Browser Cost
Before
Mutable instance
After
Immutable value
BeforeLegacy Date (Mutable & UTC-Trap)
const d = new Date('2026-03-08'); // UTC midnight -> Mar 7 in US!
d.setDate(d.getDate() + 1); // Mutates in place, 0-indexed months
Lines: 2Reflows: Mutable instanceDependencies: No PlainDate / IANA DST

Silently mutates operands and conflates calendar dates with UTC instants.

After (Native)Temporal.PlainDate & ZonedDateTime
const day = Temporal.PlainDate.from('2026-03-08');
const next = day.add({ days: 1 }); // Immutable '2026-03-09'
const meeting = next.toZonedDateTime({ timeZone: 'America/New_York', plainTime: '09:00' });
Lines: 3Reflows: Immutable valueDependencies: Native ICU4X timezone

Separates wall-clock dates from timezones and preserves DST invariants.

Under the Hood

Temporal replaces Date's single mutable epoch-millisecond slot with distinct immutable types: Instant for physical time, PlainDate for calendar dates, and ZonedDateTime backed by ICU4X IANA timezone tables. Engines enforce explicit conversions across these boundaries, eliminating silent UTC-offset and DST arithmetic bugs.

  1. Strict Type Boundaries: Engines enforce explicit conversions between PlainDate and ZonedDateTime, exposing immutable methods via dedicated Prototype Chains.
  2. ICU4X Timezone Rules: ZonedDateTime.add({ days: 1 }) consults IANA transition tables so 23-hour and 25-hour DST days keep the same wall-clock hour.
  3. Serialization: Unlike Date in Structured Clone, Temporal values serialize cleanly via .toString() (RFC 9557) across workers and JSON.
JS
const nyMeeting = Temporal.ZonedDateTime.from(
  '2026-03-08T09:00:00[America/New_York]'
);
// Crosses spring-forward DST cleanly at 09:00 local time
const nextDay = nyMeeting.add({ days: 1 });
console.log(nextDay.toString());

Problem Genealogy

  • 1995 (ES1 Date): Copied java.util.Date with mutable setters, 0-indexed months, and no IANA timezone support.
  • 2012 (Intl.DateTimeFormat): Added formatting for IANA timezones, yet parsing and arithmetic stayed broken.
  • 2024+ (TC39 Temporal): Shipped immutable calendar/timezone primitives backed by ICU4X in browsers and polyfills.

Production Pitfalls

Production Pitfall
  • Unpolyfilled Safari/Legacy Browsers: Shipping Temporal directly without @js-temporal/polyfill throws ReferenceError on unsupported engines.
  • Ambiguous DST Wall Times: Repeating 01:30 AM during fall-back requires specifying { disambiguation: 'compatible' | 'earlier' | 'later' | 'reject' }.
When Not to Use
  • When not to use Temporal.Instant: Never use Instant for future birthdays or recurring 9 AM meetings, if a country changes its DST law, an Instant shifts on the local clock; store PlainDate or ZonedDateTime instead.

Connections & Logical Next Steps

JS RuntimeTemporal API and Timezone-Safe Dates
What This Unlocks
Leaf concept

Mechanical Comparisons