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

Signatur

get Temporal.Instant.prototype.epochMilliseconds

Beschreibung

Die Accessor-Eigenschaft epochMilliseconds einer Temporal.Instant-Instanz liefert den Zeitpunkt als ganze Zahl von Millisekunden seit dem Unix-Epoch, also Mitternacht UTC am Anfang des 1. Januar 1970. Das ist genau das Format, das auch Date.now(), Date.prototype.getTime() und viele Datenbanken bzw. REST-APIs verwenden.

Intern speichert ein Temporal.Instant Nanosekunden (siehe epochNanoseconds, ein bigint). epochMilliseconds rechnet diesen Wert in Millisekunden um und rundet dabei ab in Richtung minus unendlich (Math.floor-Verhalten). Die Genauigkeit unterhalb einer Millisekunde geht dabei verloren.

Brauchen kannst du die Eigenschaft vor allem für die Zusammenarbeit mit bestehendem Code: Du erzeugst damit ein Date-Objekt, speicherst Zeitstempel als Zahl, sendest sie an Server oder vergleichst sie mit Date.now(). Den umgekehrten Weg gehst du mit Temporal.Instant.fromEpochMilliseconds().

Die Eigenschaft kann nur gelesen werden. Es gibt keinen Setter, denn Temporal.Instant ist unveränderlich. Für einen anderen Zeitpunkt erzeugst du eine neue Instanz, zum Beispiel mit add(), subtract() oder round().

Rückgabewert

Typ

number

Beschreibung

Ganzzahl mit den Millisekunden seit dem Unix-Epoch, abgerundet in Richtung minus unendlich. Bei Zeitpunkten vor 1970 ist der Wert negativ. Der Wertebereich liegt innerhalb von ±8,64·10¹⁵, also im selben Bereich wie bei Date.

Beispiele

Zeitstempel eines festen Zeitpunkts auslesen

const instant = Temporal.Instant.from("2024-01-01T00:00:00Z");
console.log(instant.epochMilliseconds);

// Gleicher Wert wie bei Date
console.log(Date.UTC(2024, 0, 1));

1704067200000 1704067200000

Temporal.Instant in ein Date-Objekt umwandeln (Interop mit Alt-Code)

const instant = Temporal.Now.instant();

// Bibliotheken, die noch Date erwarten, bekommen ein Date-Objekt
const date = new Date(instant.epochMilliseconds);
console.log(date instanceof Date);

// Und zurück zu Temporal
const back = Temporal.Instant.fromEpochMilliseconds(date.getTime());
console.log(back.epochMilliseconds === instant.epochMilliseconds);

true true

Zeitstempel an eine API senden und Ablaufzeit prüfen

const now = Temporal.Now.instant();
const expiresAt = now.add({ minutes: 30 });

const payload = JSON.stringify({
  createdAt: now.epochMilliseconds,
  expiresAt: expiresAt.epochMilliseconds,
});
console.log(payload);

// Später: Token noch gültig?
const { expiresAt: exp } = JSON.parse(payload);
const isValid = Date.now() < exp;
console.log(isValid);

{"createdAt":1718000000000,"expiresAt":1718001800000} // Werte abhängig von der aktuellen Zeit true

Rundungsverhalten vor dem Epoch und Präzisionsverlust

const beforeEpoch = Temporal.Instant.from("1969-12-31T23:59:59.9995Z");
console.log(beforeEpoch.epochNanoseconds);  // -500000n
console.log(beforeEpoch.epochMilliseconds); // abgerundet Richtung -∞

const precise = Temporal.Instant.from("2024-01-01T00:00:00.123456789Z");
console.log(precise.epochMilliseconds);     // Mikro-/Nanosekunden fallen weg

-500000n -1 1704067200123

// Wichtig · Fallstricke

Präzisionsverlust: Alles unterhalb einer Millisekunde wird verworfen. Wenn dir Mikro- oder Nanosekunden wichtig sind, nimm epochNanoseconds (bigint).
Abrunden statt Abschneiden: Vor 1970 wird Richtung minus unendlich gerundet. Aus −0,5 ms wird also -1 und nicht 0. Das ist dasselbe wie Math.floor, aber nicht dasselbe wie Math.trunc.
Nur lesbar: Eine Zuweisung wie instant.epochMilliseconds = 0 wird im Sloppy-Mode stillschweigend ignoriert und löst im Strict-Mode einen TypeError aus.
Keine Sekunden: Die Eigenschaft epochSeconds aus frühen Entwürfen des Vorschlags wurde entfernt. Für Unix-Sekunden rechnest du Math.floor(instant.epochMilliseconds / 1000).
Kompatibilität: Temporal ist neu. Nativ wird es bisher nur in aktuellen Firefox- und Chromium-Versionen unterstützt, Safari und ältere Node.js-Versionen haben es noch nicht. Für den Einsatz in Produktion solltest du ein Polyfill wie @js-temporal/polyfill oder temporal-polyfill verwenden oder die Unterstützung mit typeof Temporal !== \"undefined\" prüfen.

Siehe auch

Temporal.Instant Temporal.Instant.prototype.epochNanoseconds Temporal.Instant.fromEpochMilliseconds() Temporal.Now.instant() Date.now() Date.prototype.getTime() Date.prototype.toTemporalInstant()