Signatur
Beschreibung
until() berechnet den Abstand zwischen zwei Datum-Zeitpunkten ohne Zeitzone, also vom eigenen Wert (this) bis zu other. Liegt other später, ist die Dauer positiv, liegt er früher, ist sie negativ. Die Methode entspricht since() mit vertauschten Argumenten: a.until(b) liefert dasselbe wie b.since(a).
Wie das Ergebnis aufgeteilt wird, legen Sie über options fest. Standardmäßig ist die größte Einheit "day". Sie erhalten also Tage, Stunden, Minuten usw., aber keine Monate oder Jahre. Mit largestUnit: "month" oder "year" rechnet die Methode kalenderbewusst, berücksichtigt also unterschiedlich lange Monate und Schaltjahre. Mit smallestUnit, roundingIncrement und roundingMode können Sie das Ergebnis runden, etwa auf volle Viertelstunden.
Weil PlainDateTime keine Zeitzone kennt, geht die Berechnung immer davon aus, dass jeder Tag 24 Stunden hat. Sommerzeit-Umstellungen spielen deshalb keine Rolle. Das ist praktisch für Zeitangaben wie „Beginn des Termins laut Kalender“, aber falsch, wenn es um die tatsächlich vergangene Zeit an einem bestimmten Ort geht. Dafür nutzen Sie Temporal.ZonedDateTime.prototype.until().
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $other Pflicht | Temporal.PlainDateTime | Temporal.PlainDate | Temporal.ZonedDateTime | Object | string | Der Ziel-Datum-Zeitpunkt. Er wird wie bei Temporal.PlainDateTime.from() umgewandelt, z. B. aus einem ISO-8601-String wie "2024-03-15T17:30" oder einem Objekt mit year, month, day usw. |
|
| $options | Object | {} | Optionen für Einheiten und Rundung, siehe die folgenden Einträge. |
| $options.largestUnit | string | "auto" (entspricht "day") | Größte Einheit im Ergebnis: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond" oder "auto". Pluralformen wie "days" sind auch erlaubt. |
| $options.smallestUnit | string | "nanosecond" | Kleinste Einheit im Ergebnis. Alles, was kleiner ist, wird gerundet. Sie darf nicht größer sein als largestUnit. |
| $options.roundingIncrement | number | 1 | Rundungsschritt in smallestUnit, z. B. 15 zusammen mit "minute" für Viertelstunden. Bei Zeiteinheiten muss die nächstgrößere Einheit ohne Rest durch diesen Wert teilbar sein. |
| $options.roundingMode | string | "trunc" | Rundungsart: "ceil", "floor", "expand", "trunc", "halfCeil", "halfFloor", "halfExpand", "halfTrunc" oder "halfEven". |
Rückgabewert
Temporal.Duration-Objekt mit der Dauer von this bis other. Es ist positiv, wenn other später liegt, und negativ, wenn es früher liegt.Beispiele
Einfache Differenz (Standard: Tage als größte Einheit)
const start = Temporal.PlainDateTime.from("2024-01-01T08:00");
const end = Temporal.PlainDateTime.from("2024-03-15T17:30");
const dauer = start.until(end);
console.log(dauer.toString());
console.log(dauer.days, dauer.hours, dauer.minutes);Kalenderbewusst mit Monaten und nur in Stunden
const start = Temporal.PlainDateTime.from("2024-01-01T08:00");
const end = Temporal.PlainDateTime.from("2024-03-15T17:30");
console.log(start.until(end, { largestUnit: "month" }).toString());
console.log(start.until(end, { largestUnit: "hour" }).toString());
// Umgekehrte Richtung ergibt eine negative Dauer
console.log(end.until(start).toString());Arbeitszeit auf Viertelstunden runden
const kommen = Temporal.PlainDateTime.from("2024-06-03T08:07");
const gehen = Temporal.PlainDateTime.from("2024-06-03T16:52");
const gebucht = kommen.until(gehen, {
largestUnit: "hour",
smallestUnit: "minute",
roundingIncrement: 15,
roundingMode: "halfExpand",
});
console.log(gebucht.toString());
console.log(`${gebucht.hours} h ${gebucht.minutes} min`);Countdown bis zu einem Termin
const jetzt = Temporal.Now.plainDateTimeISO();
const termin = Temporal.PlainDateTime.from("2030-12-24T18:00");
const rest = jetzt.until(termin, {
largestUnit: "day",
smallestUnit: "minute",
});
console.log(`Noch ${rest.days} Tage, ${rest.hours} Stunden, ${rest.minutes} Minuten`);