Guides / Working with time

Durations

Create lengths of time from unit helpers or plain phrases, measure spans between dates, and convert or format totals.

A Duration represents a length of time, such as 90 minutes or 2 weeks. You can create one directly for date math, or get one back when measuring between two values.

Creating a Duration

Create a length of time with unit helpers like hours(), or pass a phrase, an ISO 8601 string, or a fields object to duration():

import { days, duration, hours } from 'native-dates';

const call = hours(1.5);
const trial = days(14);
const turnaround = duration('2 weeks, 3 days');
const iso = duration('PT1H30M');
const window = duration({ hours: 2, minutes: 45 });

Read unit counts directly off the instance. Fractional inputs spill into the next smaller unit automatically, while whole numbers stay in the unit you wrote:

call.hours; // 1
call.minutes; // 30

const ninety = duration(90, 'minutes');
ninety.hours; // 0
ninety.minutes; // 90

Measuring between two values

Call until() or since() on two dates, times, or moments to measure the span between them:

import { datetime } from 'native-dates';

const opened = datetime('2026-11-16T08:00', 'America/Los_Angeles');
const resolved = datetime('2026-11-16T10:30', 'America/Los_Angeles');

const elapsed = opened.until(resolved);
elapsed.hours; // 2
elapsed.minutes; // 30

When you only need a single number for calculations or progress bars, pass the target unit as a second argument:

opened.until(resolved, 'hours'); // 2.5
resolved.since(opened, 'minutes'); // 150

Balancing and totaling units

Values stay in the units you gave them until you ask otherwise. Call balance() when you want overflow carried into larger units:

import { hours, minutes } from 'native-dates';

minutes(90).balance().toFields(); // { hours: 1, minutes: 30 }
hours(36).balance('day').toFields(); // { days: 1, hours: 12 }

Without an argument, standalone durations balance clock units up to hours rather than assuming every calendar day has 24 hours.

Pass 'day' or 'week' when you want fixed 24-hour days or 7-day weeks.

Call total() to collapse the entire span into a single floating-point number in one unit:

import { duration } from 'native-dates';

const shift = duration('7h 30m');

shift.total('hours'); // 7.5
shift.total('minutes'); // 450

import { date } from 'native-dates';

const span = date('2026-01-15').until('2026-04-15');

span.total('months'); // 3
span.total('days'); // 90

Formatting durations

Every instance sets .text to its localized long form. Call format() with a preset style for spelled-out, abbreviated, compact, or digital output:

import { duration } from 'native-dates';

const flight = duration({ hours: 2, minutes: 30 });

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

Pass a locale tag as the second argument to translate unit labels, or call toString() when you need an ISO 8601 string for an API payload.