Signatur
Beschreibung
until() berechnet die Zeitspanne vom aktuellen Temporal.ZonedDateTime (this) bis zum Zeitpunkt other. Liegt other später, ist die Dauer positiv, sonst negativ. Die Methode ist das Gegenstück zu since(): a.until(b) ergibt dieselbe Dauer wie b.since(a).
Weil ein ZonedDateTime seine Zeitzone kennt, werden Sommerzeit-Wechsel richtig berücksichtigt. Standardmäßig ist largestUnit gleich "hours". Das Ergebnis enthält dann nur Stunden und kleinere Einheiten, also die tatsächlich vergangene Zeit. Mit "days", "weeks", "months" oder "years" wird nach Kalender gerechnet. Ein Tag kann dann 23 oder 25 Stunden lang sein.
Typische Einsätze sind Countdowns, die Dauer von Terminen, das Alter von Ereignissen und Abrechnungszeiträume. Mit smallestUnit, roundingIncrement und roundingMode rundest du das Ergebnis direkt, zum Beispiel auf volle Minuten oder auf 15-Minuten-Schritte.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $other Pflicht | Temporal.ZonedDateTime | string | object | Der Endzeitpunkt. Strings (z. B. "2024-05-01T10:00[Europe/Berlin]") und passende Objekte werden wie bei Temporal.ZonedDateTime.from() umgewandelt. Beide Werte müssen denselben Kalender haben. |
|
| $options | object | {} | Einstellungen für Einheiten und Rundung (siehe unten). |
| $options.largestUnit | string | "auto" (entspricht "hours") | Größte Einheit im Ergebnis: "years", "months", "weeks", "days", "hours" … "nanoseconds". Einzahl ("year") ist ebenfalls erlaubt. |
| $options.smallestUnit | string | "nanoseconds" | Kleinste Einheit im Ergebnis. Kleinere Anteile werden gerundet. |
| $options.roundingIncrement | number | 1 | Rundungsschritt in smallestUnit, z. B. 15 für Viertelstunden. Bei Zeiteinheiten muss er die nächstgrößere Einheit ohne Rest teilen. |
| $options.roundingMode | string | "trunc" | Rundungsart: "ceil", "floor", "expand", "trunc", "halfCeil", "halfFloor", "halfExpand", "halfTrunc", "halfEven". |
Rückgabewert
Temporal.Duration-Objekt. Es ist positiv, wenn other später liegt, und negativ, wenn es früher liegt.Beispiele
Sommerzeit-Wechsel: echte Stunden oder Kalendertage
// In der Nacht zum 31.03.2024 wird die Uhr in Berlin vorgestellt
const start = Temporal.ZonedDateTime.from("2024-03-30T12:00[Europe/Berlin]");
const ende = Temporal.ZonedDateTime.from("2024-03-31T12:00[Europe/Berlin]");
console.log(start.until(ende).toString());
console.log(start.until(ende, { largestUnit: "days" }).toString());Arbeitszeit auf angefangene Viertelstunden aufrunden
const beginn = Temporal.ZonedDateTime.from("2024-06-01T09:07:23[Europe/Berlin]");
const feierabend = Temporal.ZonedDateTime.from("2024-06-01T17:52:10[Europe/Berlin]");
const genau = beginn.until(feierabend);
const abgerechnet = beginn.until(feierabend, {
smallestUnit: "minutes",
roundingIncrement: 15,
roundingMode: "ceil",
});
console.log(genau.toString());
console.log(abgerechnet.toString());
console.log(abgerechnet.total({ unit: "hours" }));Laufzeit in Jahren, Monaten und Tagen
const vertragsbeginn = Temporal.ZonedDateTime.from("2023-05-10T08:00[Europe/Berlin]");
const heute = Temporal.ZonedDateTime.from("2024-07-25T14:30[Europe/Berlin]");
const d = vertragsbeginn.until(heute, { largestUnit: "years" });
console.log(d.toString());
console.log(`${d.years} Jahr, ${d.months} Monate, ${d.days} Tage`);Verschiedene Zeitzonen und negatives Ergebnis
const berlin = Temporal.ZonedDateTime.from("2024-01-01T10:00[Europe/Berlin]");
const newYork = Temporal.ZonedDateTime.from("2024-01-01T10:00[America/New_York]");
console.log(berlin.until(newYork).toString()); // gleiche Uhrzeit, 6 h Versatz
console.log(newYork.until(berlin).toString()); // negativ, weil früher
console.log(newYork.until(berlin).sign);