Temporal.PlainYearMonth.compare() — Methode · JavaScript-Referenz

Signatur

Temporal.PlainYearMonth.compare(yearMonth1, yearMonth2)

Beschreibung

Temporal.PlainYearMonth.compare() ist eine statische Methode, die zwei Jahr-Monat-Angaben chronologisch vergleicht. Sie liefert -1, wenn yearMonth1 früher liegt, 1, wenn er später liegt, und 0, wenn beide gleich sind. Damit passt die Methode direkt als Vergleichsfunktion für Array.prototype.sort() oder Array.prototype.toSorted().

Beide Argumente dürfen nicht nur Temporal.PlainYearMonth-Instanzen sein, sondern alles, was Temporal.PlainYearMonth.from() akzeptiert: ISO-Zeichenketten wie "2024-03" oder Objekte wie { year: 2024, month: 3 }. Die Werte werden intern vor dem Vergleich umgewandelt.

Typische Anwendungsfälle sind Abrechnungszeiträume, Monatsberichte, Ablaufdaten von Kreditkarten (MM/JJ) oder Filter wie „alle Einträge ab Monat X“. Im Unterschied zu equals(), das nur auf Gleichheit prüft (und dabei auch den Kalender berücksichtigt), liefert compare() eine Reihenfolge.

Verglichen wird das zugrunde liegende ISO-Datum inklusive des internen Referenztags. Bei Werten im ISO-Kalender spielt das keine Rolle; bei unterschiedlichen Kalendern kann es aber zu unerwarteten Ergebnissen kommen.

Parameter

Name	Typ	Default	Beschreibung
$yearMonth1 Pflicht	Temporal.PlainYearMonth \| string \| object		Erster Jahr-Monat-Wert. Wird bei Bedarf wie mit `Temporal.PlainYearMonth.from()` umgewandelt.
$yearMonth2 Pflicht	Temporal.PlainYearMonth \| string \| object		Zweiter Jahr-Monat-Wert, mit dem `yearMonth1` verglichen wird. Wird genauso umgewandelt.

Beispiele

Einfacher Vergleich mit Instanzen und Zeichenketten

const maerz = Temporal.PlainYearMonth.from('2024-03');
const juni = Temporal.PlainYearMonth.from({ year: 2024, month: 6 });

console.log(Temporal.PlainYearMonth.compare(maerz, juni));
console.log(Temporal.PlainYearMonth.compare(juni, maerz));
// Zeichenketten werden automatisch umgewandelt
console.log(Temporal.PlainYearMonth.compare('2024-03', maerz));

-1 1 0

Abrechnungsmonate chronologisch sortieren

const monate = ['2024-11', '2023-02', '2024-01', '2023-12'].map((s) =>
  Temporal.PlainYearMonth.from(s)
);

const sortiert = monate.toSorted(Temporal.PlainYearMonth.compare);
console.log(sortiert.map((ym) => ym.toString()));

// Absteigend (neueste zuerst)
const absteigend = monate.toSorted((a, b) => Temporal.PlainYearMonth.compare(b, a));
console.log(absteigend[0].toString());

[ '2023-02', '2023-12', '2024-01', '2024-11' ] 2024-11

Prüfen, ob eine Kreditkarte abgelaufen ist

const istAbgelaufen = (monat, jahr) => {
  const ablauf = Temporal.PlainYearMonth.from({ year: 2000 + jahr, month: monat });
  const aktuell = Temporal.Now.plainDateISO().toPlainYearMonth();
  // Die Karte ist bis einschließlich des Ablaufmonats gültig
  return Temporal.PlainYearMonth.compare(ablauf, aktuell) < 0;
};

console.log(istAbgelaufen(12, 20)); // 12/20
console.log(istAbgelaufen(1, 99));  // 01/99

true false

// Wichtig · Fallstricke

Browserunterstützung: Temporal ist neu. Aktuell unterstützt in Firefox 139+ und Chrome/Edge 144+; Safari und ältere Node.js-Versionen brauchen ein Polyfill wie @js-temporal/polyfill. Vorher mit typeof Temporal !== 'undefined' prüfen.
Statische Methode: Der Aufruf lautet Temporal.PlainYearMonth.compare(a, b) und nicht a.compare(b). Instanzen haben dafür equals(), das nur auf Gleichheit prüft.
Nicht mit </> vergleichen: Temporal-Objekte werfen bei valueOf() einen TypeError, deshalb funktionieren relationale Operatoren nicht. Immer compare() verwenden.
Kalender: Verglichen wird das zugrunde liegende ISO-Datum samt Referenztag, nicht der Kalender. compare() kann also 0 liefern, während equals() bei verschiedenen Kalendern false ergibt. Bei Werten aus nicht-ISO-Kalendern vorher mit withCalendar() bzw. über toPlainDate() auf einen gemeinsamen Kalender bringen.
Ungültige Eingaben wie "2024-13" oder falsche Typen lösen einen RangeError bzw. TypeError aus.

Siehe auch

Temporal.PlainYearMonth Temporal.PlainYearMonth.prototype.equals() Temporal.PlainYearMonth.from() Temporal.PlainYearMonth.prototype.until() Temporal.PlainDate.compare() Array.prototype.sort()