Skip to main content
Temporal.DifferenceOptions - Temporal - Web documentation
interface Temporal.DifferenceOptions
Unstable
Options to control the result of `until()` and `since()` methods in `Temporal` types.

Type Parameters

T extends DateTimeUnit

Properties

The unit to round to. For example, to round to the nearest minute, use `smallestUnit: 'minute'`. This property is optional for `until()` and `since()`, because those methods default behavior is not to round. However, the same property is required for `round()`.
The largest unit to allow in the resulting `Temporal.Duration` object. Larger units will be "balanced" into smaller units. For example, if `largestUnit` is `'minute'` then a two-hour duration will be output as a 120-minute duration. Valid values may include `'year'`, `'month'`, `'week'`, `'day'`, `'hour'`, `'minute'`, `'second'`, `'millisecond'`, `'microsecond'`, `'nanosecond'` and `'auto'`, although some types may throw an exception if a value is used that would produce an invalid result. For example, `hours` is not accepted by `Temporal.PlainDate.prototype.since()`. The default is always `'auto'`, though the meaning of this depends on the type being used.
optional
roundingIncrement: number
Allows rounding to an integer number of units. For example, to round to increments of a half hour, use `{ smallestUnit: 'minute', roundingIncrement: 30 }`.
Controls how rounding is performed: - `halfExpand`: Round to the nearest of the values allowed by `roundingIncrement` and `smallestUnit`. When there is a tie, round away from zero like `ceil` for positive durations and like `floor` for negative durations. - `ceil`: Always round up, towards the end of time. - `trunc`: Always round down, towards the beginning of time. This mode is the default. - `floor`: Also round down, towards the beginning of time. This mode acts the same as `trunc`, but it's included for consistency with `Temporal.Duration.round()` where negative values are allowed and `trunc` rounds towards zero, unlike `floor` which rounds towards negative infinity which is usually unexpected. For this reason, `trunc` is recommended for most use cases.