Signatur
Beschreibung
subtract() verschiebt einen zeitzonenbezogenen Zeitpunkt um eine Dauer zurück. Die Dauer kannst du als Temporal.Duration, als einfaches Objekt (z. B. { hours: 2 }) oder als ISO-8601-Dauer-String (z. B. "PT90M") übergeben. Das ursprüngliche Objekt bleibt unverändert, denn alle Temporal-Objekte sind unveränderlich (immutable).
Wichtig ist, wie die Einheiten verrechnet werden: Kalendereinheiten (years, months, weeks, days) werden in Ortszeit abgezogen. „1 Tag zurück“ bedeutet also „gleiche Uhrzeit am Vortag“, auch wenn der Tag wegen einer Sommerzeitumstellung 23 oder 25 Stunden hatte. Zeiteinheiten (hours bis nanoseconds) werden dagegen in exakter Zeit abgezogen. { days: 1 } und { hours: 24 } können deshalb verschiedene Ergebnisse liefern.
Die Einheiten werden von groß nach klein abgezogen: zuerst Jahre, Monate, Wochen und Tage, danach die Zeitanteile. Ergibt sich dabei ein Datum, das es nicht gibt (z. B. 31. März minus 1 Monat), entscheidet die Option overflow, ob das Datum angepasst wird oder ein Fehler kommt. Fällt das Ergebnis in eine Lücke durch die Sommerzeitumstellung, wird es immer nach der Strategie "compatible" aufgelöst, also nach vorne verschoben.
Typische Einsatzfälle sind Erinnerungen („30 Minuten vor dem Termin“), Fristen („14 Tage vor Ablauf“) und Zeitfenster für Berichte („letzte 7 Tage in Ortszeit“).
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $duration Pflicht | Temporal.Duration | object | string | Die Dauer, die abgezogen wird. Möglich sind ein Temporal.Duration-Objekt, ein Objekt mit Feldern wie years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds und nanoseconds oder ein ISO-8601-String wie "P1DT2H". Wird intern mit Temporal.Duration.from() umgewandelt. |
|
| $options | object | {} | Optionales Objekt mit Einstellungen. |
| $options.overflow | "constrain" | "reject" | "constrain" | Legt fest, was bei einem ungültigen Datum passiert. Bei "constrain" wird auf den nächsten gültigen Wert gekürzt (z. B. 31. → 29. Februar). Bei "reject" wird ein RangeError geworfen. |
Rückgabewert
Temporal.ZonedDateTime in derselben Zeitzone und mit demselben Kalender, um duration in die Vergangenheit verschoben.Beispiele
Erinnerung vor einem Termin berechnen
const termin = Temporal.ZonedDateTime.from("2024-03-15T10:30:00[Europe/Berlin]");
// Objekt-Schreibweise
const erinnerung = termin.subtract({ minutes: 30 });
console.log(erinnerung.toString());
// ISO-8601-Dauer-String
const vorbereitung = termin.subtract("PT2H15M");
console.log(vorbereitung.toString());
// Das Original bleibt unverändert
console.log(termin.toString());Sommerzeit: days vs. hours
// Am 31.03.2024 beginnt in Berlin die Sommerzeit (02:00 → 03:00)
const zdt = Temporal.ZonedDateTime.from("2024-03-31T12:00:00[Europe/Berlin]");
// Kalendertag zurück: gleiche Uhrzeit am Vortag
console.log(zdt.subtract({ days: 1 }).toString());
// 24 exakte Stunden zurück: wegen der Umstellung eine Stunde Unterschied
console.log(zdt.subtract({ hours: 24 }).toString());Monatsende und overflow-Option
const ende = Temporal.ZonedDateTime.from("2024-03-31T09:00:00[Europe/Berlin]");
// Standard "constrain": 31. Februar gibt es nicht → 29. Februar (Schaltjahr)
console.log(ende.subtract({ months: 1 }).toString());
try {
ende.subtract({ months: 1 }, { overflow: "reject" });
} catch (err) {
console.log(err.constructor.name);
}Zeitfenster der letzten 7 Tage in Ortszeit
const jetzt = Temporal.Now.zonedDateTimeISO("Europe/Berlin");
const start = jetzt
.subtract(Temporal.Duration.from({ weeks: 1 }))
.startOfDay();
console.log(`Bericht von ${start.toPlainDate()} bis ${jetzt.toPlainDate()}`);
// Für Datenbank-Abfragen in UTC:
console.log(start.toInstant().toString());