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

Signatur

Temporal.Instant.compare(instant1, instant2)

Beschreibung

Temporal.Instant.compare() ist eine statische Methode. Sie vergleicht zwei Temporal.Instant-Werte, also exakte Zeitpunkte auf der Zeitachse mit Nanosekunden-Genauigkeit, unabhängig von Zeitzone oder Kalender. Das Ergebnis ist -1, wenn instant1 früher liegt, 0 bei identischem Zeitpunkt und 1, wenn instant1 später liegt.

Weil die Rückgabe genau der Konvention von Vergleichsfunktionen entspricht, lässt sich die Methode direkt an Array.prototype.sort() oder toSorted() übergeben: instants.sort(Temporal.Instant.compare). Das ist der wichtigste Einsatzzweck, denn die Vergleichsoperatoren < und > werfen bei Temporal-Objekten einen TypeError, weil valueOf() absichtlich einen Fehler auslöst.

Beide Argumente werden bei Bedarf umgewandelt. Neben Temporal.Instant-Objekten sind auch Temporal.ZonedDateTime-Objekte und RFC-9557-/ISO-8601-Strings mit Offset oder Z erlaubt, z. B. "2024-03-10T12:00:00Z". Für eine reine Gleichheitsprüfung ist instant.equals(other) besser lesbar.

Parameter

Name	Typ	Default	Beschreibung
$instant1 Pflicht	Temporal.Instant \| Temporal.ZonedDateTime \| string		Erster Zeitpunkt. Strings müssen einen UTC-Offset oder `Z` enthalten und werden wie bei `Temporal.Instant.from()` umgewandelt.
$instant2 Pflicht	Temporal.Instant \| Temporal.ZonedDateTime \| string		Zweiter Zeitpunkt. Er wird genauso umgewandelt wie `instant1`.

Beispiele

Zwei Zeitpunkte vergleichen

const start = Temporal.Instant.from('2024-03-10T08:00:00Z');
const ende = Temporal.Instant.from('2024-03-10T10:00:00+02:00'); // = 08:00Z
const spaeter = Temporal.Instant.from('2024-03-10T09:30:00Z');

console.log(Temporal.Instant.compare(start, spaeter));
console.log(Temporal.Instant.compare(start, ende));
console.log(Temporal.Instant.compare(spaeter, start));

-1 0 1

Log-Einträge chronologisch sortieren

const logs = [
  { msg: 'Deploy fertig', at: Temporal.Instant.from('2024-05-01T12:05:00Z') },
  { msg: 'Build gestartet', at: Temporal.Instant.from('2024-05-01T11:58:00Z') },
  { msg: 'Tests grün', at: Temporal.Instant.from('2024-05-01T12:01:30Z') }
];

const sortiert = logs.toSorted((a, b) => Temporal.Instant.compare(a.at, b.at));
sortiert.forEach(({ msg, at }) => console.log(at.toString(), msg));

2024-05-01T11:58:00Z Build gestartet 2024-05-01T12:01:30Z Tests grün 2024-05-01T12:05:00Z Deploy fertig

Ablauf eines Tokens prüfen

const istAbgelaufen = (expiresAt) =>
  Temporal.Instant.compare(Temporal.Now.instant(), expiresAt) >= 0;

console.log(istAbgelaufen('2000-01-01T00:00:00Z'));
console.log(istAbgelaufen(Temporal.Now.instant().add({ hours: 1 })));

true false

Direkt als Sortierfunktion übergeben

const zeiten = ['2024-01-03T00:00Z', '2023-12-31T23:59Z', '2024-01-01T00:00Z']
  .map((s) => Temporal.Instant.from(s));

zeiten.sort(Temporal.Instant.compare);
console.log(zeiten.map(String));

[ '2023-12-31T23:59:00Z', '2024-01-01T00:00:00Z', '2024-01-03T00:00:00Z' ]

// Wichtig · Fallstricke

Keine Vergleichsoperatoren: a < b mit Temporal-Objekten wirft einen TypeError, weil valueOf() absichtlich einen Fehler auslöst. Verwende stattdessen immer compare() oder equals().
Strings ohne Offset wie "2024-03-10T12:00" lösen einen RangeError aus, weil sie keinen exakten Zeitpunkt beschreiben.
Temporal.PlainDateTime kann nicht übergeben werden, weil ihm der Bezug zur Zeitachse fehlt. Wandle es vorher mit toZonedDateTime() um.
Der Vergleich läuft auf Nanosekunden-Ebene. Zwei Werte, die sich nur in Nanosekunden unterscheiden, sind also nicht gleich, auch wenn ihre Millisekunden übereinstimmen.
Kompatibilität: Temporal ist erst in neueren Browsern verfügbar (Firefox 139+, Chrome 144+). Safari und ältere Node.js-Versionen brauchen einen Polyfill wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.Instant Temporal.Instant.prototype.equals() Temporal.Instant.from() Temporal.Instant.prototype.since() Temporal.ZonedDateTime.compare() Array.prototype.sort()