Signatur
Beschreibung
Die Methode add() rechnet eine Dauer auf einen Jahr-Monat-Wert wie 2024-05 auf und gibt das Ergebnis als neues Temporal.PlainYearMonth-Objekt zurück. Das Original ändert sich nicht, denn alle Temporal-Objekte sind unveränderlich.
Typische Einsatzfälle sind Abrechnungszeiträume, Monatsübersichten, Laufzeiten von Verträgen oder Kreditkarten-Ablaufdaten, also überall dort, wo der Tag keine Rolle spielt. Anders als bei Date gibt es hier keine Überläufe wie „31. Januar + 1 Monat = 3. März“, weil gar kein Tag gespeichert wird.
Die Dauer kann als Temporal.Duration, als einfaches Objekt (z. B. { years: 1, months: 3 }) oder als ISO-8601-Dauer-String (z. B. "P1Y3M") übergeben werden. Negative Werte ziehen ab. Das entspricht dann subtract() mit der positiven Dauer.
Sinnvoll sind nur die Einheiten years und months. Kleinere Einheiten (Wochen, Tage, Stunden …) werden intern vom ersten Tag des Monats aus gerechnet (bei negativer Dauer vom letzten Tag aus) und führen nur dann zu einem anderen Ergebnis, wenn sie einen ganzen Monat überschreiten.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $duration Pflicht | Temporal.Duration | object | string | Die Dauer, die addiert werden soll: eine Temporal.Duration-Instanz, ein Objekt mit Feldern wie years und months oder ein ISO-8601-Dauer-String wie "P2M". Negative Werte ziehen ab. |
|
| $options | object | {} | Optionales Objekt mit der Eigenschaft overflow. |
| $options.overflow | "constrain" | "reject" | "constrain" | Legt fest, wie mit ungültigen Ergebnissen umgegangen wird. Bei "constrain" wird auf den nächsten gültigen Wert begrenzt, bei "reject" wird ein RangeError geworfen. Relevant ist das vor allem bei Nicht-ISO-Kalendern, zum Beispiel bei Schaltmonaten im hebräischen Kalender. |
Rückgabewert
Temporal.PlainYearMonth-Objekt mit dem verschobenen Jahr-Monat im selben Kalender wie das Original.Beispiele
Monate und Jahre addieren
const start = Temporal.PlainYearMonth.from("2024-11");
console.log(start.add({ months: 3 }).toString());
console.log(start.add({ years: 1, months: 2 }).toString());
// ISO-8601-Dauer-String
console.log(start.add("P13M").toString());
// Original bleibt unverändert
console.log(start.toString());Negative Dauer: Monate zurückrechnen
const aktuell = Temporal.PlainYearMonth.from({ year: 2024, month: 2 });
const vorQuartal = aktuell.add({ months: -3 });
console.log(vorQuartal.toString());
// Gleiches Ergebnis wie subtract()
console.log(aktuell.subtract({ months: 3 }).equals(vorQuartal));Abrechnungsmonate einer Vertragslaufzeit erzeugen
const vertragsBeginn = Temporal.PlainYearMonth.from("2025-10");
const laufzeit = Temporal.Duration.from({ months: 1 });
const abrechnungsMonate = [];
let monat = vertragsBeginn;
for (let i = 0; i < 4; i++) {
abrechnungsMonate.push(monat.toLocaleString("de-DE", { month: "long", year: "numeric" }));
monat = monat.add(laufzeit);
}
console.log(abrechnungsMonate);Ablaufdatum einer Kreditkarte prüfen
const ausgestellt = Temporal.PlainYearMonth.from("2023-06");
const gueltigBis = ausgestellt.add({ years: 3 });
const heute = Temporal.Now.plainDateISO().toPlainYearMonth();
const abgelaufen = Temporal.PlainYearMonth.compare(heute, gueltigBis) > 0;
console.log(`Gültig bis ${gueltigBis}, abgelaufen: ${abgelaufen}`);