Temporal.PlainYearMonth.prototype.subtract() — Methode · JavaScript-Referenz

Signatur

Temporal.PlainYearMonth.prototype.subtract(duration, options)

Beschreibung

Die Methode subtract() zieht eine Dauer von einem Jahr-Monat-Wert ab, zum Beispiel „März 2024 minus 5 Monate“. Heraus kommt ein neues Temporal.PlainYearMonth-Objekt. Das ursprüngliche Objekt bleibt unverändert, denn alle Temporal-Objekte sind unveränderlich (immutable).

Als Dauer geht ein Temporal.Duration-Objekt, ein einfaches Objekt wie { years: 1, months: 2 } oder ein ISO-8601-Dauer-String wie "P1Y2M". Wirklich von Bedeutung sind nur Jahre und Monate, denn ein PlainYearMonth hat keinen Tag und keine Uhrzeit. ym.subtract(d) liefert dasselbe Ergebnis wie ym.add(d.negated()).

Typische Einsätze sind Abrechnungs- und Berichtszeiträume („die letzten 12 Monate“), Ablaufdaten von Kreditkarten oder monatliche Statistiken. Die Rechnung läuft im Kalender des Objekts. Bei Kalendern außerhalb von ISO (zum Beispiel dem hebräischen Kalender mit Schaltmonaten) legt die Option overflow fest, was mit einem Monat passiert, den es im Zieljahr nicht gibt.

Parameter

Name	Typ	Default	Beschreibung
$duration Pflicht	Temporal.Duration \| Object \| string		Die abzuziehende Dauer: eine `Temporal.Duration`, ein Objekt wie `{ years, months }` oder ein ISO-8601-String wie `"P1Y6M"`. Wird intern mit `Temporal.Duration.from()` umgewandelt.
$options	Object	{}	Optionales Objekt mit der Eigenschaft `overflow`: `"constrain"` (Standard) zieht ungültige Werte auf den nächsten gültigen Wert, `"reject"` wirft dann einen `RangeError`.

Rückgabewert

Typ

Temporal.PlainYearMonth

Beschreibung

Ein neues Temporal.PlainYearMonth im selben Kalender, um duration in die Vergangenheit verschoben.

Beispiele

Monate abziehen, auch über den Jahreswechsel

const ym = Temporal.PlainYearMonth.from("2024-03");
const frueher = ym.subtract({ months: 5 });

console.log(frueher.toString());
console.log(ym.toString()); // Original bleibt unverändert

2023-10 2024-03

Dauer als ISO-8601-String oder Temporal.Duration

const ym = Temporal.PlainYearMonth.from({ year: 2024, month: 3 });

console.log(ym.subtract("P1Y2M").toString());
console.log(ym.subtract(Temporal.Duration.from({ years: 10 })).toString());

2023-01 2014-03

Die letzten 12 Monate für einen Bericht erzeugen

const aktuell = Temporal.PlainYearMonth.from("2025-02");

const letzte12 = Array.from({ length: 12 }, (_, i) =>
  aktuell.subtract({ months: i }).toLocaleString("de-DE", {
    year: "numeric",
    month: "long",
    calendar: "iso8601"
  })
);

console.log(letzte12.slice(0, 3));

[ 'Februar 2025', 'Januar 2025', 'Dezember 2024' ]

Negative Dauer und Fehler bei ungültiger Eingabe

const ym = Temporal.PlainYearMonth.from("2024-11");

// Eine negative Dauer verschiebt nach vorn
console.log(ym.subtract({ months: -3 }).toString());

try {
  ym.subtract({ monate: 1 }); // falscher Schlüsselname
} catch (e) {
  console.log(e.constructor.name);
}

2025-02 TypeError

// Wichtig · Fallstricke

Browser-Unterstützung: Temporal ist neu. Nativ gibt es die API in Firefox 139+ und Chrome/Edge 144+, in Safari und älteren Node.js-Versionen noch nicht. Als Ersatz dienen Polyfills wie @js-temporal/polyfill oder temporal-polyfill.
Nur Jahre und Monate verwenden: Einheiten kleiner als ein Monat (Wochen, Tage, Stunden …) haben keinen sinnvollen Bezug zu einem Jahr-Monat. Sie ändern das Ergebnis nicht verlässlich, und je nach Stand der Spezifikation bzw. des Polyfills verhalten sie sich unterschiedlich. Wer Tage braucht, rechnet mit toPlainDate({ day }) und Temporal.PlainDate.
Unveränderlichkeit: subtract() ändert das Objekt nicht selbst. Das Ergebnis muss man einer Variablen zuweisen.
overflow im ISO-Kalender: Hier ist jeder Monat in jedem Jahr gültig, die Option wirkt also praktisch nicht. Wichtig wird sie bei Kalendern mit Schaltmonaten (z. B. hebrew, chinese).
Wertebereich: Liegt das Ergebnis außerhalb des von Temporal unterstützten Bereichs (etwa ±270.000 Jahre), gibt es einen RangeError. Eine ungültige Dauer, z. B. mit unbekannten Schlüsseln oder gemischten Vorzeichen, führt zu einem TypeError bzw. RangeError.

Siehe auch

Temporal.PlainYearMonth.prototype.add() Temporal.PlainYearMonth.prototype.since() Temporal.PlainYearMonth.prototype.until() Temporal.PlainYearMonth.prototype.with() Temporal.Duration Temporal.PlainDate.prototype.subtract()