</> programmierung.net
Start · Sprachen · JavaScript · Referenz · Temporal.PlainDate.prototype.since()

Temporal.PlainDate.prototype.since()

Methode

Gibt eine <code>Temporal.Duration</code> zurück, die die Zeitspanne von einem anderen Datum <code>other</code> bis zu diesem <code>PlainDate</code> angibt.

seit JavaScript ES2026 (Temporal) – Firefox 139+, Chrome 144+; son Kategorie: method-property

Signatur

Temporal.PlainDate.prototype.since(other, options)

Beschreibung

Die Methode since() berechnet den Abstand zwischen zwei Kalenderdaten ohne Uhrzeit und Zeitzone. Das Ergebnis ist this − other: Liegt other in der Vergangenheit, ist die Dauer positiv, liegt es in der Zukunft, ist sie negativ. Damit ist since() das Gegenstück zu until(): a.since(b) entspricht b.until(a).

Mit other kannst du eine Temporal.PlainDate-Instanz, einen ISO-8601-String wie "2024-01-01" oder ein Objekt mit year, month und day übergeben. Die Umwandlung übernimmt Temporal.PlainDate.from().

Ohne Optionen wird die Differenz nur in Tagen angegeben (largestUnit: "auto" entspricht hier "day"). Für Altersangaben, Vertragslaufzeiten oder „vor X Monaten“-Anzeigen setzt du largestUnit auf "year" oder "month". Die Berechnung folgt dem Kalender: Unterschiedliche Monatslängen und Schaltjahre werden automatisch berücksichtigt.

Parameter

Name Typ Default Beschreibung
$other Pflicht Temporal.PlainDate | string | object Das Startdatum, ab dem gemessen wird. Wird mit Temporal.PlainDate.from() umgewandelt.
$options object {} Optionales Objekt mit folgenden Einstellungen:
  • largestUnit: "auto" (Standard, entspricht "day"), "year", "month", "week" oder "day"
  • smallestUnit: kleinste Einheit im Ergebnis, Standard "day"
  • roundingIncrement: Rundungsschritt in smallestUnit, Standard 1
  • roundingMode: z. B. "trunc" (Standard), "round", "halfExpand", "ceil", "floor", "expand"
Einheiten sind auch im Plural erlaubt, z. B. "months".

Rückgabewert

Typ
Temporal.Duration
Beschreibung
Eine neue, unveränderliche Temporal.Duration vom Datum other bis zu this. Sie ist positiv, wenn other früher liegt, und negativ, wenn es später liegt. Die Dauer enthält nur Datumsanteile (Jahre, Monate, Wochen, Tage).

Beispiele

Tage seit Jahresbeginn (Standardverhalten)

const heute = Temporal.PlainDate.from("2024-03-15");
const neujahr = Temporal.PlainDate.from("2024-01-01");

const dauer = heute.since(neujahr);
console.log(dauer.toString());
console.log(dauer.days);

// Umgekehrte Richtung ergibt eine negative Dauer
console.log(neujahr.since(heute).toString());
P74D 74 -P74D

Alter in Jahren, Monaten und Tagen berechnen

const geburtstag = Temporal.PlainDate.from("1990-08-20");
const stichtag = Temporal.PlainDate.from("2025-06-10");

const alter = stichtag.since(geburtstag, { largestUnit: "year" });
console.log(alter.toString());
console.log(`${alter.years} Jahre, ${alter.months} Monate, ${alter.days} Tage`);
P34Y9M21D 34 Jahre, 9 Monate, 21 Tage

Strings als Argument und Ergebnis in Monaten

const ende = Temporal.PlainDate.from("2024-03-15");

// other darf auch ein ISO-String sein
console.log(ende.since("2024-01-01", { largestUnit: "month" }).toString());

// Auf ganze Monate runden statt abschneiden
const gerundet = ende.since("2024-01-01", {
  largestUnit: "month",
  smallestUnit: "month",
  roundingMode: "halfExpand",
});
console.log(gerundet.toString());
P2M14D P2M

Relative Anzeige mit Intl.RelativeTimeFormat

const erstellt = Temporal.PlainDate.from("2024-11-02");
const heute = Temporal.PlainDate.from("2024-12-24");

const wochen = heute.since(erstellt, { largestUnit: "week" }).weeks;
const rtf = new Intl.RelativeTimeFormat("de", { numeric: "auto" });
console.log(rtf.format(-wochen, "week"));
vor 7 Wochen

// Wichtig · Fallstricke

  • Richtung: a.since(b) berechnet a − b. Wenn du die Differenz vom aktuellen Objekt in die Zukunft suchst, ist until() meist verständlicher.
  • Standard nur Tage: Ohne largestUnit erhältst du z. B. P74D und nicht P2M14D. duration.months ist dann 0.
  • Standard-Rundung ist "trunc": Mit smallestUnit: "month" wird ohne weitere Angabe abgeschnitten und nicht kaufmännisch gerundet.
  • Keine Zeiteinheiten: "hour", "minute" usw. lösen einen RangeError aus. Für Uhrzeiten brauchst du PlainDateTime oder ZonedDateTime.
  • Ist largestUnit kleiner als smallestUnit, entsteht ein RangeError.
  • Haben beide Daten verschiedene Kalender (z. B. iso8601 und hebrew), wird ein RangeError geworfen.
  • Monatsarithmetik ist nicht symmetrisch: Durch unterschiedliche Monatslängen führt das Zurückrechnen einer Dauer nicht immer zum Ausgangsdatum.
  • Kompatibilität: Temporal gibt es erst seit Kurzem in Firefox (139+) und Chrome (144+). Für andere Browser und ältere Node.js-Versionen brauchst du einen Polyfill wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.PlainTime.prototype.since() Temporal.PlainDate.prototype.with() Temporal.PlainDateTime.prototype.since() Temporal.PlainDate.prototype.add() Temporal.PlainDate.prototype.until() Temporal.PlainDate.prototype.valueOf()
← Vorheriger Eintrag Temporal.PlainDate.prototype.monthsInYear