Signatur
Beschreibung
Temporal.Instant ist Teil der Temporal-API und stellt einen absoluten Moment in der Zeit dar – ähnlich wie Date, aber mit Nanosekundenpräzision und ohne die bekannten Schwächen des Date-Objekts. Ein Instant ist immer UTC-basiert und kennt weder Zeitzonen noch Kalender.
Der interne Wert eines Instant wird als Anzahl Nanosekunden seit dem Unix-Epoch (1970-01-01T00:00:00Z) gespeichert. Dies erlaubt präzise Zeitstempel für technische Protokollierung, Benchmarking und Synchronisation verteilter Systeme.
Um einen Instant menschenlesbar darzustellen oder Datums-/Zeitarithmetik mit Zeitzonen durchzuführen, kann man ihn mit toZonedDateTimeISO() in ein Temporal.ZonedDateTime umwandeln. Für einfache Differenzberechnungen steht die Methode until() bzw. since() zur Verfügung, die eine Temporal.Duration zurückgibt.
- Unveränderlich (immutable): Alle Operationen geben neue Instanzen zurück.
- Vergleichbar: Statische Methode
Temporal.Instant.compare()ermöglicht die Sortierung. - Serialisierbar:
toString()liefert einen ISO-8601-String;Temporal.Instant.from()parst ihn zurück.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $epochNanoseconds Pflicht | BigInt | Anzahl der Nanosekunden seit dem Unix-Epoch (1970-01-01T00:00:00Z) als BigInt. Negative Werte repräsentieren Zeitpunkte vor 1970. |
Rückgabewert
Temporal.Instant-Instanz, die den angegebenen absoluten Zeitpunkt repräsentiert.Beispiele
Aktuellen Zeitpunkt ermitteln und ausgeben
// Aktuellen Zeitpunkt als Temporal.Instant
const now = Temporal.Now.instant();
console.log(now.toString()); // z. B. '2024-06-15T10:23:45.123456789Z'
// Nanosekunden seit Unix-Epoch
console.log(now.epochNanoseconds); // z. B. 1718446425123456789n
// Aus ISO-String erzeugen
const instant = Temporal.Instant.from('2024-01-01T00:00:00Z');
console.log(instant.epochSeconds); // 1704067200Zeitdifferenz berechnen und Zeitzonen-Konvertierung
const start = Temporal.Instant.from('2024-03-10T08:00:00Z');
const end = Temporal.Instant.from('2024-03-10T10:30:00Z');
// Differenz berechnen
const duration = start.until(end, { largestUnit: 'hour' });
console.log(`Dauer: ${duration.hours}h ${duration.minutes}min`);
// Dauer: 2h 30min
// Zeitpunkt in Berliner Ortszeit umwandeln
const berlinZDT = start.toZonedDateTimeISO('Europe/Berlin');
console.log(berlinZDT.toString());
// 2024-03-10T09:00:00+01:00[Europe/Berlin]
// Zwei Instants vergleichen
const cmp = Temporal.Instant.compare(start, end);
console.log(cmp); // -1 (start liegt vor end)// Wichtig · Fallstricke
Browser-Kompatibilität: Temporal ist derzeit (Stand 2024) ein TC39 Stage-3-Proposal und in keinem Browser standardmäßig aktiviert. Für produktiven Einsatz sollte das offizielle Polyfill @js-temporal/polyfill verwendet werden. Node.js unterstützt Temporal ebenfalls noch nicht nativ.
BigInt-Pflicht: Der Konstruktor erwartet zwingend einen BigInt-Wert (z. B. 1000000000n), da reguläre number-Werte nicht ausreichend präzise für Nanosekunden sind. Ein TypeError wird geworfen, wenn kein BigInt übergeben wird.
Wertebereich: Der Wert muss innerhalb des erlaubten Bereichs von ca. ±108 Tagen relativ zum Unix-Epoch liegen. Werte außerhalb dieses Bereichs führen zu einem RangeError.
Kein Timezone-/Kalender-Bezug: Temporal.Instant kennt keine Zeitzonen oder Kalender. Für lokale Zeitdarstellung immer toZonedDateTimeISO() oder toZonedDateTime() verwenden.