Temporal.Instant.fromEpochNanoseconds() — Methode · JavaScript-Referenz

Signatur

Temporal.Instant.fromEpochNanoseconds(epochNanoseconds)

Beschreibung

Temporal.Instant.fromEpochNanoseconds() ist eine statische Fabrikmethode. Sie erzeugt ein Temporal.Instant, also einen exakten Zeitpunkt ohne Zeitzone und Kalender, aus der Anzahl der Nanosekunden seit dem Unix-Epoch (Mitternacht am 1. Januar 1970, UTC). Positive Werte liegen nach dem Epoch, negative davor.

Die Methode ist nanosekundengenau und damit die verlustfreie Variante. Sie eignet sich besonders, wenn Zeitstempel aus hochauflösenden Quellen stammen, z. B. aus Tracing-Systemen wie OpenTelemetry, aus Logdateien, Datenbanken wie ClickHouse oder InfluxDB oder aus Protokollen, die Nanosekunden als 64-Bit-Ganzzahl übertragen. Das Gegenstück ist die Eigenschaft Temporal.Instant.prototype.epochNanoseconds. Mit ihr lässt sich ein Instant wieder in genau denselben BigInt zurückverwandeln.

Der Parameter muss ein BigInt sein. Eine number wird nicht automatisch umgewandelt, weil Werte in Nanosekunden schnell über Number.MAX_SAFE_INTEGER hinausgehen und dann an Genauigkeit verlieren würden. Für Millisekunden-Zeitstempel, wie sie Date.now() liefert, gibt es die bequemere Methode Temporal.Instant.fromEpochMilliseconds().

Parameter

Name	Typ	Default	Beschreibung
$epochNanoseconds Pflicht	bigint		Anzahl der Nanosekunden seit dem Unix-Epoch als `BigInt`. Erlaubt ist der Bereich ±8,64 × 10²¹ ns, das sind ±10⁸ Tage bzw. etwa ±273.790 Jahre um 1970.

Rückgabewert

Typ

Temporal.Instant

Beschreibung

Ein neues Temporal.Instant-Objekt für den angegebenen exakten Zeitpunkt.

Beispiele

Grundlagen: Epoch und Zeitpunkte davor

const epoch = Temporal.Instant.fromEpochNanoseconds(0n);
console.log(epoch.toString());

// Eine Nanosekunde vor dem Epoch
const davor = Temporal.Instant.fromEpochNanoseconds(-1n);
console.log(davor.toString());

1970-01-01T00:00:00Z 1969-12-31T23:59:59.999999999Z

Nanosekunden-Zeitstempel aus Log oder Datenbank verarbeiten

// Zeitstempel kommt als String (z. B. aus JSON), damit keine Genauigkeit verloren geht
const logEintrag = { ts: '1700000000123456789', msg: 'Request empfangen' };

const zeitpunkt = Temporal.Instant.fromEpochNanoseconds(BigInt(logEintrag.ts));

console.log(zeitpunkt.toString());
console.log(zeitpunkt.toZonedDateTimeISO('Europe/Berlin').toString());

2023-11-14T22:13:20.123456789Z 2023-11-14T23:13:20.123456789+01:00[Europe/Berlin]

Verlustfreier Hin- und Rückweg und Dauer zwischen zwei Spans

const start = Temporal.Instant.fromEpochNanoseconds(1700000000000000000n);
const ende  = Temporal.Instant.fromEpochNanoseconds(1700000000001234567n);

const dauer = start.until(ende, { largestUnit: 'millisecond' });
console.log(dauer.toString());

// Zurück zum BigInt – exakt identisch
console.log(ende.epochNanoseconds === 1700000000001234567n);

PT0.001234567S true

Fehlerbehandlung: falscher Typ und Bereichsüberschreitung

const sicherErzeugen = (wert) => {
  try {
    return Temporal.Instant.fromEpochNanoseconds(wert);
  } catch (err) {
    console.log(`${err.name}: ungültiger Wert ${String(wert)}`);
    return null;
  }
};

sicherErzeugen(1000);                        // number statt BigInt
sicherErzeugen(8_640_000_000_000_000_000_001n); // außerhalb des Bereichs
console.log(sicherErzeugen(1000n)?.toString());

TypeError: ungültiger Wert 1000 RangeError: ungültiger Wert 8640000000000000000001 1970-01-01T00:00:00.000001Z

// Wichtig · Fallstricke

Nur BigInt: Wird eine number wie 1000 übergeben, entsteht ein TypeError. Mit BigInt(wert) umwandeln oder ein Literal mit n-Suffix verwenden.
Genauigkeit in JSON: Nanosekunden-Werte passen nicht verlustfrei in eine JSON-number. Überträgt man sie als String und wandelt sie danach mit BigInt() um, bleiben alle Stellen erhalten. Eine Umwandlung wie BigInt(Date.now()) * 1_000_000n liefert zwar den richtigen Typ, die Auflösung bleibt aber bei Millisekunden.
Wertebereich: Werte außerhalb von ±8,64 × 10²¹ ns lösen einen RangeError aus. Das ist derselbe Bereich, den auch Date abdeckt.
Keine Monotonie-Quelle: process.hrtime.bigint() (Node.js) und performance.now() messen nicht ab dem Unix-Epoch. Ihre Werte ergeben hier keinen sinnvollen Zeitpunkt.
Kompatibilität: Temporal gibt es bisher nur in neueren Browsern (Firefox 139+, Chrome 144+). Safari und ältere Node.js-Versionen brauchen einen Polyfill, z. B. @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.Instant Temporal.Instant.fromEpochMilliseconds() Temporal.Instant.from() Temporal.Now.instant() BigInt