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

Signatur

new Temporal.Instant(epochNanoseconds)

Beschreibung

Der Konstruktor Temporal.Instant() erzeugt einen exakten Zeitpunkt auf der globalen Zeitachse. Er hat weder Zeitzone noch Kalender. Intern speichert er nur einen Wert: die Anzahl der Nanosekunden seit dem 1. Januar 1970, 00:00:00 UTC. Deshalb erwartet der Konstruktor genau diesen Wert als BigInt.

Den Konstruktor direkt nutzen Sie vor allem, wenn Sie bereits einen Zeitstempel in Nanosekunden haben, etwa aus einer Datenbank, einem Log-System, OpenTelemetry-Traces oder einem Binärprotokoll. In anderen Fällen gibt es passendere Fabrikmethoden:

Temporal.Instant.from() für ISO-8601-Zeichenketten wie "2024-03-10T12:00:00Z"
Temporal.Instant.fromEpochMilliseconds() für Millisekunden-Werte (z. B. aus Date.now())
Temporal.Now.instant() für den aktuellen Zeitpunkt

Der Konstruktor muss mit new aufgerufen werden. Das entstehende Objekt ist unveränderlich: Methoden wie add() oder round() geben immer ein neues Temporal.Instant zurück.

Parameter

Name	Typ	Default	Beschreibung
$epochNanoseconds Pflicht	bigint		Nanosekunden seit der Unix-Epoche (1970-01-01T00:00:00Z). Negative Werte stehen für Zeitpunkte vor 1970. Erlaubt sind Werte von `-8.64e21` bis `8.64e21` Nanosekunden, das sind ±100.000.000 Tage.

Rückgabewert

Typ

Temporal.Instant

Beschreibung

Ein neues, unveränderliches Temporal.Instant-Objekt für den angegebenen Zeitpunkt.

Beispiele

Die Unix-Epoche als Instant

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

1970-01-01T00:00:00Z 0

Nanosekunden-Zeitstempel aus einem Log-System einlesen

// Zeitstempel eines Trace-Spans, z. B. aus OpenTelemetry
const rawTimestamp = "1700000000123456789";

const instant = new Temporal.Instant(BigInt(rawTimestamp));
console.log(instant.toString());

// In einer Zeitzone darstellen
const berlin = instant.toZonedDateTimeISO("Europe/Berlin");
console.log(berlin.toPlainTime().toString());

2023-11-14T22:13:20.123456789Z 23:13:20.123456789

Aus Millisekunden (Date) umrechnen

const ms = Date.UTC(2024, 0, 1); // 1. Januar 2024, 00:00 UTC

// Millisekunden → Nanosekunden: mit 1.000.000 multiplizieren
const instant = new Temporal.Instant(BigInt(ms) * 1_000_000n);
console.log(instant.toString());

// Gleichwertig und besser lesbar:
console.log(Temporal.Instant.fromEpochMilliseconds(ms).equals(instant));

2024-01-01T00:00:00Z true

Fehler bei falschem Typ und außerhalb des Wertebereichs

const tryCreate = (value) => {
  try {
    return new Temporal.Instant(value).toString();
  } catch (err) {
    return `${err.name}`;
  }
};

console.log(tryCreate(1000));  // Number statt BigInt
console.log(tryCreate(8_640_000_000_000_000_000_001n)); // zu groß
console.log(tryCreate(8_640_000_000_000_000_000_000n)); // größter erlaubter Wert

TypeError RangeError +275760-09-13T00:00:00Z

// Wichtig · Fallstricke

Nur BigInt: Eine normale Zahl wie new Temporal.Instant(1000) löst einen TypeError aus. Nutzen Sie das Suffix n oder wandeln Sie mit BigInt(...) um. Achtung: BigInt(1.5) wirft ebenfalls einen Fehler.
Einheit verwechselt: Der Wert wird in Nanosekunden angegeben, nicht in Millisekunden wie bei Date. Übergeben Sie Millisekunden, landen Sie ungefähr im Januar 1970. Für Millisekunden gibt es Temporal.Instant.fromEpochMilliseconds().
Wertebereich: Werte über ±8.64e21 ns führen zu einem RangeError. Das entspricht dem Bereich von Date.
Nur mit new: Ein Aufruf als normale Funktion wirft einen TypeError.
Keine Zeitzone: Ein Instant hat weder Zeitzone noch Kalender. Für Datum und Uhrzeit vor Ort brauchen Sie toZonedDateTimeISO().
Kompatibilität: Temporal ist noch nicht in allen Umgebungen verfügbar: Firefox ab 139, Chromium-Browser ab 144, Safari und ältere Node.js-Versionen noch nicht. Als Ersatz dient z. B. das Polyfill @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

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