Temporal.PlainMonthDay.prototype.with() — Methode · JavaScript-Referenz

Signatur

Temporal.PlainMonthDay.prototype.with(info, options)

Beschreibung

with() erzeugt eine geänderte Kopie eines Temporal.PlainMonthDay-Objekts. Alle Temporal-Objekte sind unveränderlich (immutable). Deshalb ändert man keine Eigenschaften direkt, sondern gibt nur die Felder an, die sich ändern sollen. Alle anderen Felder werden aus dem Ausgangsobjekt übernommen.

Typische Einsatzfälle sind wiederkehrende Kalendertermine ohne Jahr, etwa Geburtstage, Jahrestage oder Feiertage wie „24.12.“. Mit with({ day: 26 }) lässt sich daraus zum Beispiel direkt ein anderer Tag im selben Monat ableiten.

Erlaubte Felder sind month, monthCode, day und optional year (bei Nicht-ISO-Kalendern außerdem era/eraYear). Das Jahr wird im Ergebnis nicht gespeichert. Es dient nur dazu, den Tag zu prüfen. Wird z. B. year: 2021 zusammen mit dem 29. Februar angegeben, wird der Tag auf den 28. begrenzt. Ohne Jahr gilt im ISO-Kalender der 29. Februar als gültig, weil intern das Schaltjahr 1972 als Referenzjahr dient.

Ungültige Werte wie day: 31 im April werden standardmäßig auf den nächsten gültigen Wert begrenzt (overflow: "constrain"). Mit overflow: "reject" wird stattdessen ein RangeError ausgelöst. Das ist sinnvoll, wenn Eingaben von Nutzern streng geprüft werden sollen.

Parameter

Name	Typ	Default	Beschreibung
$info Pflicht	Object		Objekt mit mindestens einem der Felder `month`, `monthCode`, `day`, `year` (bzw. `era`/`eraYear`). Die Eigenschaften `calendar` und `timeZone` sind nicht erlaubt.
$options	Object	undefined	Optionales Objekt mit der Eigenschaft `overflow`: `"constrain"` (Standard; ungültige Werte werden auf den nächsten gültigen Wert begrenzt) oder `"reject"` (bei ungültigen Werten wird ein `RangeError` ausgelöst).

Rückgabewert

Typ

Temporal.PlainMonthDay

Beschreibung

Ein neues Temporal.PlainMonthDay-Objekt mit den ersetzten Feldern. Das Ausgangsobjekt bleibt unverändert.

Beispiele

Einzelnes Feld ersetzen

const heiligabend = Temporal.PlainMonthDay.from("12-24");
const zweiterFeiertag = heiligabend.with({ day: 26 });

console.log(heiligabend.toString());      // Original bleibt unverändert
console.log(zweiterFeiertag.toString());

12-24 12-26

Überlauf: constrain vs. reject

const termin = Temporal.PlainMonthDay.from("03-31");

// Standard: Der 31. April wird auf den 30. begrenzt
console.log(termin.with({ month: 4 }).toString());

try {
  termin.with({ month: 4 }, { overflow: "reject" });
} catch (err) {
  console.log(err.constructor.name);
}

04-30 RangeError

29. Februar mit und ohne Jahresangabe

const md = Temporal.PlainMonthDay.from("02-01");

// Ohne Jahr: gültig, weil das Referenzjahr 1972 ein Schaltjahr ist
console.log(md.with({ day: 29 }).toString());

// Mit Nicht-Schaltjahr: Tag wird auf den 28. begrenzt
console.log(md.with({ year: 2021, day: 29 }).toString());

02-29 02-28

Praxis: Geburtstag verschieben und in einem Jahr konkretisieren

const geburtstag = Temporal.PlainMonthDay.from({ month: 5, day: 14 });
const korrigiert = geburtstag.with({ day: 15 });

// Datum im nächsten Jahr berechnen
const jahr = Temporal.Now.plainDateISO().year + 1;
const datum = korrigiert.toPlainDate({ year: jahr });
console.log(datum.dayOfWeek >= 6 ? "Wochenende" : "Werktag");

Werktag oder Wochenende (abhängig vom Jahr)

// Wichtig · Fallstricke

Unveränderlich: with() gibt immer ein neues Objekt zurück. Der Aufruf md.with({...}) ohne Zuweisung des Ergebnisses hat keine Wirkung.
Enthält info die Eigenschaft calendar oder timeZone oder ist es kein Objekt (z. B. ein String), wird ein TypeError ausgelöst. Den Kalender wechselt man stattdessen mit Temporal.PlainMonthDay.from().
Ein leeres Objekt {} ohne bekannte Felder löst ebenfalls einen TypeError aus.
month und monthCode müssen übereinstimmen, wenn beide angegeben sind (z. B. month: 3 und monthCode: \"M03\"). Andernfalls wird ein RangeError ausgelöst. Bei Nicht-ISO-Kalendern mit Schaltmonaten (z. B. dem hebräischen) ist monthCode eindeutiger.
Die Angabe year wird nicht gespeichert, sondern nur zur Prüfung des Tages verwendet.
Kompatibilität: Temporal ist noch nicht in allen Browsern verfügbar (Stand: Firefox 139+, Chromium 144+, Safari noch nicht). Für ältere Umgebungen und Node.js eignet sich ein Polyfill wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.PlainMonthDay Temporal.PlainMonthDay.from() Temporal.PlainMonthDay.prototype.toPlainDate() Temporal.PlainMonthDay.prototype.equals() Temporal.PlainDate.prototype.with() Temporal.PlainYearMonth.prototype.with() Temporal.PlainMonthDay.prototype.valueOf()