Signatur
Beschreibung
with() erzeugt eine abgeänderte Kopie eines Temporal.PlainYearMonth. Sie geben nur die Felder an, die sich ändern sollen, z. B. { month: 12 }. Alle anderen Felder übernimmt die Methode aus dem Ausgangsobjekt. Das Original bleibt unverändert, denn alle Temporal-Objekte sind unveränderlich (immutable).
Die Methode eignet sich, um Felder absolut zu setzen, etwa „Dezember desselben Jahres“ oder „gleicher Monat im Jahr 2030“. Wenn Sie relativ rechnen wollen, etwa „drei Monate später“, verwenden Sie stattdessen add() bzw. subtract(). Diese Methoden kümmern sich um den Übertrag ins nächste Jahr, with() nicht.
Erlaubte Felder sind year, month, monthCode sowie in Kalendern mit Epochen (Ären) era und eraYear. Den Kalender können Sie mit with() nicht ändern. Dafür gibt es bei PlainYearMonth keine eigene Methode: Sie wandeln das Objekt mit toPlainDate() in ein Datum um und rufen dann withCalendar() auf. Die Option overflow legt fest, was mit ungültigen Werten passiert: Entweder werden sie auf den gültigen Bereich begrenzt oder es wird ein Fehler geworfen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $info Pflicht | Object | Objekt mit mindestens einem der Felder year, month, monthCode, era, eraYear. Die Eigenschaften calendar und timeZone sind nicht erlaubt und führen zu einem TypeError. |
|
| $options | Object | undefined | Optionales Objekt mit der Eigenschaft overflow: "constrain" (Standard) begrenzt Werte außerhalb des gültigen Bereichs auf den nächsten gültigen Wert, "reject" wirft stattdessen einen RangeError. |
Rückgabewert
Temporal.PlainYearMonth mit den ersetzten Feldern. Der Kalender ist derselbe wie beim Ausgangsobjekt.Beispiele
Einzelne Felder ersetzen
const ym = Temporal.PlainYearMonth.from("2024-05");
console.log(ym.with({ year: 2025 }).toString());
console.log(ym.with({ month: 12 }).toString());
console.log(ym.with({ year: 2030, month: 1 }).toString());
// Das Original bleibt unverändert
console.log(ym.toString());Überlauf: constrain vs. reject
const ym = Temporal.PlainYearMonth.from("2024-05");
// Standard: auf gültigen Bereich begrenzen
console.log(ym.with({ month: 13 }).toString());
try {
ym.with({ month: 13 }, { overflow: "reject" });
} catch (err) {
console.log(err.constructor.name);
}Praxis: Monatsauswahl für ein Geschäftsjahr erzeugen
// Alle Monate des Jahres, in dem ein Abrechnungsmonat liegt
const abrechnung = Temporal.PlainYearMonth.from("2025-08");
const monate = Array.from({ length: 12 }, (_, i) =>
abrechnung.with({ month: i + 1 })
);
console.log(monate.map((m) => m.toString()).join(", "));
// Jahresabschluss = Dezember desselben Jahres
const abschluss = abrechnung.with({ month: 12 });
console.log(abschluss.toLocaleString("de-DE", { month: "long", year: "numeric" }));// Wichtig · Fallstricke
- Kein relatives Rechnen:
with({ month: ym.month + 1 })springt nicht ins nächste Jahr. Aus Dezember wird mitconstrainwieder Dezember. Für „nächster Monat“ verwenden Sieym.add({ months: 1 }). monthundmonthCodegemeinsam: Wenn Sie beide Felder angeben, müssen sie denselben Monat bezeichnen, sonst wird einRangeErrorgeworfen. In Kalendern mit Schaltmonaten, etwa dem hebräischen, istmonthCode(z. B.\"M05L\") eindeutiger als die fortlaufende Nummermonth.- Fehlerfälle: Ein
TypeErrorentsteht, wenninfokein Objekt ist, kein erkanntes Feld enthält odercalendarbzw.timeZoneenthält. Wenn Sie einen String übergeben, etwaym.with(\"2025-01\"), wird er nicht geparst, sondern mit einem Fehler abgelehnt. - Kompatibilität: Temporal ist noch nicht in allen Engines verfügbar (Safari, ältere Chrome- und Node.js-Versionen). Für den produktiven Einsatz eignen sich Polyfills wie
@js-temporal/polyfillodertemporal-polyfill.