The JavaScript Temporal API: Date Handling Done Right
Why the Temporal API fixes decades of JavaScript date bugs, and how to migrate off Date before it quietly breaks your app.

Date has been broken since 1995, and we've all just agreed to work around it. Mutable instances, zero-indexed months, ambiguous time zone handling, and a parser that silently accepts garbage input — every JavaScript developer has a war story about a date bug that only showed up in production, usually around a time zone boundary or a DST transition. The Temporal API fixes this at the language level, and it's close enough to shipping that you should understand it now, not after it lands in every runtime.
Why Date Keeps Breaking Things
The core problem isn't that Date has bugs — it's that Date conflates three different concepts into one mutable object: a point in time, a wall-clock date, and a time zone-aware instant. Every operation you do on it has to guess which one you meant.
// ❌ Date: mutation, implicit UTC/local confusion, no real duration type
const meeting = new Date('2026-03-08T14:00:00');
meeting.setDate(meeting.getDate() + 1); // mutates in place
const duration = new Date(meeting) - new Date(); // subtraction gives ms, not a duration
// Was that +1 day across a DST boundary? Which time zone did the
// constructor assume? setDate() silently rolls over invalid days.
// None of this is visible by reading the code.Date also has no concept of a calendar-only date (a birthday has no time
zone) or a civil time (a recurring meeting at "9am local" means something
different depending on where you are). Every workaround — libraries like
Moment.js, date-fns, or Luxon — exists specifically because the platform
primitive is inadequate.
The Core Temporal Types
Temporal splits the single Date object into distinct, purpose-built types.
This is the single biggest mental shift: you pick the type that matches what
you're actually modeling, instead of forcing everything through one
ambiguous object.
| Type | Represents | Example use case |
|---|---|---|
Temporal.PlainDate | Calendar date, no time | Birthday, invoice due date |
Temporal.PlainTime | Wall-clock time, no date | Store opening hour |
Temporal.ZonedDateTime | Instant + time zone | Meeting scheduled in a specific city |
Temporal.Instant | Exact point on the UTC timeline | Server log timestamp |
// ✅ Temporal: immutable, explicit, type matches intent
const meeting = Temporal.PlainDate.from('2026-03-08');
const tomorrow = meeting.add({ days: 1 }); // returns a new instance
const zoned = Temporal.ZonedDateTime.from(
'2026-03-08T14:00:00-05:00[America/New_York]'
);
const inTokyo = zoned.withTimeZone('Asia/Tokyo');
console.log(inTokyo.toString());
// 2026-03-09T04:00:00+09:00[Asia/Tokyo]Every Temporal object is immutable. add(), subtract(), and with()
all return new instances, which eliminates an entire category of
action-at-a-distance bugs caused by shared mutable date references.
Temporal is defined by TC39 Stage 3 proposal, the same standards body that owns the ECMAScript specification. It's implemented natively in Firefox and ships behind runtime support elsewhere, with polyfills covering the gap in the meantime.
Durations Are a First-Class Type
One of the most common date bugs is treating a duration as a millisecond
integer and losing the semantic meaning of "1 month" versus "30 days" — they
aren't the same thing, and Date arithmetic has no way to express the
difference.
// ❌ Millisecond math breaks across month/DST boundaries
const ONE_MONTH_MS = 30 * 24 * 60 * 60 * 1000;
const renewalDate = new Date(subscriptionStart.getTime() + ONE_MONTH_MS);
// Off by a day or more depending on the actual month length.
// ✅ Temporal.Duration carries calendar semantics
const subscriptionStart = Temporal.PlainDate.from('2026-01-31');
const renewalDate = subscriptionStart.add({ months: 1 });
console.log(renewalDate.toString()); // '2026-02-28' — correctly clampedTemporal.Duration also supports balanced arithmetic between two points:
const start = Temporal.PlainDateTime.from('2026-01-01T09:00:00');
const end = Temporal.PlainDateTime.from('2026-03-15T17:30:00');
const elapsed = start.until(end, {
largestUnit: 'months',
smallestUnit: 'minutes',
});
console.log(elapsed.toString()); // P2M14DT8H30MThat ISO 8601 duration string is directly interoperable with any system that reads the ISO 8601 standard, which includes most logging pipelines, API contracts, and database serialization formats already in use.
Time Zones Without External Libraries
Time zone handling is where most date libraries earn their keep, because the
browser's only native time zone-aware primitive used to be Intl.DateTimeFormat,
which formats but doesn't let you do arithmetic. Temporal closes that gap
directly.
function nextBusinessDayInZone(
date: Temporal.PlainDate,
timeZone: string
): Temporal.ZonedDateTime {
let candidate = date.toZonedDateTime({
timeZone,
plainTime: Temporal.PlainTime.from('09:00:00'),
});
do {
candidate = candidate.add({ days: 1 });
} while (
candidate.dayOfWeek === 6 ||
candidate.dayOfWeek === 7
);
return candidate;
}
const result = nextBusinessDayInZone(
Temporal.PlainDate.from('2026-11-13'), // a Friday
'Europe/Madrid'
);
console.log(result.toString());
// 2026-11-16T09:00:00+01:00[Europe/Madrid] — correctly skips the weekendNotice there's no ambiguity about whether 09:00 means local time or UTC —
ZonedDateTime carries the IANA zone identifier with it, and every
operation respects DST transitions in that specific zone automatically.
Migrating Without a Big-Bang Rewrite
You don't need to rip out every Date call at once. The practical path is
to convert at your system's boundaries first — API responses, database
reads, form inputs — and let Temporal own all internal logic.
// Boundary: convert incoming Date/string to Temporal immediately
function parseApiTimestamp(iso: string): Temporal.Instant {
return Temporal.Instant.from(iso);
}
// Internal logic works exclusively with Temporal types
function isWithinSla(
receivedAt: Temporal.Instant,
resolvedAt: Temporal.Instant,
slaHours: number
): boolean {
const elapsed = receivedAt.until(resolvedAt, { largestUnit: 'hours' });
return elapsed.hours <= slaHours;
}
// Boundary: convert back only when an API or legacy library demands Date
function toLegacyDate(instant: Temporal.Instant): Date {
return new Date(instant.epochMilliseconds);
}This mirrors how teams migrated off moment to date-fns or luxon
years ago: isolate the conversion at the edges, keep business logic on the
better primitive, and remove the legacy type once every call site has moved.
Key Takeaways
Dateconflates instants, calendar dates, and civil times into one mutable object — most date bugs come from that conflation, not from arithmetic mistakes.- Temporal gives you distinct types (
PlainDate,PlainTime,ZonedDateTime,Instant) so the type signature documents what the value actually represents. - Every Temporal object is immutable —
add()andwith()return new instances, eliminating shared-reference bugs. Temporal.Durationunderstands calendar semantics ("1 month" is not a fixed number of milliseconds), whichDatearithmetic cannot express.- Time zone math is native — you no longer need a library just to add a day correctly across a DST boundary.
- Migrate at system boundaries first (API parsing, DB reads) and let Temporal own internal logic before touching every call site.
Check support before you commit production code to it — consult the
compatibility tables on MDN's Temporal reference and reach for the official polyfill in environments where native support
isn't there yet. But design your date-handling logic against Temporal's
model today, even behind a polyfill — it's the shape the language is
converging on, and code written against PlainDate and ZonedDateTime
will outlive whatever ad hoc date library you'd otherwise reach for.


