patternjavascriptTip
Temporal API — the modern replacement for JavaScript Date
Viewed 0 times
Stage 4 (2025); polyfill: @js-temporal/polyfill
TemporalPlainDateZonedDateTimeimmutable datemodern date API
Problem
The Date object is mutable, has 0-indexed months, conflates UTC and local time, and has no timezone awareness. Every serious application requires a library to work around it.
Solution
The Temporal API (stage 4, shipping in JS engines 2025) provides immutable, timezone-aware date/time types:
Temporal.PlainDate — calendar date, no time
Temporal.PlainDateTime — date + time, no timezone
Temporal.ZonedDateTime — date + time + IANA timezone
Temporal.Instant — exact UTC moment
Temporal.Duration — typed duration
const today = Temporal.Now.plainDateISO();
const nextWeek = today.add({ weeks: 1 });
Temporal.PlainDate — calendar date, no time
Temporal.PlainDateTime — date + time, no timezone
Temporal.ZonedDateTime — date + time + IANA timezone
Temporal.Instant — exact UTC moment
Temporal.Duration — typed duration
const today = Temporal.Now.plainDateISO();
const nextWeek = today.add({ weeks: 1 });
Why
Temporal fixes every known Date footgun: 1-indexed months, immutability, timezone awareness, DST-correct arithmetic, and unambiguous string parsing.
Gotchas
- Temporal is available via @js-temporal/polyfill until engines ship it natively
- Use ZonedDateTime for user-facing events, Instant for timestamps
- All Temporal objects are immutable — modification methods return new instances
- Temporal.Duration arithmetic is calendar-aware — adding months works correctly
Code Snippets
Temporal API basics
import { Temporal } from '@js-temporal/polyfill';
// 1-indexed months (no 0-index confusion)
const d = Temporal.PlainDate.from({ year: 2024, month: 3, day: 15 });
d.month; // 3 (March)
// Timezone-aware conversion
const meeting = Temporal.ZonedDateTime.from(
'2024-03-15T14:00:00[America/New_York]'
);
meeting.withTimeZone('Asia/Tokyo').toString();
// '2024-03-16T03:00:00+09:00[Asia/Tokyo]'Revisions (0)
No revisions yet.