Signatur
Beschreibung
Die Zugriffseigenschaft epochNanoseconds gibt den exakten Zeitpunkt einer Temporal.ZonedDateTime als BigInt zurück. Gemeint sind die Nanosekunden seit dem Unix-Epoch, also seit Mitternacht am Anfang des 1. Januar 1970 (UTC). Die Zeitzone und der Kalender der Instanz spielen für den Wert keine Rolle: Zwei ZonedDateTime-Objekte, die denselben Zeitpunkt in verschiedenen Zeitzonen darstellen, haben denselben Wert für epochNanoseconds.
Die Eigenschaft ist die genaueste Darstellung eines Zeitpunkts in Temporal. Das ist nützlich, wenn Zeitstempel verlustfrei gespeichert, verglichen oder serialisiert werden sollen, zum Beispiel für Datenbanken, Protokolldateien oder den Austausch mit Systemen, die in Nanosekunden rechnen (etwa process.hrtime.bigint() in Node.js oder Tracing-Formate wie OpenTelemetry). Aus dem Wert lässt sich mit Temporal.Instant.fromEpochNanoseconds() und new Temporal.ZonedDateTime(ns, timeZone) wieder ein vollständiges Objekt erzeugen.
Die Eigenschaft ist nur lesbar. Es gibt keinen Setter. Um einen anderen Zeitpunkt zu erhalten, erzeugt man mit add(), subtract() oder with() ein neues Objekt. Wer nur Millisekunden braucht, zum Beispiel für den Austausch mit Date, verwendet besser epochMilliseconds, das eine normale number zurückgibt.
Rückgabewert
BigInt) mit den Nanosekunden seit dem Unix-Epoch. Bei Zeitpunkten vor 1970 ist der Wert negativ. Der Wertebereich reicht von -8.64e21n bis 8.64e21n (±108 Tage).Beispiele
Zeitstempel in Nanosekunden auslesen
const zdt = Temporal.ZonedDateTime.from("2024-03-15T12:30:00.123456789+01:00[Europe/Berlin]");
console.log(zdt.epochNanoseconds);
console.log(typeof zdt.epochNanoseconds);Wert unabhängig von der Zeitzone
const berlin = Temporal.ZonedDateTime.from("2024-06-01T10:00:00+02:00[Europe/Berlin]");
const tokio = berlin.withTimeZone("Asia/Tokyo");
console.log(tokio.toString());
console.log(berlin.epochNanoseconds === tokio.epochNanoseconds);Verlustfrei speichern und wiederherstellen
const original = Temporal.Now.zonedDateTimeISO("Europe/Berlin");
// BigInt ist nicht JSON-fähig → als String speichern
const json = JSON.stringify({
ns: original.epochNanoseconds.toString(),
tz: original.timeZoneId,
});
const { ns, tz } = JSON.parse(json);
const restored = new Temporal.ZonedDateTime(BigInt(ns), tz);
console.log(restored.equals(original));Dauer in Nanosekunden berechnen und sortieren
const start = Temporal.ZonedDateTime.from("2024-01-01T00:00:00Z[UTC]");
const ende = start.add({ milliseconds: 1, nanoseconds: 500 });
const diffNs = ende.epochNanoseconds - start.epochNanoseconds;
console.log(diffNs);
const events = [ende, start];
events.sort((a, b) => (a.epochNanoseconds < b.epochNanoseconds ? -1 : 1));
console.log(events.map((e) => e.toString()));// Wichtig · Fallstricke
- BigInt, keine Number: Man kann den Wert nicht mit
numbermischen (zdt.epochNanoseconds + 1wirft einenTypeError). Richtig ist+ 1n.JSON.stringify()kann BigInt nicht serialisieren, daher vorher.toString()verwenden. - Nicht mit
Number()umwandeln: Werte überNumber.MAX_SAFE_INTEGERverlieren an Genauigkeit. Für Millisekunden istepochMillisecondsdie richtige Wahl. - Vergleiche: Zum Sortieren ist
Temporal.ZonedDateTime.compare()meist lesbarer. Beachte, dassequals()auch Zeitzone und Kalender vergleicht,epochNanosecondsdagegen nur den reinen Zeitpunkt. - Nur lesbar: Eine Zuweisung wird still ignoriert, im Strict Mode wirft sie einen
TypeError. - Kompatibilität: Temporal ist noch neu (Firefox 139+, Chrome 144+). Für ältere Umgebungen ist ein Polyfill nötig, etwa
@js-temporal/polyfillodertemporal-polyfill.