Temporal.Instant.prototype.equals() — Methode · JavaScript-Referenz

Signatur

Temporal.Instant.prototype.equals(other)

Beschreibung

Die Methode equals() vergleicht zwei exakte Zeitpunkte auf der Zeitachse. Zwei Temporal.Instant-Objekte sind gleich, wenn ihre Werte in epochNanoseconds übereinstimmen – also wenn sie denselben Moment seit der Unix-Epoche (1970-01-01T00:00:00Z) auf die Nanosekunde genau beschreiben.

Das Argument other muss kein Temporal.Instant sein: Es wird intern wie bei Temporal.Instant.from() umgewandelt. Damit lassen sich auch RFC-9557-/ISO-8601-Zeichenketten mit Zeitzonen-Offset (z. B. "2024-03-10T12:00:00+01:00") direkt vergleichen. Unterschiedliche Offset-Schreibweisen, die denselben Moment beschreiben, gelten als gleich.

Verwende equals() statt ===, denn === vergleicht bei Objekten nur die Referenz. Wenn du eine Reihenfolge brauchst (früher/später), zum Beispiel zum Sortieren, nimm stattdessen die statische Methode Temporal.Instant.compare().

Parameter

Name	Typ	Default	Beschreibung
$other Pflicht	Temporal.Instant \| string		Der zu vergleichende Zeitpunkt. Ein `Temporal.Instant` oder eine Zeichenkette mit Datum, Uhrzeit und Offset bzw. `Z`, die `Temporal.Instant.from()` verarbeiten kann.

Beispiele

Zwei Instants vergleichen

const a = Temporal.Instant.from("2024-06-01T10:00:00Z");
const b = Temporal.Instant.fromEpochMilliseconds(Date.UTC(2024, 5, 1, 10));

console.log(a.equals(b));
console.log(a === b); // Referenzvergleich!

true false

Unterschiedliche Offsets, gleicher Moment

const berlin = Temporal.Instant.from("2024-06-01T12:00:00+02:00");

// Zeichenketten werden automatisch per Instant.from() umgewandelt
console.log(berlin.equals("2024-06-01T10:00:00Z"));
console.log(berlin.equals("2024-06-01T06:00:00-04:00"));
console.log(berlin.equals("2024-06-01T10:00:00.000000001Z"));

true true false

Praxis: Prüfen, ob ein Cache-Eintrag unverändert ist

const cache = new Map();

const istAktuell = (key, lastModified) => {
  const gespeichert = cache.get(key);
  return gespeichert !== undefined && gespeichert.equals(lastModified);
};

cache.set("/api/user", Temporal.Instant.from("2024-06-01T08:30:00Z"));

// z. B. aus einem Server-Header (ISO-Format)
console.log(istAktuell("/api/user", "2024-06-01T10:30:00+02:00"));
console.log(istAktuell("/api/user", "2024-06-01T09:00:00Z"));

true false

// Wichtig · Fallstricke

Kein ===: Temporal-Objekte sind Objekte. === und == vergleichen nur Referenzen. < und > lösen einen TypeError aus, weil valueOf() absichtlich einen Fehler wirft.
Strenge Eingabe: Zeichenketten ohne Offset bzw. Z (z. B. "2024-06-01T10:00") sind kein exakter Zeitpunkt und führen zu einem RangeError. Ungültige Typen wie Zahlen oder Date-Objekte führen zu einem TypeError. Ein Date wandelst du vorher mit date.toTemporalInstant() oder Temporal.Instant.fromEpochMilliseconds(date.getTime()) um.
Nanosekunden-Genauigkeit: Schon 1 ns Unterschied ergibt false. Für einen Vergleich mit Toleranz rundest du beide Werte vorher mit round() oder prüfst until() gegen eine Schwelle.
Zum Vergleich von Zeitpunkten mit Zeitzone und Kalender dient Temporal.ZonedDateTime.prototype.equals(). Diese Methode berücksichtigt Zeitzone und Kalender zusätzlich.
Kompatibilität: Temporal ist noch nicht in allen Browsern verfügbar (u. a. Safari). Ob es fehlt, prüfst du mit typeof Temporal !== "undefined". Als Ersatz dient z. B. das Polyfill @js-temporal/polyfill.

Siehe auch

Temporal.Instant.compare() Temporal.Instant.from() Temporal.Instant Temporal.Instant.prototype.add() Temporal.Instant.prototype.round()