Temporal.Instant.prototype.epochNanoseconds — Eigenschaft · JavaScript-Referenz

Signatur

get Temporal.Instant.prototype.epochNanoseconds

Beschreibung

Die schreibgeschützte Zugriffs-Eigenschaft epochNanoseconds liefert die interne, exakte Darstellung eines Temporal.Instant: die Anzahl der Nanosekunden seit der Unix-Epoche (Mitternacht zu Beginn des 1. Januar 1970, UTC). Liegt der Zeitpunkt vor der Epoche, ist der Wert negativ.

Der Wert ist ein BigInt und keine Number, weil Nanosekunden-Zeitstempel schnell größer als Number.MAX_SAFE_INTEGER (ca. 9 × 10¹⁵) werden. Der heutige Zeitpunkt liegt bereits bei etwa 1,7 × 10¹⁸ Nanosekunden. Mit einem BigInt gehen keine Stellen verloren.

Nutzen Sie die Eigenschaft, wenn Sie Zeitpunkte verlustfrei speichern, übertragen oder vergleichen wollen, etwa für Datenbanken mit Nanosekunden-Genauigkeit, Protokolle, verteiltes Tracing (z. B. OpenTelemetry) oder für den Austausch mit Systemen, die Nanosekunden-Zeitstempel erwarten. Für die umgekehrte Richtung gibt es Temporal.Instant.fromEpochNanoseconds() oder den Konstruktor new Temporal.Instant(bigint).

Brauchen Sie nur Millisekunden-Genauigkeit, etwa für die Umwandlung in ein Date, ist epochMilliseconds einfacher, denn es liefert eine gewöhnliche Number.

Rückgabewert

Typ

bigint

Beschreibung

Anzahl der Nanosekunden seit der Unix-Epoche als BigInt. Vor 1970 ist der Wert negativ. Der Wertebereich reicht von -8.64e21 bis 8.64e21 Nanosekunden, also ±10⁸ Tage.

Beispiele

Nanosekunden-Zeitstempel auslesen

const instant = Temporal.Instant.from('2024-03-15T12:30:45.123456789Z');

console.log(instant.epochNanoseconds);
console.log(typeof instant.epochNanoseconds);

1710505845123456789n bigint

Verlustfreies Speichern und Wiederherstellen (z. B. JSON)

const jetzt = Temporal.Now.instant();

// BigInt ist nicht JSON-serialisierbar, darum als String speichern
const payload = JSON.stringify({ ts: jetzt.epochNanoseconds.toString() });

// Später wiederherstellen
const { ts } = JSON.parse(payload);
const wiederhergestellt = Temporal.Instant.fromEpochNanoseconds(BigInt(ts));

console.log(wiederhergestellt.equals(jetzt));

true

Dauer in Nanosekunden messen und vergleichen

const start = Temporal.Now.instant();
let summe = 0;
for (let i = 0; i < 1e6; i++) summe += i;
const ende = Temporal.Now.instant();

const diffNs = ende.epochNanoseconds - start.epochNanoseconds;
console.log(`Dauer: ${diffNs} ns (${Number(diffNs) / 1e6} ms)`);

Dauer: 3000000 ns (3 ms) // Wert variiert

Zeitpunkte vor der Epoche und Umrechnung in Date

const mondlandung = Temporal.Instant.from('1969-07-20T20:17:40Z');
console.log(mondlandung.epochNanoseconds);

// Für Date die Millisekunden verwenden, nicht die Nanosekunden
const date = new Date(mondlandung.epochMilliseconds);
console.log(date.toISOString());

-14182940000000000n 1969-07-20T20:17:40.000Z

// Wichtig · Fallstricke

BigInt und Number nicht mischen: instant.epochNanoseconds + 1 wirft einen TypeError. Schreiben Sie + 1n oder wandeln Sie ausdrücklich mit Number() um. Die Umwandlung in Number kann bei so großen Werten Genauigkeit kosten.
JSON: JSON.stringify() wirft bei BigInt-Werten einen TypeError. Serialisieren Sie den Wert als String oder verwenden Sie instant.toString() (ISO-8601).
Nur lesbar: Die Eigenschaft hat keinen Setter. Eine Zuweisung wird im nicht-strikten Modus stillschweigend ignoriert und wirft im strikten Modus einen Fehler. Temporal.Instant ist unveränderlich. Um einen verschobenen Zeitpunkt zu erhalten, nutzen Sie add() oder subtract().
Genauigkeit der Uhr: Temporal.Now.instant() liefert zwar Nanosekunden, Browser runden aber aus Sicherheitsgründen (Timing-Angriffe) oft auf Mikro- oder Millisekunden.
Kompatibilität: Temporal ist noch nicht in allen Umgebungen verfügbar. Firefox unterstützt es ab Version 139, Chromium-Browser ab etwa Version 144. Safari und ältere Node.js-Versionen brauchen einen Polyfill wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.Instant.prototype.epochMilliseconds Temporal.Instant.fromEpochNanoseconds() Temporal.Instant Temporal.ZonedDateTime.prototype.epochNanoseconds BigInt Temporal.Now.instant()