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

Signatur

Temporal.PlainDateTime.prototype.valueOf()

Beschreibung

Die Methode valueOf() von Temporal.PlainDateTime gibt keinen Wert zurück, sondern wirft immer einen TypeError. Das ist Absicht: JavaScript ruft valueOf() automatisch auf, wenn ein Objekt in eine Zahl oder einen anderen primitiven Wert umgewandelt werden muss, zum Beispiel bei den Vergleichsoperatoren <, >, <=, >= oder bei arithmetischen Operatoren wie - und +.

Beim alten Date-Objekt liefert valueOf() einen Zeitstempel in Millisekunden. Darum funktionieren dort Ausdrücke wie date2 - date1 oder date1 < date2. Ein PlainDateTime hat aber keine Zeitzone und entspricht damit keinem eindeutigen Zeitpunkt. Eine versteckte Umwandlung in eine Zahl oder in einen Text würde leicht zu falschen Ergebnissen führen, etwa weil Zeichenketten lexikografisch verglichen werden. Das gilt besonders bei Jahren außerhalb von 0000–9999 oder bei anderen Kalendern.

Verwende stattdessen die dafür gedachten Methoden:

Temporal.PlainDateTime.compare(a, b) zum Sortieren und Vergleichen (gibt -1, 0 oder 1 zurück)
a.equals(b) zur Prüfung auf Gleichheit
a.until(b) bzw. a.since(b) für Differenzen als Temporal.Duration
toString() oder toJSON() für eine ausdrückliche Umwandlung in einen Text

Du rufst valueOf() praktisch nie selbst auf. Wichtig ist nur, zu wissen, warum ein Operator bei PlainDateTime einen Fehler auslöst.

Rückgabewert

Typ

never

Beschreibung

Gibt nie einen Wert zurück, sondern wirft immer einen TypeError.

Beispiele

Vergleichsoperator löst TypeError aus

const start = Temporal.PlainDateTime.from('2024-03-01T09:00');
const ende = Temporal.PlainDateTime.from('2024-03-01T17:30');

try {
  console.log(start < ende); // ruft intern valueOf() auf
} catch (err) {
  console.log(err instanceof TypeError);
}

true

Richtig vergleichen und sortieren mit compare()

const termine = [
  Temporal.PlainDateTime.from('2024-05-10T14:00'),
  Temporal.PlainDateTime.from('2024-05-09T08:15'),
  Temporal.PlainDateTime.from('2024-05-10T09:30'),
];

termine.sort(Temporal.PlainDateTime.compare);
console.log(termine.map(String));

const [a, b] = termine;
console.log(Temporal.PlainDateTime.compare(a, b) < 0); // a liegt vor b
console.log(a.equals(b));

["2024-05-09T08:15:00", "2024-05-10T09:30:00", "2024-05-10T14:00:00"] true false

Differenz mit until() statt Subtraktion

const start = Temporal.PlainDateTime.from('2024-03-01T09:00');
const ende = Temporal.PlainDateTime.from('2024-03-01T17:30');

// start - ende würde einen TypeError werfen
const dauer = start.until(ende);
console.log(dauer.toString());
console.log(dauer.total({ unit: 'minutes' }));

PT8H30M 510

Ausdrückliche Umwandlung in Text funktioniert

const dt = Temporal.PlainDateTime.from('2024-12-24T18:00');

// Template-Literale und String() rufen toString() auf, nicht valueOf()
console.log(`Bescherung: ${dt}`);
console.log(JSON.stringify({ zeit: dt }));

try {
  const x = dt + 1; // + mit Hint "default" → valueOf() → TypeError
} catch (err) {
  console.log(err.name);
}

Bescherung: 2024-12-24T18:00:00 {"zeit":"2024-12-24T18:00:00"} TypeError

// Wichtig · Fallstricke

Auch == funktioniert nicht wie erwartet: Zwei verschiedene Instanzen mit demselben Datum sind nie === bzw. == gleich, weil dabei Objekt-Referenzen verglichen werden. Verwende equals(). Beim Vergleich mit einem primitiven Wert (z. B. dt == 'abc') wird eine Umwandlung ausgelöst und dabei ein TypeError geworfen.
Umstieg von Date: Code, der Daten mit < oder - vergleicht, lässt sich nicht einfach übernehmen. Er muss auf compare(), until() bzw. since() umgestellt werden.
Kein Zeitstempel: PlainDateTime hat keine Zeitzone. Für echte Zeitpunkte brauchst du toZonedDateTime(zeitzone) und danach z. B. epochMilliseconds.
Array.prototype.sort() ohne Vergleichsfunktion wandelt die Elemente in Texte um. Das wirft keinen Fehler, kann aber falsch sortieren, zum Beispiel bei erweiterten Jahreszahlen oder nicht-gregorianischen Kalendern. Übergib daher immer Temporal.PlainDateTime.compare.
Kompatibilität: Temporal ist in Firefox (ab 139) und Chrome (ab 144) verfügbar. Safari und ältere Umgebungen brauchen ein Polyfill wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

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