Signatur
Beschreibung
until() berechnet den Abstand zwischen zwei Uhrzeiten ohne Datum und ohne Zeitzone. Das Ergebnis ist ein Temporal.Duration. Es ist positiv, wenn other später liegt als die aktuelle Uhrzeit, und negativ, wenn other früher liegt. a.until(b) ergibt dasselbe wie b.since(a).
Das Argument other wird genauso umgewandelt wie bei Temporal.PlainTime.from(). Du kannst also eine Temporal.PlainTime-Instanz, einen ISO-Zeit-String wie "17:30" oder ein Objekt wie { hour: 17, minute: 30 } übergeben.
Mit dem Objekt options legst du fest, wie die Dauer dargestellt wird: largestUnit bestimmt die größte Einheit, smallestUnit, roundingIncrement und roundingMode steuern die Rundung. Die größte mögliche Einheit ist die Stunde. Ohne Optionen wird das Ergebnis in Stunden, Minuten, Sekunden und Sekundenbruchteilen bis zur Nanosekunde angegeben.
Typische Anwendungen sind Arbeitszeiten, Öffnungszeiten, Countdowns innerhalb eines Tages oder Zeitfenster in Fahrplänen. Das funktioniert immer dann, wenn nur die Uhrzeit zählt und Datum oder Zeitzone keine Rolle spielen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $other Pflicht | Temporal.PlainTime | string | Object | Die Ziel-Uhrzeit. Sie wird wie bei Temporal.PlainTime.from() umgewandelt, z. B. aus "17:45:30" oder { hour: 17, minute: 45 }. |
|
| $options | Object | {} | Optionale Einstellungen: largestUnit, smallestUnit, roundingIncrement und roundingMode. |
| $options.largestUnit | string | "auto" (= "hour") | Größte Einheit im Ergebnis: "hour", "minute", "second", "millisecond", "microsecond" oder "nanosecond" (auch in der Pluralform). Größere Einheiten wie "day" lösen einen RangeError aus. |
| $options.smallestUnit | string | "nanosecond" | Kleinste Einheit im Ergebnis. Kleinere Anteile werden gerundet. Darf nicht größer sein als largestUnit. |
| $options.roundingIncrement | number | 1 | Rundungsschritt in smallestUnit, z. B. 15 für Viertelstunden. Der Wert muss den nächstgrößeren Einheitswert glatt teilen, bei Minuten also 60. |
| $options.roundingMode | string | "trunc" | Rundungsverfahren: "ceil", "floor", "expand", "trunc", "halfCeil", "halfFloor", "halfExpand", "halfTrunc" oder "halfEven". |
Rückgabewert
Temporal.Duration mit der Dauer von dieser Uhrzeit bis other. Ist other früher, ist die Dauer negativ.Beispiele
Arbeitszeit zwischen zwei Uhrzeiten
const beginn = Temporal.PlainTime.from("09:15:00");
const ende = Temporal.PlainTime.from("17:45:30");
const dauer = beginn.until(ende);
console.log(dauer.toString());
console.log(dauer.hours, dauer.minutes, dauer.seconds);
// Gegenrichtung: gleicher Betrag, negatives Vorzeichen
console.log(ende.until(beginn).toString());Ergebnis in Minuten und gerundet
const start = Temporal.PlainTime.from("09:15");
const ziel = { hour: 17, minute: 45, second: 30 };
// Alles in Minuten ausdrücken
console.log(start.until(ziel, { largestUnit: "minute" }).toString());
// Auf volle Minuten runden (kaufmännisch)
console.log(
start.until(ziel, { smallestUnit: "minute", roundingMode: "halfExpand" }).toString()
);
// Auf Viertelstunden abrunden, z. B. für die Abrechnung
console.log(
start.until(ziel, { smallestUnit: "minute", roundingIncrement: 15, roundingMode: "floor" }).toString()
);Nachtschicht über Mitternacht
const schichtBeginn = Temporal.PlainTime.from("22:00");
const schichtEnde = Temporal.PlainTime.from("06:00");
let dauer = schichtBeginn.until(schichtEnde);
console.log(dauer.toString()); // negativ, denn es gibt kein Datum
// Über Mitternacht korrigieren: 24 Stunden addieren
if (dauer.sign < 0) {
dauer = dauer.add({ hours: 24 });
}
console.log(dauer.toString());