Zum Inhalt springen

Die JavaScript Temporal API: Datumshandling richtig gemacht

Warum die Temporal API jahrzehntealte JavaScript-Date-Bugs behebt und wie Sie rechtzeitig von Date wegmigrieren.

4 Min. Lesezeit
Code-Editor zeigt die Verwendung der JavaScript Temporal API für Datums- und Zeitberechnungen

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.

jsjavascript
// ❌ 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.

TypRepräsentiertBeispielanwendung
Temporal.PlainDateKalenderdatum ohne UhrzeitGeburtstag, Fälligkeitsdatum einer Rechnung
Temporal.PlainTimeUhrzeit ohne DatumÖffnungszeit eines Geschäfts
Temporal.ZonedDateTimeZeitpunkt + ZeitzoneMeeting, das in einer bestimmten Stadt stattfindet
Temporal.InstantExakter Punkt auf der UTC-ZeitlinieZeitstempel in einem Server-Log
jsjavascript
// ✅ 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.

i

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.

jsjavascript
// ❌ 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 clamped

Temporal.Duration unterstützt außerdem ausgeglichene Arithmetik zwischen zwei Zeitpunkten:

jsjavascript
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()); // P2M14DT8H30M

Diese 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.

tstypescript
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 weekend

Beachten 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.

tstypescript
// 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

  1. Date vermengt Zeitpunkte, Kalenderdaten und zivile Uhrzeiten in einem mutablen Objekt — die meisten Date-Bugs entstehen aus dieser Vermengung, nicht aus Rechenfehlern.
  2. Temporal bietet klar abgegrenzte Typen (PlainDate, PlainTime, ZonedDateTime, Instant), sodass die Typsignatur selbst dokumentiert, was der Wert tatsächlich darstellt.
  3. Jedes Temporal-Objekt ist unveränderlich — add() und with() geben neue Instanzen zurück und eliminieren Bugs durch geteilte Referenzen.
  4. Temporal.Duration versteht Kalender-Semantik ("1 Monat" ist keine feste Anzahl Millisekunden) — etwas, das Date-Arithmetik nicht ausdrücken kann.
  5. Zeitzonen-Mathematik ist nativ — Sie brauchen keine Bibliothek mehr, nur um einen Tag korrekt über eine DST-Grenze hinweg zu addieren.
  6. 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.

Wilfredo Rujel

Wilfredo Rujel

Full-Stack-Softwareentwickler

Diesen Beitrag teilenX