Temporal.ZonedDateTime.prototype.valueOf() — Methode · JavaScript-Referenz

Signatur

Temporal.ZonedDateTime.prototype.valueOf()

Beschreibung

Die Methode valueOf() von Temporal.ZonedDateTime gibt absichtlich keinen Wert zurück. Sie wirft immer einen TypeError. Das ist eine bewusste Entscheidung im Design von Temporal: Bei Date liefert valueOf() einen Zeitstempel in Millisekunden. Dadurch funktionieren Ausdrücke wie date1 < date2 oder date2 - date1 zwar, sie führen aber oft zu unauffälligen Fehlern, etwa bei Zeitzonen oder bei ==-Vergleichen, die nur die Objektidentität prüfen.

JavaScript ruft valueOf() automatisch auf, wenn ein Objekt in eine Zahl oder einen primitiven Wert umgewandelt werden soll. Das passiert bei arithmetischen Operatoren (-, *, unäres +), bei relationalen Vergleichen (<, >, <=, >=) und bei Number(). Bei einem ZonedDateTime bricht all das sofort mit einem Fehler ab. So fallen falsche Nutzungen schon beim Entwickeln auf und schleichen sich nicht als falsche Ergebnisse ein.

Nutzen Sie stattdessen die dafür vorgesehenen Methoden:

Temporal.ZonedDateTime.compare(a, b) zum Sortieren und Vergleichen
a.equals(b) für einen Gleichheitstest (Zeitpunkt, Zeitzone und Kalender)
a.until(b) bzw. a.since(b) für Differenzen
a.epochMilliseconds bzw. a.epochNanoseconds, wenn Sie wirklich einen Zahlenwert brauchen

Beispiele

Implizite Umwandlung löst TypeError aus

const start = Temporal.ZonedDateTime.from('2024-03-10T09:00[Europe/Berlin]');
const ende = Temporal.ZonedDateTime.from('2024-03-10T17:30[Europe/Berlin]');

try {
  console.log(ende - start);
} catch (err) {
  console.log(err instanceof TypeError, err.name);
}

try {
  console.log(start < ende);
} catch (err) {
  console.log('Vergleich nicht erlaubt:', err.name);
}

true TypeError Vergleich nicht erlaubt: TypeError

Richtig vergleichen und sortieren mit compare()

const termine = [
  Temporal.ZonedDateTime.from('2024-06-01T14:00[Europe/Berlin]'),
  Temporal.ZonedDateTime.from('2024-06-01T09:00[America/New_York]'),
  Temporal.ZonedDateTime.from('2024-06-01T08:00[Europe/London]')
];

// termine.sort((a, b) => a - b) würde einen TypeError werfen
termine.sort(Temporal.ZonedDateTime.compare);

console.log(termine.map((t) => t.toString()));

[ '2024-06-01T08:00:00+01:00[Europe/London]', '2024-06-01T14:00:00+02:00[Europe/Berlin]', '2024-06-01T09:00:00-04:00[America/New_York]' ]

Differenz berechnen und Zahlenwert gezielt abrufen

const abflug = Temporal.ZonedDateTime.from('2024-07-01T10:15[Europe/Berlin]');
const landung = Temporal.ZonedDateTime.from('2024-07-01T13:05[America/New_York]');

// Statt landung - abflug:
const dauer = abflug.until(landung, { largestUnit: 'hour' });
console.log(dauer.toString());

// Wenn wirklich eine Zahl gebraucht wird: explizit anfordern
const ms = landung.epochMilliseconds - abflug.epochMilliseconds;
console.log(ms / 60000, 'Minuten');

PT8H50M 530 Minuten

// Wichtig · Fallstricke

Gleichheit mit ==/===: Diese Operatoren rufen valueOf() nicht auf, wenn beide Seiten Objekte sind. Sie vergleichen nur die Referenz und liefern ohne Fehler false, auch wenn beide Instanzen denselben Zeitpunkt darstellen. Verwenden Sie equals().
String-Verkettung funktioniert: Bei Template-Literalen und String(zdt) wird toString() verwendet. `${zdt}` wirft also keinen Fehler. '' + zdt dagegen nutzt den Hinweis „default“ und landet bei valueOf(), deshalb wirft es.
Umstieg von Date: Bestehender Code wie arr.sort((a, b) => a - b) oder if (d1 < d2) muss beim Wechsel auf Temporal umgeschrieben werden.
Kompatibilität: Temporal wird noch nicht überall unterstützt: Firefox ab 139, Chromium-Browser ab 144, Safari noch nicht. Für ältere Umgebungen gibt es Polyfills wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.ZonedDateTime.compare() Temporal.ZonedDateTime.prototype.equals() Temporal.ZonedDateTime.prototype.until() Temporal.ZonedDateTime.prototype.since() Temporal.ZonedDateTime.prototype.epochMilliseconds Temporal.ZonedDateTime.prototype.toString() Object.prototype.valueOf()