Temporal API and Timezone-Safe Dates
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.
Mutable Legacy Date vs Immutable Temporal Types
const d = new Date('2026-03-08'); // UTC midnight -> Mar 7 in US!
d.setDate(d.getDate() + 1); // Mutates in place, 0-indexed monthsSilently mutates operands and conflates calendar dates with UTC instants.
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' });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.
- Strict Type Boundaries: Engines enforce explicit conversions between
PlainDateandZonedDateTime, exposing immutable methods via dedicated Prototype Chains. - 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. - Serialization: Unlike
Datein Structured Clone,Temporalvalues serialize cleanly via.toString()(RFC 9557) across workers and JSON.
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): Copiedjava.util.Datewith 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
- Unpolyfilled Safari/Legacy Browsers: Shipping
Temporaldirectly without@js-temporal/polyfillthrowsReferenceErroron unsupported engines. - Ambiguous DST Wall Times: Repeating 01:30 AM during fall-back requires specifying
{ disambiguation: 'compatible' | 'earlier' | 'later' | 'reject' }.
- When not to use
Temporal.Instant: Never useInstantfor future birthdays or recurring 9 AM meetings, if a country changes its DST law, anInstantshifts on the local clock; storePlainDateorZonedDateTimeinstead.
Connections & Logical Next Steps
Temporal types expose immutable value methods on dedicated prototypes without mutating receivers.
Unlike legacy Date, Temporal objects require explicit ISO string serialization across postMessage.