Guides / Working with time

Types of time

Pick the right type for a calendar day, a time of day, a specific moment, or a length of time.

JavaScript’s built-in Date uses one object for everything, whether you mean someone’s birthday, a 9:30 AM alarm, or the exact second an order was placed.

Each concept gets its own type so you only work with the parts you actually have:

• CalendarDate for a day on the calendar, like May 10, 2026
• Time for a time of day, like 9:30 AM
• DateTime for a specific moment in a time zone
• Duration for a length of time, like 2 hours or 3 weeks

CalendarDate

Use CalendarDate when something happens on a day rather than at a specific second: birthdays, due dates, holidays, or values from a date picker.

Create one with today() or date():

import { date, today } from 'native-dates';

const birthday = date('2026-05-10');
const due = today().plus(2, 'weeks');

birthday.month; // 5
birthday.day; // 10

Because a CalendarDate has no clock or time zone, May 10 stays May 10 for every user regardless of where they live.

Time

Use Time for a time of day that isn’t tied to one specific date, such as store opening hours or a daily reminder.

import { time } from 'native-dates';

const opens = time('9:00am');
const closes = opens.plus(8, 'hours');

closes.hour; // 17
closes.format('short'); // '5:00 PM'

Adding hours past midnight wraps around the 24-hour clock cleanly, since there is no date to advance.

DateTime

Use DateTime when something happens at a real point in time: a meeting, a flight departure, or a timestamp from your database.

Create one with now() or datetime(), or attach a time to a calendar date:

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

const current = now();
const created = datetime('2026-11-16T17:30:00Z');
const standup = date('2026-11-16').at('9:30am', 'America/Los_Angeles');

A DateTime knows both when something happens and which time zone you’re viewing it in. Call in() to see that same moment in another city:

standup.in('Europe/Berlin').format('time'); // '6:30 PM'

Duration

Use Duration for how long something lasts. Create one with unit helpers like hours() or pass a phrase 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');

Measuring the gap between two values returns a Duration too:

const opens = time('9:00am');
const lunch = time('12:30pm');

opens.until(lunch).format('long'); // '3 hours, 30 minutes'

Moving between them

These types connect directly when you add or drop parts. Attach a time to a CalendarDate with at() to get a DateTime:

const reminder = today().plus(1, 'day').at('9:00am');

Going the other way, read the date or time off any DateTime:

reminder.date; // CalendarDate for tomorrow
reminder.time; // Time for 09:00:00