Die JavaScript Temporal API: Datumshandling richtig gemacht
Warum die Temporal API jahrzehntealte JavaScript-Date-Bugs behebt und wie Sie rechtzeitig von Date wegmigrieren.

Date ist seit 1995 kaputt, und wir haben uns alle stillschweigend darauf geeinigt, drumherum zu arbeiten. Mutable Instanzen, nullindizierte Monate, mehrdeutige Zeitzonenbehandlung und ein Parser, der klaglos jeden Unsinn als Eingabe akzeptiert — jeder JavaScript-Entwickler hat seine eigene Geschichte über einen Date-Bug, der erst in Produktion auftauchte, meist an einer Zeitzonengrenze oder bei einem DST-Übergang. Die Temporal API behebt das auf Sprachebene, und sie steht kurz genug vor der Fertigstellung, dass Sie sich jetzt damit auseinandersetzen sollten — nicht erst, wenn sie in jeder Runtime gelandet ist.
Warum Date ständig Probleme verursacht
Das Kernproblem ist nicht, dass Date Bugs hat — es ist, dass Date drei verschiedene Konzepte in ein einziges mutables Objekt presst: einen Zeitpunkt, ein Kalenderdatum und einen zeitzonenbewussten Augenblick. Bei jeder Operation darauf muss das System raten, welches davon Sie eigentlich meinten.
// ❌ 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 kennt außerdem kein reines Kalenderdatum (ein Geburtstag hat keine Zeitzone) und keine zivile Uhrzeit (ein wiederkehrendes Meeting "um 9 Uhr Ortszeit" bedeutet je nach Standort etwas anderes). Jeder Workaround — Bibliotheken wie Moment.js, date-fns oder Luxon — existiert nur deshalb, weil das Plattform-Primitiv unzureichend ist.
Die zentralen Temporal-Typen
Temporal teilt das einzelne Date-Objekt in klar abgegrenzte, zweckgebundene Typen auf. Das ist die größte gedankliche Umstellung: Sie wählen den Typ, der tatsächlich zu dem passt, was Sie modellieren, statt alles durch ein einziges mehrdeutiges Objekt zu zwingen.
| Typ | Repräsentiert | Beispielanwendung |
|---|---|---|
Temporal.PlainDate | Kalenderdatum ohne Uhrzeit | Geburtstag, Fälligkeitsdatum einer Rechnung |
Temporal.PlainTime | Uhrzeit ohne Datum | Öffnungszeit eines Geschäfts |
Temporal.ZonedDateTime | Zeitpunkt + Zeitzone | Meeting, das in einer bestimmten Stadt stattfindet |
Temporal.Instant | Exakter Punkt auf der UTC-Zeitlinie | Zeitstempel in einem Server-Log |
// ✅ 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]Jedes Temporal-Objekt ist unveränderlich (immutable). add(), subtract() und with() geben alle neue Instanzen zurück — das eliminiert eine ganze Kategorie von Fernwirkungs-Bugs, die durch geteilte, mutable Date-Referenzen entstehen.
Temporal basiert auf dem TC39-Stage-3-Proposal, derselben Standardisierungsorganisation, die auch die ECMAScript-Spezifikation verantwortet. Es ist in Firefox nativ implementiert und läuft anderswo hinter Runtime-Support-Flags, wobei Polyfills die Lücke vorerst überbrücken.
Durations sind ein eigenständiger Typ
Einer der häufigsten Date-Bugs besteht darin, eine Zeitspanne als Millisekunden-Integer zu behandeln und dabei die semantische Bedeutung von "1 Monat" gegenüber "30 Tagen" zu verlieren — das ist nicht dasselbe, und die Date-Arithmetik hat keine Möglichkeit, diesen Unterschied auszudrücken.
// ❌ 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 unterstützt außerdem ausgeglichene Arithmetik zwischen zwei Zeitpunkten:
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()); // P2M14DT8H30MDiese ISO-8601-Dauer-Zeichenkette ist direkt mit jedem System interoperabel, das den ISO-8601-Standard liest — und das betrifft die meisten Logging-Pipelines, API-Verträge und bereits eingesetzten Datenbank-Serialisierungsformate.
Zeitzonen ohne externe Bibliotheken
Zeitzonenbehandlung ist der Bereich, in dem sich die meisten Date-Bibliotheken bislang bewährt haben, denn das einzige native zeitzonenbewusste Primitiv des Browsers war bisher Intl.DateTimeFormat — das formatiert zwar, erlaubt aber keine Arithmetik. Temporal schließt diese Lücke direkt.
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 weekendBeachten Sie: Es gibt keine Mehrdeutigkeit darüber, ob 09:00 Ortszeit oder UTC meint — ZonedDateTime trägt den IANA-Zonenbezeichner mit sich, und jede Operation berücksichtigt DST-Übergänge in genau dieser Zone automatisch.
Migration ohne Komplettumbau
Sie müssen nicht alle Date-Aufrufe auf einmal herausreißen. Der praktikable Weg besteht darin, zuerst an den Systemgrenzen zu konvertieren — API-Antworten, Datenbankzugriffe, Formulareingaben — und Temporal die gesamte interne Logik überlassen zu lassen.
// 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);
}Das entspricht dem Vorgehen, mit dem Teams vor Jahren von moment zu date-fns oder luxon migriert sind: die Konvertierung an den Rändern isolieren, die Geschäftslogik auf dem besseren Primitiv belassen und den Legacy-Typ entfernen, sobald jede Aufrufstelle umgestellt ist.
Die wichtigsten Erkenntnisse
Datevermengt Zeitpunkte, Kalenderdaten und zivile Uhrzeiten in einem mutablen Objekt — die meisten Date-Bugs entstehen aus dieser Vermengung, nicht aus Rechenfehlern.- Temporal bietet klar abgegrenzte Typen (
PlainDate,PlainTime,ZonedDateTime,Instant), sodass die Typsignatur selbst dokumentiert, was der Wert tatsächlich darstellt. - Jedes Temporal-Objekt ist unveränderlich —
add()undwith()geben neue Instanzen zurück und eliminieren Bugs durch geteilte Referenzen. Temporal.Durationversteht Kalender-Semantik ("1 Monat" ist keine feste Anzahl Millisekunden) — etwas, dasDate-Arithmetik nicht ausdrücken kann.- Zeitzonen-Mathematik ist nativ — Sie brauchen keine Bibliothek mehr, nur um einen Tag korrekt über eine DST-Grenze hinweg zu addieren.
- Migrieren Sie zuerst an den Systemgrenzen (API-Parsing, DB-Zugriffe) und lassen Sie Temporal die interne Logik übernehmen, bevor Sie jede Aufrufstelle anfassen.
Prüfen Sie die Unterstützung, bevor Sie Produktionscode darauf festlegen — werfen Sie einen Blick in die Kompatibilitätstabellen der Temporal-Referenz bei MDN und greifen Sie in Umgebungen ohne native Unterstützung auf den offiziellen Polyfill zurück. Aber entwerfen Sie Ihre Datumslogik schon heute nach dem Temporal-Modell, auch hinter einem Polyfill — das ist die Richtung, in die sich die Sprache entwickelt, und Code, der gegen PlainDate und ZonedDateTime geschrieben ist, wird jede ad hoc zusammengestellte Date-Bibliothek überleben, zu der Sie sonst greifen würden.


