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

Signatur

Temporal.PlainDate.prototype.valueOf()

Beschreibung

valueOf() ist bei Temporal.PlainDate absichtlich so gebaut, dass sie immer einen TypeError wirft. JavaScript ruft valueOf() automatisch auf, wenn ein Objekt in einen primitiven Wert umgewandelt werden muss, zum Beispiel bei den Operatoren <, >, <=, >=, bei arithmetischen Operatoren wie - und + oder bei Number(date).

Diese Schutzfunktion ist eine bewusste Designentscheidung von Temporal: Bei Date liefert valueOf() einen Zeitstempel in Millisekunden. Deshalb funktioniert date1 < date2 dort zwar, aber auch sinnlose Ausdrücke wie date + 1 laufen ohne Fehler durch. Ein PlainDate hat keine Uhrzeit und keine Zeitzone, daher gibt es keinen eindeutigen Zahlenwert dafür. Statt stillschweigend falsche Ergebnisse zu liefern, schlägt die Umwandlung sofort fehl.

Zum Vergleichen nimmst du Temporal.PlainDate.compare() (für Sortierung und Größer/Kleiner) oder equals() (für Gleichheit). Für Datumsrechnungen gibt es add(), subtract(), until() und since(). Eine String-Darstellung bekommst du mit toString(), toJSON() oder toLocaleString(). Diese Methoden werden auch bei Template-Literalen und bei String(date) genutzt, weil dabei die String-Umwandlung bevorzugt wird.

Rückgabewert

Typ

never

Beschreibung

Die Methode gibt nie einen Wert zurück, sondern wirft immer einen TypeError.

Beispiele

Relationale Operatoren werfen einen TypeError

const a = Temporal.PlainDate.from('2024-03-01');
const b = Temporal.PlainDate.from('2024-05-15');

try {
  console.log(a < b);
} catch (err) {
  console.log(err instanceof TypeError, err.name);
}

true TypeError

Richtig vergleichen mit compare() und equals()

const a = Temporal.PlainDate.from('2024-03-01');
const b = Temporal.PlainDate.from('2024-05-15');

console.log(Temporal.PlainDate.compare(a, b)); // -1, 0 oder 1
console.log(Temporal.PlainDate.compare(a, b) < 0); // ist a früher als b?
console.log(a.equals(Temporal.PlainDate.from('2024-03-01')));

// Termine chronologisch sortieren
const termine = [b, a].sort(Temporal.PlainDate.compare);
console.log(termine.map(String));

-1 true true [ '2024-03-01', '2024-05-15' ]

Differenz berechnen statt subtrahieren

const start = Temporal.PlainDate.from('2024-01-10');
const ende = Temporal.PlainDate.from('2024-03-05');

// ende - start würde einen TypeError werfen
const dauer = start.until(ende, { largestUnit: 'day' });
console.log(`${dauer.days} Tage`);

// String-Umwandlung klappt, denn sie nutzt toString()
console.log(`Projektende: ${ende}`);

55 Tage Projektende: 2024-03-05

// Wichtig · Fallstricke

Umstieg von Date: Code wie a < b, a - b oder +date funktioniert mit PlainDate nicht. Stelle ihn auf compare() bzw. until()/since() um.
Gleichheit: a == b und a === b werfen keinen Fehler, wenn beide Seiten Objekte sind. Sie prüfen aber nur, ob es dasselbe Objekt ist, und liefern bei gleichem Datum in zwei Instanzen false. Nutze dafür equals(). Wird ein PlainDate dagegen per == mit einem primitiven Wert verglichen (etwa einem String), wird valueOf() aufgerufen und es gibt einen TypeError.
Verkettung mit +: 'Datum: ' + date wirft ebenfalls einen TypeError, weil + zuerst valueOf() aufruft. Template-Literale oder String(date) funktionieren dagegen.
Sortieren: array.sort() ohne Vergleichsfunktion sortiert nach String-Darstellung. Bei ISO-Daten mit vierstelliger Jahreszahl klappt das zufällig, sicher ist aber nur array.sort(Temporal.PlainDate.compare).
Kompatibilität: Temporal ist erst seit Kurzem in Browsern verfügbar (Firefox 139+, Chrome 144+). In anderen Umgebungen brauchst du ein Polyfill wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

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