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

Signatur

Temporal.PlainDate.prototype.add(duration, options)

Beschreibung

add() rechnet eine Dauer auf ein reines Kalenderdatum (ohne Uhrzeit und ohne Zeitzone) auf. Die Dauer kann als Temporal.Duration, als einfaches Objekt wie { months: 1, days: 3 } oder als ISO-8601-Dauer-String wie "P1M3D" übergeben werden. Alles, was Temporal.Duration.from() versteht, ist erlaubt.

Die Methode verändert das ursprüngliche Objekt nicht, denn alle Temporal-Objekte sind unveränderlich. Stattdessen gibt sie immer eine neue Instanz zurück. Deshalb eignet sie sich gut für Fälligkeitsdaten, Abo-Laufzeiten, Fristen oder Kalenderansichten, also überall dort, wo man früher mit Date.prototype.setDate() und fehleranfälligen Monatsberechnungen gearbeitet hat.

Die Reihenfolge der Berechnung ist festgelegt:

Zuerst werden Jahre und Monate addiert.
Gibt es den Tag danach nicht (z. B. 31. Februar), greift die Option overflow.
Danach werden Wochen und Tage addiert.

Zeiteinheiten wie Stunden oder Minuten werden in ganze Tage umgerechnet. Ein Rest, der keinen ganzen Tag ergibt, wird ignoriert.

Eine negative Dauer entspricht einem Aufruf von subtract() mit der positiven Dauer. Das Ergebnis behält den Kalender des Ausgangsdatums. Bei anderen Kalendern als iso8601 richten sich die Längen von Monaten und Jahren nach diesem Kalender.

Parameter

Name	Typ	Default	Beschreibung
$duration Pflicht	Temporal.Duration \| object \| string		Die Dauer, die addiert wird: eine `Temporal.Duration`, ein Objekt mit Feldern wie `years`, `months`, `weeks` und `days` oder ein ISO-8601-String wie `"P2W"`. Wird intern mit `Temporal.Duration.from()` umgewandelt.
$options	object	{}	Objekt mit Optionen.
$options.overflow	"constrain" \| "reject"	"constrain"	Legt fest, was passiert, wenn das Ergebnis nach der Addition von Jahren und Monaten einen ungültigen Tag hätte. `"constrain"` setzt den Tag auf den letzten gültigen Tag des Monats. `"reject"` wirft einen `RangeError`.

Rückgabewert

Typ

Temporal.PlainDate

Beschreibung

Ein neues Temporal.PlainDate mit dem berechneten Datum im selben Kalender wie das Ausgangsdatum.

Beispiele

Tage und Wochen addieren

const start = Temporal.PlainDate.from("2024-03-15");

console.log(start.add({ days: 10 }).toString());
console.log(start.add({ weeks: 2 }).toString());
console.log(start.add("P1Y").toString());

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

2024-03-25 2024-03-29 2025-03-15 2024-03-15

Monatsende: overflow "constrain" oder "reject"

const endOfJanuary = Temporal.PlainDate.from("2023-01-31");

// Standard: auf den letzten gültigen Tag setzen
console.log(endOfJanuary.add({ months: 1 }).toString());

try {
  endOfJanuary.add({ months: 1 }, { overflow: "reject" });
} catch (err) {
  console.log(err instanceof RangeError);
}

2023-02-28 true

Fälligkeitsdatum einer Rechnung berechnen

const createDueDate = (invoiceDate, paymentTermDays = 30) =>
  Temporal.PlainDate.from(invoiceDate).add({ days: paymentTermDays });

const due = createDueDate("2024-12-10");
console.log(due.toString());
console.log(due.toLocaleString("de-DE", { dateStyle: "full" }));

2025-01-09 Donnerstag, 9. Januar 2025

Reihenfolge: erst Monate, dann Tage; Stunden werden abgerundet

const d = Temporal.PlainDate.from("2024-01-31");

// 1 Monat → 2024-02-29 (constrain), danach + 14 Tage
console.log(d.add("P1M2W").toString());

// 36 Stunden = 1 ganzer Tag, die restlichen 12 Stunden fallen weg
console.log(d.add({ hours: 36 }).toString());

// Negative Dauer = zurückrechnen
console.log(d.add({ months: -1 }).toString());

2024-03-14 2024-02-01 2023-12-31

// Wichtig · Fallstricke

Browser-Unterstützung: Temporal ist noch nicht überall verfügbar (Safari fehlt bisher). Für den produktiven Einsatz sollte man vorher prüfen, ob das Objekt existiert (typeof Temporal !== \"undefined\"), oder einen Polyfill wie @js-temporal/polyfill verwenden.
Nicht umkehrbar: date.add({ months: 1 }).subtract({ months: 1 }) ergibt nicht immer das Ausgangsdatum. Beispiel: 31.01. → 28.02. → 28.01. Wer Abstände zwischen zwei Daten braucht, nimmt besser until() bzw. since().
Nicht beliebig zerlegbar: add({ months: 1, days: 1 }) kann ein anderes Ergebnis liefern als zwei getrennte Aufrufe in umgekehrter Reihenfolge (erst Tage, dann Monate).
Zeiteinheiten: Stunden, Minuten und kleinere Einheiten werden nur als ganze Tage berücksichtigt. Wer mit Uhrzeiten rechnen will, sollte Temporal.PlainDateTime oder Temporal.ZonedDateTime verwenden.
Wertebereich: Liegt das Ergebnis außerhalb des darstellbaren Bereichs (ca. ±275.760 Jahre), wird ein RangeError geworfen. Eine ungültige Dauer, z. B. mit gemischten Vorzeichen, führt ebenfalls zu einem RangeError.
Kein Seiteneffekt: Das Ergebnis muss man zuweisen. Ein bloßer Aufruf date.add(...) ohne Zuweisung hat keine Wirkung.

Siehe auch

Temporal.PlainTime.prototype.add() Temporal.PlainDate.prototype.with() Temporal.PlainDateTime.prototype.add() Temporal.PlainDate.prototype.equals() Temporal.PlainDate.prototype.since() Temporal.PlainDate.prototype.valueOf()