Skip to main content
interface Temporal.DifferenceOptions

Options to control the result of until() and since() methods in Temporal types.


smallestUnit: SmallestUnit<T>

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().

largestUnit: LargestUnit<T>

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.

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 }.

roundingMode: RoundingMode

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.