Temporal.Instant.prototype.add() — Methode · JavaScript-Referenz

Signatur

Temporal.Instant.prototype.add(duration)

Beschreibung

Die Methode add() verschiebt einen exakten Zeitpunkt auf der Zeitachse um eine feste Zeitspanne nach vorn. Weil Temporal.Instant weder Zeitzone noch Kalender kennt, sind nur exakte Zeiteinheiten erlaubt: hours, minutes, seconds, milliseconds, microseconds und nanoseconds. Die Rechnung ist auf die Nanosekunde genau.

Die Dauer kannst du als Temporal.Duration-Instanz, als Objekt wie { hours: 2, minutes: 30 } oder als ISO-8601-Dauerstring wie "PT2H30M" übergeben. Sie wird intern mit Temporal.Duration.from() umgewandelt. Bei einer negativen Dauer bewegt sich der Zeitpunkt zurück. instant.add(d) liefert also dasselbe wie instant.subtract(d.negated()).

Wie alle Temporal-Objekte ist Temporal.Instant unveränderlich: Das ursprüngliche Objekt bleibt gleich, du bekommst immer eine neue Instanz zurück. Typische Einsätze sind Ablaufzeiten für Tokens und Caches, Timeouts oder Zeitstempel in Logs, also überall, wo es um exakte Zeitabstände geht und die Uhrzeit vor Ort keine Rolle spielt.

Parameter

Name	Typ	Default	Beschreibung
$duration Pflicht	Temporal.Duration \| object \| string		Die Dauer, die addiert wird. Möglich sind eine `Temporal.Duration`, ein Objekt mit Dauer-Feldern (z. B. `{ minutes: 15 }`) oder ein ISO-8601-String (z. B. `"PT15M"`). `years`, `months`, `weeks` und `days` müssen 0 sein.

Rückgabewert

Typ

Temporal.Instant

Beschreibung

Eine neue Temporal.Instant-Instanz für den Zeitpunkt this + duration.

Beispiele

Stunden und Minuten addieren

const start = Temporal.Instant.from("2024-01-01T00:00:00Z");

const later = start.add({ hours: 1, minutes: 30 });
console.log(later.toString());

// Das Original bleibt unverändert
console.log(start.toString());

2024-01-01T01:30:00Z 2024-01-01T00:00:00Z

ISO-Dauerstring und Nanosekunden-Genauigkeit

const t = Temporal.Instant.from("2024-06-15T12:00:00Z");

console.log(t.add("PT48H").toString());          // 48 Stunden sind erlaubt
console.log(t.add({ nanoseconds: 1 }).toString());
console.log(t.add({ minutes: -10 }).toString());  // negative Dauer: zurück

2024-06-17T12:00:00Z 2024-06-15T12:00:00.000000001Z 2024-06-15T11:50:00Z

Ablaufzeit eines Tokens berechnen

const TOKEN_TTL = Temporal.Duration.from({ minutes: 15 });

const issueToken = () => {
  const issuedAt = Temporal.Now.instant();
  return { issuedAt, expiresAt: issuedAt.add(TOKEN_TTL) };
};

const isExpired = (token) =>
  Temporal.Instant.compare(Temporal.Now.instant(), token.expiresAt) >= 0;

const token = issueToken();
console.log(isExpired(token));

false

Tage sind nicht erlaubt: RangeError und Ausweg

const t = Temporal.Instant.from("2024-03-30T12:00:00Z");

try {
  t.add({ days: 1 });
} catch (err) {
  console.log(err instanceof RangeError);
}

// Ausweg: feste 24 Stunden ...
console.log(t.add({ hours: 24 }).toString());

// ... oder Kalendertage in einer bestimmten Zeitzone
const nextDay = t.toZonedDateTimeISO("Europe/Berlin").add({ days: 1 }).toInstant();
console.log(nextDay.toString());

true 2024-03-31T12:00:00Z 2024-03-31T11:00:00Z

// Wichtig · Fallstricke

Keine Kalendereinheiten: Enthält die Dauer years, months, weeks oder days mit einem Wert ungleich 0, wird ein RangeError geworfen. Ein „Tag“ ist ohne Zeitzone nicht eindeutig, denn bei der Zeitumstellung dauert er 23 oder 25 Stunden. Für Kalenderrechnung nimm Temporal.ZonedDateTime.
Wertebereich: Liegt das Ergebnis außerhalb des erlaubten Bereichs von ±10⁸ Tagen um die Unix-Epoche, gibt es ebenfalls einen RangeError.
Ungültige Eingaben: Ein Objekt ohne ein einziges bekanntes Dauer-Feld führt zu einem TypeError. Ein falsch formatierter String führt zu einem RangeError.
Unveränderlichkeit: add() ändert das Objekt nicht. Du musst den Rückgabewert verwenden, instant.add(...) allein bewirkt nichts.
Browser-Unterstützung: Temporal ist neu und wird bisher nur von Firefox (ab 139) und Chromium-Browsern (ab 144) unterstützt, nicht aber von Safari. In älteren Umgebungen hilft ein Polyfill wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.Instant.prototype.subtract() Temporal.Instant.prototype.until() Temporal.Instant.prototype.since() Temporal.Instant Temporal.Duration.from() Temporal.ZonedDateTime.prototype.add()