Temporal/Instant

Browserunterstützung
caniuse.com

Ein Temporal.Instant-Objekt repräsentiert einen eindeutigen Zeitpunkt, in Nanosekundengenauigkeit (im Rahmen der Möglichkeiten des verwendeten Computers). Genau wie Date stellt Instant einen Zeitpunkt als die Zeitdifferenz zum Bezugsmoment der Unix-Epoche – 01.01.1970, Mitternacht – dar.

Instant-Objekte kennen weder Zeitzone noch Kalendersystem, sie sind immer als UTC-Zeitpunkte aufzufassen. Aus diesem Grund kennt ein Instant-Objekt auch keine Eigenschaften oder Methoden, die Zeit- oder Datumsinformationen liefern. Solche Informationen erfordern Zeitzone und/oder Kalender, und dafür hat kann ein Instant mit der Methode toZonedDateTimeISO() in ein ZonedDateTime-Objekt umgewandelt werden.

Erzeugen eines Temporal.Instant

Um ein Instant-Objekt zu erhalten, kann man

• Mittels Temporal.Instant.from() einen anderen Instant oder den zu Grunde liegenden Instant eines ZonedDateTime-Objekts klonen
• Mittels Temporal.Instant.from() einen RFC 9557-String in einen Instant konvertieren
• Mittels Temporal.Instant.fromEpochMilliseconds() oder Temporal.Instant.fromEpochNanoseconds() die Zeitdifferenz zur Unix-Epoche in einen Instant umrechnen
• auf einem Date-Objekt die Methode toTemporalInstant() aufrufen
• von Temporal.Now.instant() den aktuellen Zeitpunkt erhalten
• von einem ZonedDateTime-Objekt mittels toInstant() den zu Grunde liegenden Instant abrufen

Hinweis:

Instant.fromEpochNanoseconds erwartet einen BigInt-Wert als Argument. Instant.fromEpochMilliseconds ist lediglich eine Komfortfunktion, die ihren Parameter in einen BigInt umwandelt und mit 1000000 multipliziert, um dann Instant.fromEpochNanoseconds aufzurufen.

Was kann man damit machen?

Nicht viel. Instant-Objekte sind universelle Zeitpunkte ohne direkten Bezug zur menschlichen Welt. Als solche kann man sie vergleichen, und – in Grenzen – mit ihnen rechnen.

Vergleichen

Die statische Methode Temporal.Instant.compare(instant1, instant2) vergleicht zwei Instants und liefert den Wert -1, 0 oder 1, je nach dem, ob instant1 kleiner, gleich oder größer als instant2 ist. instant1 und instant2 können Instant-Objekte sein oder Werte, die von Temporal.Instant.from() konvertiert werden können.

Die compare()-Methode kann, um ein Array von Instant-Objekten (oder geeigneten Strings) zu sortieren, direkt an die Array-Methode sort übergeben werden.

Darüber hinaus unterstützen Instant-Objekte (wie alle Temporal-Objekte) eine equals()-Methode, die true oder false zurückgibt. Sie akzeptiert als Argument alles, was auch von Temporal.Instant.from() akzeptiert wird.

Runden

Wenn man den Zeitpunkt nicht auf Nanosekunden genau haben möchte, sondern auf eine größere Einheit runden will, kann man das mit der Methode round() eines Instant-Objekts tun. Man übergibt an round() entweder ein Options-Objekt mit den Eigenschaften roundingIncrement, roundingMode und smallestUnit, oder lediglich eine Zeichenkette mit dem Wert für smallestUnit.

roundingIncrement (optional)

Hier wird eine positive ganze Zahl erwartet. Fehlt die Eigenschaft, wird 1 angenommen.

Das roundingIncrement setzt die Schrittweite, die die gerundeten Werte in der angegebenen smallestUnit haben sollen.

roundingMode (optional)

Gibt die Rundungsregel an, analog zu Intl.NumberFormat. Voreinstellung ist "halfExpand", was kaufmännischer Rundung entspricht.

roundingsmallestUnit (erforderlich)

Die Einheit, auf die gerundet werden soll. Möglich sind "hour", "minute", "second", "millisecond" oder "nanosecond"; die Pluralform dieser Begriffe ist ebenfalls erlaubt.

Runden von Instants

const jetzt = Temporal.Now.instant();

console.log(jetzt.toString());
         // '2026-03-02T20:37:42.811600098Z'

console.log(jetzt.round("minutes").toString());
         // '2026-03-02T20:38:00Z'

console.log(jetzt.round({ roundingIncrement: 10, smallestUnit: "seconds").toString());
         // '2026-03-02T20:37:40Z'

console.log(jetzt.round({ roundingIncrement: 7, smallestUnit: "minutes").toString());
         // Temporal error: dividend is not divisible by roundingIncrement

Beachte: Das roundingIncrement muss so gewählt sein, dass sich ein Tag, in der gewünschten smallestUnit ausgedrückt, dadurch teilen lässt. Möchte man zum Beispiel auf Sekunden runden, muss das Inkrement ein Teiler von 24×60×60=86400 sein. Möchte man auf Minuten runden, muss das Inkrement ein Teiler von 24×60=3600 sein.

Arithmetik

Man kann zu einem Instant eine Duration addieren oder subtrahieren, und man kann aus der Zeitdifferenz eine Duration erzeugen.

Zum Addieren und Subtrahieren dienen die Methoden add() und subtract eines Instant-Objekts. Sie erwarten ein Duration-Objekt als Argument, diese Duration darf allerdings keinen Kalender benötigen, um interpretiert werden zu können. Das bedeutet: Jahre, Monate und Wochen sind in einer solchen Duration nicht zulässig.

Zeitdifferenzen lassen sich auf zwei Arten ermitteln. Die Differenz instant2 - instant1 erhält man:

• bezogen auf instant1 mit instant1.until(instant2)
• bezogen auf instant2 mit instant2.since(instant1)

Das Ergebnis ist das Gleiche. Und wann verwendet man was? Beide Methoden akzeptieren alles, was auch die from()-Methode akzeptiert. Wenn man also einen der beiden Instants als Instant-Objekt vorliegen hat und der andere erst noch mittels from() konstruiert werden müsste, dann kann man sich das durch Verwendung der geeigneten Methode ersparen. Ansonsten ist es gleichgültig, welche Methode man benutzt.

Die ermittelte Zeitdifferenz lässt sich direkt runden. Dazu übergibt man an until() bzw. since() ein options-Objekt, wie es auch von der round()-Methode von Duration verstanden wird.

Wenn einer der beiden Instants als Instant-Objekt vorliegt und der andere Instant zunächst konvertiert werden muss, ist die benötigte Methode

Mit einem Instanz