Signatur
Beschreibung
round() rundet einen exakten Zeitpunkt (Temporal.Instant) auf eine kleinste Einheit, also "hour", "minute", "second", "millisecond", "microsecond" oder "nanosecond". Das ursprüngliche Objekt bleibt unverändert, denn Temporal-Objekte sind unveränderlich. Du bekommst immer eine neue Instanz zurück.
Typische Einsatzfälle sind das Kürzen von Zeitstempeln für Logs und Anzeigen, das Einsortieren von Messwerten in feste Zeitfenster (z. B. 5- oder 15-Minuten-Intervalle) und das Entfernen von Sub-Sekunden-Anteilen vor einem Vergleich oder dem Speichern. Mit roundingIncrement legst du die Schrittweite fest, mit roundingMode die Rundungsrichtung, z. B. "floor" für den Anfang eines Intervalls.
Wichtig: Ein Instant hat keine Zeitzone. Gerundet wird deshalb immer in Bezug auf die Unix-Epoche, also in UTC. Brauchst du Rundung nach lokaler Uhrzeit (z. B. „volle Stunde in Indien“ oder „Tagesbeginn“), wandle den Zeitpunkt vorher mit toZonedDateTimeISO() um und benutze Temporal.ZonedDateTime.prototype.round().
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $smallestUnit Pflicht | string | Kurzform: Übergibst du einen String, gilt er als smallestUnit, die übrigen Optionen haben dann ihre Standardwerte. Erlaubt sind "hour", "minute", "second", "millisecond", "microsecond" und "nanosecond" (auch in der Mehrzahl, z. B. "minutes"). "day" ist nicht erlaubt. |
|
| $options Pflicht | Object | Alternative zum String: ein Objekt mit den folgenden Eigenschaften. | |
| $options.smallestUnit Pflicht | string | Die Einheit, auf die gerundet wird (Werte wie oben). Ohne diese Angabe wird ein RangeError geworfen. |
|
| $options.roundingIncrement | number | 1 | Schrittweite in smallestUnit, z. B. 15 für Viertelstunden. Die Zahl muss ganzzahlig sein und einen Tag ohne Rest teilen, z. B. bei Stunden 1, 2, 3, 4, 6, 8, 12 oder 24 und bei Minuten ein Teiler von 1440. |
| $options.roundingMode | string | "halfExpand" | Legt fest, wie gerundet wird: "ceil", "floor", "expand", "trunc", "halfCeil", "halfFloor", "halfExpand", "halfTrunc" oder "halfEven". |
Rückgabewert
Temporal.Instant, das auf die angegebene Einheit und Schrittweite gerundet ist.Beispiele
Auf Sekunde und Minute runden
const instant = Temporal.Instant.from("2024-03-15T10:37:48.123Z");
// Kurzform mit String
console.log(instant.round("second").toString());
console.log(instant.round("minute").toString()); // halfExpand: 48 s → aufrunden
// Abrunden über das Options-Objekt
console.log(
instant.round({ smallestUnit: "minute", roundingMode: "floor" }).toString()
);Messwerte in 15-Minuten-Fenster einsortieren
const messungen = [
{ zeit: "2024-03-15T10:02:10Z", wert: 21.4 },
{ zeit: "2024-03-15T10:14:59Z", wert: 21.9 },
{ zeit: "2024-03-15T10:31:05Z", wert: 22.6 },
];
const fenster = Map.groupBy(messungen, ({ zeit }) =>
Temporal.Instant.from(zeit)
.round({ smallestUnit: "minute", roundingIncrement: 15, roundingMode: "floor" })
.toString()
);
for (const [start, werte] of fenster) {
console.log(start, werte.map((m) => m.wert));
}Fallstrick: Rundung erfolgt in UTC, nicht in Ortszeit
const instant = Temporal.Instant.from("2024-03-15T10:37:48.123Z");
// Instant rundet in UTC → in Indien (UTC+05:30) keine volle Stunde
const utcGerundet = instant.round("hour");
console.log(utcGerundet.toZonedDateTimeISO("Asia/Kolkata").toString());
// Richtig für Ortszeit: erst in eine Zeitzone umwandeln, dann runden
const lokalGerundet = instant
.toZonedDateTimeISO("Asia/Kolkata")
.round({ smallestUnit: "hour", roundingMode: "floor" });
console.log(lokalGerundet.toString());Ungültige Optionen abfangen
const instant = Temporal.Instant.from("2024-03-15T10:37:48Z");
try {
instant.round({ smallestUnit: "minute", roundingIncrement: 7 });
} catch (err) {
console.log(err.name); // 7 teilt 1440 Minuten nicht ohne Rest
}
try {
instant.round("day");
} catch (err) {
console.log(err.name); // "day" ist bei Instant nicht erlaubt
}