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

Signatur

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

Beschreibung

Mit with() ersetzen Sie gezielt einzelne Bestandteile eines Kalenderdatums. Die übrigen Felder werden vom Ausgangsdatum übernommen. Weil Temporal.PlainDate unveränderlich ist, bleibt das ursprüngliche Objekt unverändert. Sie erhalten immer eine neue Instanz zurück.

Typische Anwendungen sind etwa „derselbe Tag in einem anderen Jahr“, „der Erste oder Letzte des Monats“ oder „Stichtag auf den 15. setzen“. Anders als add() rechnet with() nicht mit Zeitspannen, sondern überschreibt Felder. date.with({ month: 3 }) bedeutet also „März“ und nicht „drei Monate später“.

Die erkannten Felder hängen vom Kalender ab. Im ISO-8601-Kalender sind das year, month, monthCode und day. In Kalendern mit Epochen (z. B. gregory oder japanese) kommen era und eraYear hinzu. Führt die Kombination der Felder zu einem ungültigen Datum (z. B. 31. Februar), bestimmt die Option overflow, ob der Wert in den gültigen Bereich gezogen oder ein Fehler geworfen wird.

Kalender und Zeitzone lassen sich mit with() nicht ändern. Für einen Kalenderwechsel gibt es withCalendar(). Eine Uhrzeit ergänzen Sie mit toPlainDateTime().

Parameter

Name	Typ	Default	Beschreibung
$info Pflicht	object		Objekt mit mindestens einem erkannten Datumsfeld: `year`, `month`, `monthCode`, `day` sowie je nach Kalender `era` und `eraYear`. Die Eigenschaften `calendar` und `timeZone` sind nicht erlaubt.
$options	object	undefined	Optionales Objekt mit der Eigenschaft `overflow`: `"constrain"` (Standard, zieht ungültige Werte in den gültigen Bereich) oder `"reject"` (wirft einen `RangeError`).

Rückgabewert

Typ

Temporal.PlainDate

Beschreibung

Ein neues Temporal.PlainDate mit denselben Feldern wie das Ausgangsdatum, außer den in info angegebenen Feldern, die ersetzt werden. Der Kalender bleibt erhalten.

Beispiele

Einzelne Felder ersetzen

const geburtstag = Temporal.PlainDate.from("1990-07-15");

// Derselbe Tag im Jahr 2025
const diesesJahr = geburtstag.with({ year: 2025 });
console.log(diesesJahr.toString());

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

2025-07-15 1990-07-15

Erster und letzter Tag des Monats

const heute = Temporal.PlainDate.from("2024-02-10");

const monatsanfang = heute.with({ day: 1 });
const monatsende = heute.with({ day: heute.daysInMonth });

console.log(monatsanfang.toString(), monatsende.toString());

2024-02-01 2024-02-29

Überlauf: constrain vs. reject

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

// Standard "constrain": 31. Februar wird zum 28. Februar
console.log(datum.with({ month: 2 }).toString());

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

2023-02-28 RangeError

Fälligkeitsdatum auf den 15. des Folgemonats setzen

const rechnungsdatum = Temporal.PlainDate.from("2024-11-28");

// Erst einen Monat addieren (rechnen), dann den Tag ersetzen (with)
const faellig = rechnungsdatum.add({ months: 1 }).with({ day: 15 });

console.log(`Zahlbar bis ${faellig.toLocaleString("de-DE")}`);

Zahlbar bis 15.12.2024

// Wichtig · Fallstricke

Kein Rechnen: with({ month: date.month + 1 }) schlägt im Dezember fehl, denn Monat 13 wird mit constrain zu 12, mit reject kommt ein RangeError. Für relative Änderungen verwenden Sie add() bzw. subtract().
Ist info kein Objekt oder enthält es kein erkanntes Feld, wird ein TypeError geworfen. Das gilt auch, wenn calendar oder timeZone enthalten sind.
Geben Sie month und monthCode gleichzeitig an und passen sie nicht zusammen, gibt es einen RangeError. In Kalendern mit Schaltmonaten (z. B. hebrew oder chinese) ist monthCode eindeutiger als month.
Auch mit constrain wird ein RangeError geworfen, wenn das Ergebnis außerhalb des von Temporal unterstützten Datumsbereichs liegt (etwa ±270.000 Jahre).
Kompatibilität: Temporal ist neu und noch nicht in allen Engines verfügbar (z. B. Safari und ältere Node.js-Versionen). Für den produktiven Einsatz empfiehlt sich ein Polyfill wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.PlainDate Temporal.PlainDate.prototype.add() Temporal.PlainDate.prototype.subtract() Temporal.PlainDate.prototype.withCalendar() Temporal.PlainDate.from() Temporal.PlainDateTime.prototype.with()