Signatur
Beschreibung
subtract() zieht eine Zeitspanne von einem Kalenderdatum ohne Uhrzeit und ohne Zeitzone ab. Die Dauer kann als Temporal.Duration, als Objekt wie { months: 1, days: 3 } oder als ISO-8601-Dauerstring wie "P1M3D" übergeben werden. Alles, was Temporal.Duration.from() akzeptiert, ist erlaubt.
Wie alle Temporal-Objekte ist PlainDate unveränderlich. Die Methode gibt also immer ein neues Objekt zurück. Ein Aufruf von date.subtract(d) liefert dasselbe Ergebnis wie date.add(d.negated()).
Die Einheiten werden kalenderbewusst in fester Reihenfolge verrechnet: zuerst Jahre, dann Monate, danach Wochen und Tage. Ist das Zwischenergebnis ungültig, etwa der 31. Februar, entscheidet die Option overflow:
"constrain"(Standard): Das Datum wird auf den letzten gültigen Tag gesetzt."reject": Es wird einRangeErrorgeworfen.
Zeitanteile der Dauer (Stunden, Minuten, …) werden zu ganzen Tagen zusammengefasst, wobei ein Tag 24 Stunden hat. Reste unter einem Tag werden ignoriert.
Typische Einsatzfälle sind Fristberechnungen („30 Tage vor Fälligkeit“), Kalenderansichten („vorheriger Monat“) und Berichte über Zeiträume. Anders als bei Date gibt es dabei keine Probleme mit Zeitzonen oder Sommerzeit.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $duration Pflicht | Temporal.Duration | object | string | Die abzuziehende Zeitspanne: eine Temporal.Duration, ein Objekt mit Feldern wie years, months, weeks, days oder ein ISO-8601-String wie "P1Y2M". Eine negative Dauer verschiebt das Datum in die Zukunft. |
|
| $options | object | { overflow: "constrain" } | Optionales Objekt mit der Eigenschaft overflow: "constrain" setzt ungültige Tage auf den letzten gültigen Tag, "reject" wirft stattdessen einen RangeError. |
Rückgabewert
Temporal.PlainDate, das um duration früher liegt. Das ursprüngliche Objekt bleibt unverändert.Beispiele
Tage, Wochen und Monate abziehen
const heute = Temporal.PlainDate.from("2024-05-15");
console.log(heute.subtract({ days: 10 }).toString());
console.log(heute.subtract({ weeks: 2 }).toString());
console.log(heute.subtract("P1Y2M").toString()); // ISO-Dauerstring
console.log(heute.toString()); // Original bleibt unverändertMonatsende: constrain vs. reject
const datum = Temporal.PlainDate.from("2021-03-31");
// Standard: auf den letzten gültigen Tag setzen
console.log(datum.subtract({ months: 1 }).toString());
try {
datum.subtract({ months: 1 }, { overflow: "reject" });
} catch (err) {
console.log(err.constructor.name);
}Frist berechnen: Erinnerung 30 Tage vor Fälligkeit
const faelligkeit = Temporal.PlainDate.from("2025-01-15");
const erinnerung = faelligkeit.subtract({ days: 30 });
const heute = Temporal.Now.plainDateISO();
const jetztErinnern = Temporal.PlainDate.compare(heute, erinnerung) >= 0;
console.log(`Erinnerung ab: ${erinnerung.toLocaleString("de-DE")}`);
console.log(`Jetzt erinnern? ${jetztErinnern}`);Schaltjahr und Reihenfolge der Einheiten
const schalttag = Temporal.PlainDate.from("2024-02-29");
console.log(schalttag.subtract({ years: 1 }).toString());
// Zuerst Monate, dann Tage: 31.03. − 1 Monat → 28.02., dann − 1 Tag
const d = Temporal.PlainDate.from("2021-03-31");
console.log(d.subtract({ months: 1, days: 1 }).toString());
// Zeitanteile werden zu ganzen Tagen zusammengefasst
console.log(d.subtract({ hours: 50 }).toString());// Wichtig · Fallstricke
Browser-Unterstützung: Temporal ist noch recht neu (seit Firefox 139 und Chrome 144). Safari und ältere Umgebungen brauchen einen Polyfill wie @js-temporal/polyfill. Vorab prüfen mit typeof Temporal !== \"undefined\".
- Nicht umkehrbar: Weil am Monatsende auf den letzten gültigen Tag gesetzt wird, gilt
d.subtract(x).add(x)nicht immer gleichd. So wird 2021-03-31 minus 1 Monat zu 2021-02-28, plus 1 Monat dann zu 2021-03-28. - Rückgabewert verwenden:
date.subtract(...)ändertdatenicht. Wer den Rückgabewert verwirft, erhält kein Ergebnis. - Zeitanteile: Stunden, Minuten usw. zählen nur, soweit sie zusammen ganze 24-Stunden-Tage ergeben. Für Uhrzeiten eignen sich
Temporal.PlainDateTimeoderTemporal.ZonedDateTime. - Abstände zwischen zwei Daten berechnet man mit
since()oderuntil(), nicht mitsubtract(). - Liegt das Ergebnis außerhalb des darstellbaren Bereichs (etwa ±270.000 Jahre), wird ein
RangeErrorgeworfen. Ungültige Dauer-Eingaben, z. B. gemischte Vorzeichen, lösen ebenfalls einenRangeErroraus.