native-dates

API / Classes

Time class

A time of day with no calendar date and no time zone.

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

Creating a Time

Parse 12-hour or 24-hour clock strings, pass hour and minute numbers, or convert an existing value with time(). Instances are immutable, so every method that changes a value returns a new one.

create.js
import { time } from 'native-dates';

const morning = time('9:30am');
const evening = time('17:30');
const alarm = time(6, 45);

Read the local time of day off any DateTime through its time property:

import { datetime, now } from 'native-dates';

const standup = datetime('2026-11-16T09:30', 'America/Los_Angeles');
standup.time.toString(); // '09:30:00'
const currentClock = now().time;

Properties

Properties read the 24-hour clock fields from hours down to nanoseconds.

Property Type Description
text string Locale-formatted time of day, such as '9:30 AM'.
hour, minute, second number 24-hour clock fields (0–23, 0–59, 0–59).
millisecond, microsecond, nanosecond number Sub-second clock fields (0–999).

Combining and fields

Place a time of day onto a calendar date, or replace individual clock fields.

on()

t.on(date, zone?): DateTime

Combines this time of day with a calendar date in a time zone and returns a DateTime. Mirrors calling at() on a CalendarDate.

Parameters

dateCalendarDateInputrequired

ISO date string, CalendarDate, DateTime, fields object, or Date.

zoneZone

IANA time zone name, fixed UTC offset, or 'UTC'. Defaults to the configured zone.

Returns

DateTime

A new DateTime on date at this time in zone.

const opens = time('9:30am');

opens.on('2026-11-16', 'America/New_York').toString(); // '2026-11-16T14:30:00.000Z'

set()

t.set(fields): Time
t.set(unit, value): Time

Returns a new Time with one or more clock fields replaced. Out-of-range values such as minute 75 throw a RangeError.

Parameters

fieldsDateTimeFields | Unitrequired

Object of clock fields, or a single unit name when passing value.

valuenumber

Whole-number value for the given unit.

Returns

Time

A new Time with updated clock fields.

const reminder = time('9:30am');

reminder.set('minute', 45).toString(); // '09:45:00'
reminder.set({ hour: 17, minute: 0 }).toString(); // '17:00:00'

Arithmetic and rounding

Add or subtract clock units, snap to unit boundaries, or round to a step increment. Calendar units such as days and weeks throw a RangeError because a time of day has no date.

Wrapping around midnight

Clock arithmetic wraps around the 24-hour day like a clock face, so adding 2 hours to 23:00 returns 01:00. Combine the time with a date using on() first when crossing midnight should advance the calendar day.

plus()

t.plus(amount, unit?): Time
t.add(amount, unit?): Time

Moves forward on the 24-hour clock and returns a new Time, wrapping past midnight when needed. Also aliased as add().

Parameters

amountDurationInputrequired

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

unitUnit

Clock unit name when amount is a number, such as 'hours' or 'minutes'.

Returns

Time

A new Time wrapped to the 24-hour clock.

time('9:00am').plus(90, 'minutes').toString(); // '10:30:00'
time('23:00').plus('2h').toString(); // '01:00:00'

minus()

t.minus(amount, unit?): Time
t.subtract(amount, unit?): Time
t.remove(amount, unit?): Time

Moves backward on the 24-hour clock, wrapping before midnight when needed. Accepts the same inputs as plus(), and is also aliased as subtract() and remove().

Parameters

amountDurationInputrequired

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

unitUnit

Clock unit name when amount is a number.

Returns

Time

A new Time wrapped to the 24-hour clock.

time('00:30').minus(45, 'minutes').toString(); // '23:45:00'

startOf()

t.startOf(unit): Time

Zeros out all clock fields smaller than the given unit.

Parameters

unitUnitrequired

Clock unit from 'hour' down to 'nanosecond'.

Returns

Time

A new Time at the start of unit.

time('14:37:22').startOf('hour').toString(); // '14:00:00'

endOf()

t.endOf(unit): Time

Moves to the final millisecond of the given clock unit.

Parameters

unitUnitrequired

Clock unit from 'hour' down to 'second'.

Returns

Time

A new Time at the last millisecond of unit.

time('14:37:22').endOf('hour').toString(); // '14:59:59.999'

round()

t.round(unit): Time
t.round(increment, unit): Time

Rounds to the nearest clock unit or step increment, with half-way ties rounding up.

Parameters

