Date.prototype.toTemporalInstant() — Methode · JavaScript-Referenz

Signatur

Date.prototype.toTemporalInstant()

Beschreibung

toTemporalInstant() ist die offizielle Brücke zwischen dem alten Date-Objekt und der neuen Temporal-API. Die Methode liefert ein Temporal.Instant, also einen exakten Zeitpunkt auf der globalen Zeitachse ohne Zeitzone und ohne Kalender. Der Wert von epochMilliseconds des Ergebnisses entspricht genau date.getTime().

Brauchen wirst du sie vor allem, wenn bestehender Code, Bibliotheken oder APIs (z. B. File.lastModifiedDate, Datenbanktreiber, JSON-Parser) noch Date-Objekte liefern, du aber mit Temporal weiterrechnen willst – etwa um sie mit toZonedDateTimeISO() in eine bestimmte Zeitzone umzurechnen oder Zeitabstände mit until()/since() genau zu bestimmen.

Weil ein Date nur Millisekunden speichert, sind die Mikro- und Nanosekundenanteile des erzeugten Instant immer 0. Das Original-Date bleibt unverändert; das Ergebnis ist ein unveränderliches (immutable) Temporal-Objekt.

Rückgabewert

Typ

Temporal.Instant

Beschreibung

Ein neues Temporal.Instant, dessen epochMilliseconds dem Zeitstempel des Datums entspricht. Ist das Datum ungültig (NaN), wird ein RangeError ausgelöst.

Beispiele

Date in Temporal.Instant umwandeln

const date = new Date("2024-03-15T12:30:00Z");
const instant = date.toTemporalInstant();

console.log(instant.toString());
console.log(instant.epochMilliseconds === date.getTime());

2024-03-15T12:30:00Z true

Zeitpunkt aus einer Legacy-API in eine Zeitzone umrechnen

// z. B. Wert aus einer älteren Bibliothek
const createdAt = new Date("2024-03-15T12:30:00Z");

const berlin = createdAt
  .toTemporalInstant()
  .toZonedDateTimeISO("Europe/Berlin");

console.log(berlin.toString());
console.log(`${berlin.hour}:${String(berlin.minute).padStart(2, "0")} Uhr`);

2024-03-15T13:30:00+01:00[Europe/Berlin] 13:30 Uhr

Ungültige Datumswerte sicher abfangen

const toInstantSafe = (date) => {
  if (Number.isNaN(date.getTime())) return null;
  return date.toTemporalInstant();
};

console.log(toInstantSafe(new Date("kein Datum")));

try {
  new Date("kein Datum").toTemporalInstant();
} catch (err) {
  console.log(err instanceof RangeError);
}

null true

Feature-Erkennung und Rückweg zu Date

const now = new Date();

if (typeof Date.prototype.toTemporalInstant === "function") {
  const instant = now.toTemporalInstant();
  const later = instant.add({ hours: 2 });
  // Zurück zu Date über epochMilliseconds
  const backToDate = new Date(later.epochMilliseconds);
  console.log(backToDate.getTime() - now.getTime());
} else {
  console.log("Temporal wird nicht unterstützt – Polyfill laden");
}

7200000

// Wichtig · Fallstricke

Browser-Kompatibilität: Temporal ist erst in neuen Versionen verfügbar (Firefox 139+, Chromium-Browser ab Version 144). Safari und ältere Node.js-Versionen unterstützen es noch nicht vollständig. Prüfe vorher mit typeof Date.prototype.toTemporalInstant === "function" oder nutze einen Polyfill (z. B. @js-temporal/polyfill, der die Methode aber nicht automatisch an Date.prototype hängt – dort ist die Funktion toTemporalInstant separat exportiert und wird mit .call(date) aufgerufen).
Ungültige Daten: Bei new Date(NaN) oder nicht parsebaren Strings wird ein RangeError ausgelöst, es wird also kein „Invalid Date“-Wert weitergereicht.
Genauigkeit: Date kennt nur Millisekunden. Umgekehrt gehen beim Rückweg über new Date(instant.epochMilliseconds) Mikro- und Nanosekunden verloren.
Keine Zeitzone: Das Ergebnis enthält keine Zeitzone. Für lokale Uhrzeiten musst du explizit toZonedDateTimeISO(timeZone) aufrufen – anders als bei Date wird nicht stillschweigend die Systemzeitzone verwendet.
Es gibt bewusst keine Methode toTemporalZonedDateTime() o. ä.; der Weg führt immer über Instant.

Siehe auch

Temporal.Instant Date Temporal.Now.instant() Date.prototype.toLocaleString() Date.prototype.toTimeString()