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

Signatur

Temporal.PlainYearMonth.prototype.valueOf()

Beschreibung

Die Methode valueOf() von Temporal.PlainYearMonth hat nur einen Zweck: Sie verhindert die implizite Umwandlung in einen primitiven Wert. JavaScript ruft valueOf() automatisch auf, wenn ein Objekt in arithmetischen Ausdrücken oder in Vergleichen mit <, >, <= und >= vorkommt. Ein Temporal.PlainYearMonth wirft dabei sofort einen TypeError. So entstehen keine stillen Fehler.

Der Grund dafür: Bei Date liefert valueOf() einen Zeitstempel in Millisekunden. Deshalb funktioniert date1 < date2, aber date1 == date2 vergleicht nur, ob beide Variablen auf dasselbe Objekt zeigen. Dieses uneinheitliche Verhalten war eine häufige Fehlerquelle, und Temporal vermeidet es bewusst.

Für Vergleiche nimmst du stattdessen Temporal.PlainYearMonth.compare(), das sich auch als Vergleichsfunktion für Array.prototype.sort() eignet, oder equals() zur Prüfung auf Gleichheit. Für Rechnungen gibt es add(), subtract(), until() und since(). Eine Textdarstellung erhältst du explizit mit toString() oder toJSON().

Rückgabewert

Typ

never

Beschreibung

Gibt nie etwas zurück, sondern wirft bei jedem Aufruf einen TypeError.

Beispiele

Vergleichsoperatoren lösen einen TypeError aus

const a = Temporal.PlainYearMonth.from("2024-03");
const b = Temporal.PlainYearMonth.from("2024-07");

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.PlainYearMonth.from("2024-03");
const b = Temporal.PlainYearMonth.from("2024-07");

console.log(Temporal.PlainYearMonth.compare(a, b)); // -1, 0 oder 1
console.log(a.equals(Temporal.PlainYearMonth.from({ year: 2024, month: 3 })));

// Abrechnungsmonate chronologisch sortieren
const monate = ["2025-01", "2023-11", "2024-06"].map((s) => Temporal.PlainYearMonth.from(s));
monate.sort(Temporal.PlainYearMonth.compare);
console.log(monate.map(String));

-1 true [ '2023-11', '2024-06', '2025-01' ]

Rechnen mit add() und until() statt mit Operatoren

const start = Temporal.PlainYearMonth.from("2024-10");

// start + 1 würde einen TypeError auslösen
const naechster = start.add({ months: 1 });
console.log(naechster.toString());

const ende = Temporal.PlainYearMonth.from("2025-04");
const dauer = start.until(ende, { largestUnit: "months" });
console.log(dauer.months);

2024-11 6

String-Umwandlung funktioniert trotzdem

const ym = Temporal.PlainYearMonth.from("2024-12");

// Template-Literale und String() rufen toString() auf, nicht valueOf()
console.log(`Abrechnung für ${ym}`);
console.log(String(ym));
console.log(JSON.stringify({ periode: ym }));

try {
  console.log("Periode: " + ym); // + ruft zuerst valueOf() auf
} catch (err) {
  console.log("Fehler:", err.name);
}

Abrechnung für 2024-12 2024-12 {"periode":"2024-12"} Fehler: TypeError

// Wichtig · Fallstricke

Verkettung mit +: "Text " + ym wirft einen TypeError. Der Operator + nutzt den Hinweis default und ruft deshalb valueOf() auf. Template-Literale, String(ym) und ym.toString() funktionieren dagegen.
== und === werfen keinen Fehler. Sie vergleichen aber nur, ob beide Variablen auf dasselbe Objekt zeigen. Zwei inhaltlich gleiche Instanzen gelten also als verschieden. Nutze equals().
Unterschied zu Date: Wer bestehenden Code mit Date auf Temporal umstellt, muss Ausdrücke wie a - b oder a < b ersetzen, und zwar durch until()/since() bzw. compare().
Sortieren: sort() ohne Vergleichsfunktion wandelt die Elemente in Strings um. Das klappt bei ISO-Kalenderdaten zufällig, wird bei anderen Kalendern aber unzuverlässig. Übergib immer Temporal.PlainYearMonth.compare.
Kompatibilität: Temporal ist noch nicht in allen Browsern verfügbar. In Safari und älteren Umgebungen brauchst du ein Polyfill, z. B. @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.PlainYearMonth.compare() Temporal.PlainYearMonth.prototype.equals() Temporal.PlainYearMonth.prototype.toString() Temporal.PlainYearMonth.prototype.toJSON() Temporal.PlainYearMonth.prototype.until() Object.prototype.valueOf()