native-dates

API / Classes

Duration class

A length of time across calendar and clock units.

import { Duration } from 'native-dates'core 7.3 kB min+br

Creating a Duration

Parse phrases and ISO 8601 strings with duration(), call unit helpers like hours(), or measure the span between two dates or times. Instances are immutable, so every method returns a new value.

create.js
import { date, days, duration, hours } from 'native-dates';

const breakTime = duration('1h 30m');
const trial = days(14);
const timeout = hours(1.5);
const quarter = date('2026-01-01').until('2026-04-01');

Fields stay as written

Creating a duration from 90 minutes keeps minutes at 90 rather than converting to 1 hour and 30 minutes. Calendar days also stay separate from hours across daylight saving changes until you call balance().

Properties

Properties reflect the unit counts stored on the duration.

Property Type Description
text string Locale-formatted duration in long style, such as '1 hour, 30 minutes'.
years, months, weeks, days number Signed calendar unit counts stored on this duration.
hours, minutes, seconds number Signed clock unit counts.
milliseconds, microseconds, nanoseconds number Signed sub-second unit counts.
sign number Overall direction of the duration: 1, 0, or -1.
anchor TemporalValue Starting point recorded by until() or since(), or undefined on standalone durations.

Arithmetic and sign

Combine durations, scale them by a factor, or flip their sign. All non-zero fields in a duration must share the same sign.

plus()

dur.plus(other, unit?): Duration
dur.add(other, unit?): Duration

Adds another duration and returns a new Duration. Calendar units add field-by-field while clock units combine cleanly, and add() is an alias.

Parameters

otherDurationInputrequired

Count paired with unit, Duration instance, duration string, fields object, or milliseconds.

unitUnit

Unit name when other is a number, such as 'minutes' or 'days'.

Returns

Duration

A new combined Duration.

hours(2).plus(30, 'minutes').toString(); // 'PT2H30M'
days(1).plus('6h').toString(); // 'P1DT6H'

minus()

dur.minus(other, unit?): Duration
dur.subtract(other, unit?): Duration
dur.remove(other, unit?): Duration

Subtracts another duration, throwing an error if calendar and clock fields end up with opposite signs. Accepts the same inputs as plus(), and is also aliased as subtract() and remove().

Parameters

otherDurationInputrequired

Count paired with unit, Duration instance, duration string, fields object, or milliseconds.

unitUnit

Unit name when other is a number.

Returns

Duration

A new Duration with other subtracted.

hours(2).minus('30m').toString(); // 'PT1H30M'

times()

dur.times(factor): Duration

Multiplies every field by a number, spilling fractional results into smaller units.

Parameters

factornumberrequired

Multiplier to scale the duration by, including fractional or negative numbers.

Returns

Duration

A new scaled Duration.

hours(1).times(1.5).toString(); // 'PT1H30M'
days(1).times(3).toString(); // 'P3D'

abs()

dur.abs(): Duration

Returns a copy with all fields made positive.

duration('-1h 30m').abs().toString(); // 'PT1H30M'

negated()

dur.negated(): Duration

Reverses the sign of every field in the duration.

hours(2).negated().toString(); // '-PT2H'

Balancing, rounding, and totals

Roll smaller units up into larger ones, round to a target precision, or express the entire span as a single number.

Months and years need a starting date

Standalone calendar spans like months(1) have no fixed day count, so converting them to days or milliseconds throws a RangeError. Measure between two dates with until() when you need exact totals across months or years.

balance()

dur.balance(largestUnit?): Duration

Carries overflow from smaller units into larger ones. By default, standalone durations balance up to hours and measured spans balance up to days, unless you pass a larger target unit.

Parameters

largestUnitUnit

Largest unit to roll values up into, such as 'hour', 'day', or 'week'.

Returns

Duration

A new balanced Duration.

import { minutes } from 'native-dates';

minutes(150).balance().toString(); // 'PT2H30M'
duration('36h').balance('day').toString(); // 'P1DT12H'
duration('10d').balance('week').toString(); // 'P1W3D'

total()

dur.total(unit): number

Returns the entire length of the duration as a single floating-point number in the given unit.

Parameters

unitUnitrequired

Target unit to express the total length in, such as 'hours' or 'days'.

Returns

number

Total length in unit, including any fractional part.

minutes(90).total('hours'); // 1.5
days(14).total('weeks'); // 2
date('2026-01-01').until('2026-07-01').total('months'); // 6

round()

dur.round(smallestUnit): Duration

Rounds the duration to the nearest whole unit, with half-way ties rounding away from zero.

Parameters

smallestUnitUnitrequired

Smallest unit to keep after rounding, such as 'minute' or 'hour'.

Returns

Duration

A new rounded Duration.

minutes(90).round('hour').toString(); // 'PT2H'
duration('1h 20m').round('hour').toString(); // 'PT1H'

Comparing durations

Compare durations by total length rather than how their fields were written, so 60 minutes equals 1 hour.

equals()

dur.equals(other): boolean

Returns true when both durations represent the same total length.

Parameters

otherDurationInputrequired

Another Duration or any input accepted by duration().

Returns

boolean

true if both durations have equal length.

import { months } from 'native-dates';

hours(1).equals(minutes(60)); // true
months(1).equals('P1M'); // true

compare()

dur.compare(other): number

Orders this duration against another by total length for sorting.

Parameters

otherDurationInputrequired

Duration to compare against.

Returns

number

-1 when shorter, 0 when equal, or 1 when longer.

hours(1).compare(minutes(90)); // -1
date('2026-01-01').until('2026-02-01').compare(days(31)); // 0

Sign predicates

Zero-argument checks for empty or negative spans:

Method Type Description
isZero() boolean Whether every unit on the duration is zero.
isNegative() boolean Whether the duration represents a negative span.

Formatting and conversion

format()

dur.format(style?, locale?): string

Formats the duration in the active locale using Intl.DurationFormat. Clock overflow balances up to hours automatically, and sub-second fields stay hidden whenever larger units are present.

Parameters

style'long' | 'short' | 'narrow' | 'digital'default 'long'

Display style for unit labels, or 'digital' for a colon-separated timer.

localestring

BCP 47 locale tag overriding the configured default for this call.

Returns

string

Locale-formatted duration string.

const span = duration('2h 30m');

span.format('long', 'en-US'); // '2 hours, 30 minutes'
span.format('short', 'en-US'); // '2 hr, 30 min'
span.format('narrow', 'en-US'); // '2h 30m'
span.format('digital', 'en-US'); // '2:30:00'

toFields()

dur.toFields(): DurationFields

Returns a plain object containing only the non-zero plural unit fields on this duration.

duration('1h 30m').toFields(); // { hours: 1, minutes: 30 }

toString()

dur.toString(): string
dur.toJSON(): string

Returns the ISO 8601 duration string. toJSON() returns the same string for JSON.stringify().

Returns

string

ISO 8601 duration string, such as 'PT1H30M'.

const ttl = duration('1h 30m');

ttl.toString(); // 'PT1H30M'
JSON.stringify({ ttl }); // '{"ttl":"PT1H30M"}'

toMilliseconds()

dur.toMilliseconds(): number

Returns the total length in milliseconds. Unanchored month or year durations throw a RangeError.

hours(2).toMilliseconds(); // 7200000

toTemporal()

dur.toTemporal(): Temporal.Duration

Returns the underlying Temporal.Duration instance.

valueOf()

dur.valueOf(): number

Returns total milliseconds so fixed-length or anchored durations work with timers and numeric comparison operators.

Edit this pageUpdated Nov 12, 2026