incrementnumber | Unitrequired

Step size that divides evenly into the next unit, or the target unit when rounding to 1.

unitUnit

Clock unit to round, from 'hour' down to 'nanosecond'.

Returns

Time

A new rounded Time.

const checkin = time('14:36:00');

checkin.round('hour').toString(); // '15:00:00'
checkin.round(15, 'minutes').toString(); // '14:30:00'

floor()

t.floor(unit): Time
t.floor(increment, unit): Time

Rounds down to the start of a clock unit or step increment. Accepts the same arguments as round().

time('14:29').floor(15, 'minutes').toString(); // '14:15:00'

ceil()

t.ceil(unit): Time
t.ceil(increment, unit): Time

Rounds up to the next clock unit or step increment. Accepts the same arguments as round().

time('14:01').ceil(15, 'minutes').toString(); // '14:15:00'

Comparing times

Comparisons order times within a single day from midnight through the end of the day. Relational operators like < throw a RangeError, so compare values with methods or compare().

equals()

t.equals(other): boolean

Returns true when both values represent the exact same time of day.

Parameters

otherTimeInputrequired

Another Time or any input accepted by time().

Returns

boolean

true if both values match to the nanosecond.

time('5:30pm').equals('17:30'); // true

isBefore()

t.isBefore(other): boolean

Returns true if this time is earlier in the day than the other.

time('9:00am').isBefore('5:00pm'); // true

isAfter()

t.isAfter(other): boolean

Returns true if this time is later in the day than the other.

time('5:00pm').isAfter('9:00am'); // true

isSame()

t.isSame(other, unit?): boolean

Checks whether another time falls within the same clock unit, such as the same hour or minute. Calling isSame() without a unit checks exact equality.

Parameters

otherTimeInputrequired

Time to compare against.

unitUnit

Clock unit to compare, such as 'hour' or 'minute'.

Returns

boolean

true when both times share the same unit.

time('9:05am').isSame('9:45am', 'hour'); // true
time('9:05am').isSame('10:05am', 'hour'); // false

Measuring spans

until()

t.until(other): Duration
t.until(other, unit): number

Measures the signed time from this time to another within the same day, returning a negative span when the target is earlier. Pass a unit name to get the total length as a number.

Parameters

otherTimeInputrequired

Target time to measure toward.

unitUnit

Clock unit to return the total length in as a floating-point number.

Returns

Duration | number

A Duration balanced up to hours, or a number when unit is given.

const opens = time('9:00am');
const closes = time('5:30pm');

opens.until(closes).format('long', 'en-US'); // '8 hours, 30 minutes'
opens.until(closes, 'hours'); // 8.5
time('22:00').until('02:00', 'hours'); // -20

since()

t.since(other): Duration
t.since(other, unit): number

Measures the time elapsed since an earlier time on the same day. Pass a unit name to get the total as a number.

time('5:00pm').since('9:00am', 'hours'); // 8

Formatting and conversion

format()

t.format(spec?, locale?): string

Formats the time of day using Intl.DateTimeFormat. Accepts a preset style, an options object, or a token pattern when @native-dates/plugins/tokens is loaded.

Parameters

specFormatSpecdefault 'short'

Time preset from 'short' through 'full', Intl.DateTimeFormatOptions object, or token pattern.

localestring

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

Returns

string

Locale-formatted time string.

const afternoon = time('17:30:15');

afternoon.format('short', 'en-US'); // '5:30 PM'
afternoon.format('medium', 'en-US'); // '5:30:15 PM'
afternoon.format({ hour: '2-digit', minute: '2-digit', hour12: false }, 'en-US'); // '17:30'

toString()

t.toString(): string
t.toJSON(): string

Returns the 24-hour ISO 8601 time string, printing sub-second digits in groups of three only when nonzero. toJSON() returns the same string for JSON.stringify().

Returns

string

ISO 8601 time string, such as '17:30:00' or '17:30:15.250'.

time('5:30pm').toString(); // '17:30:00'
time('17:30:15.25').toString(); // '17:30:15.250'
JSON.stringify({ opens: time('9am') }); // '{"opens":"09:00:00"}'

toTemporal()

t.toTemporal(): Temporal.PlainTime

Returns the underlying Temporal.PlainTime instance.

valueOf()

t.valueOf(): never

Throws a RangeError so numeric operators never silently coerce a time of day to a number.

Edit this pageUpdated Nov 12, 2026