native-dates

API / Functions

dateRange() function

Create a DateRange, DateTimeRange, or TimeRange from endpoints, durations, or interval strings.

import { dateRange, datetimeRange, timeRange } from 'native-dates'core 12.1 kB min+br

Creating ranges

Standalone factories construct Ranges from raw inputs, endpoint pairs, or single interval strings. When you already hold a typed point, call to() or range() on it directly.

dateRange()

dateRange(start, end, options?): DateRange
dateRange(interval, options?): DateRange

Creates an inclusive DateRange spanning two calendar dates. When the second argument is a duration like '7 days', the final day sits six days after the start date so the span covers seven days total.

dates.js
import { dateRange, days } from 'native-dates';

const fromEnds = dateRange('2026-09-01', '2026-09-07');
const fromLength = dateRange('2026-09-01', days(7));
const fromInterval = dateRange('2026-09-01/2026-09-07');

fromEnds.duration.days; // 7
fromLength.toString(); // '2026-09-01/2026-09-07'
fromInterval.equals(fromEnds); // true

Parameters

startCalendarDateInput | stringrequired

Start date input, or a full interval string when end is omitted.

endCalendarDateInput | DurationInput | ReadOptions

Inclusive end date, duration length, or options object when start is an interval string.

optionsZone | ReadOptions

Time zone or read options applied when parsing endpoints.

3 options
zoneZone

Time zone used to extract calendar days from instant strings or Date objects.

loosebooleandefault false

Parse informal date strings and return null on unreadable input with @native-dates/plugins/loose.

dayFirstboolean

Interpret ambiguous numeric dates day-first in loose mode.

Returns

DateRange

An inclusive DateRange, or null when loose mode cannot read an endpoint.

datetimeRange()

datetimeRange(start, end, options?): DateTimeRange
datetimeRange(interval, options?): DateTimeRange

Creates a half-open DateTimeRange that includes its start moment and excludes its end. When the end input carries no explicit time zone, it is read in the start moment’s zone.

Parameters

startDateTimeInput | stringrequired

Start moment input, or an interval string when end is omitted.

endDateTimeInput | DurationInput | ReadOptions

Exclusive end moment, duration length, or options object for an interval string.

optionsZone | ReadOptions

Time zone or read options for both endpoints.

Returns

DateTimeRange

A half-open DateTimeRange, or null when loose mode cannot read an endpoint.

import { datetimeRange } from 'native-dates';

const meeting = datetimeRange('2026-09-01T09:00', '90m', 'America/New_York');
meeting.end.format('short', 'en-US'); // '9/1/26, 10:30 AM'

const zoned = datetimeRange('2026-09-01T09:00[America/New_York]/2026-09-01T10:30[America/New_York]');
zoned.start.zone; // 'America/New_York'

timeRange()

timeRange(start, end, options?): TimeRange
timeRange(interval, options?): TimeRange

Creates a half-open TimeRange between two times of day, excluding its end time. When the end time is earlier on the clock than the start time, the range wraps across midnight.

Parameters

startTimeInput | stringrequired

Start clock input, or an interval string when end is omitted.

endTimeInput | DurationInput | ReadOptions

Exclusive end time, clock duration, or options object for an interval string.

optionsZone | ReadOptions

Time zone or read options when extracting times from timestamps.

Returns

TimeRange

A half-open TimeRange, or null when loose mode cannot read an endpoint.

import { timeRange } from 'native-dates';

const office = timeRange('9am - 5pm');
const overnight = timeRange('22:00', '8h');

office.toString(); // '09:00:00/17:00:00'
overnight.toString(); // '22:00:00/06:00:00'

Interval strings and loose mode

Single-string intervals split on an ISO slash or on spaced range separators. Slashes inside bracketed IANA zone names stay untouched.

Form Example How it reads
ISO slash interval '2026-09-01/2026-09-07', '09:00/17:00' Splits on / outside bracketed time zone names, matching toString() output.
Spaced hyphen or en-dash '9am - 5pm', '2026-09-01 – 2026-09-07' Splits on - or – surrounded by spaces so hyphens inside ISO dates stay intact.
English to separator '2026-09-01 to 2026-09-07' Splits on to surrounded by spaces.
Start and length dateRange('2026-09-01', '7d'), timeRange('9am', '90m') Reads the second argument as a duration when it is a Duration, duration fields, or duration phrase.

With the loose plugin loaded, loose mode parses informal endpoints and returns null when an endpoint cannot be read:

import { dateRange } from 'native-dates';
import '@native-dates/plugins/loose';

dateRange('Sep 1, 2026 to Sep 7, 2026', { loose: true })?.toString();
// '2026-09-01/2026-09-07'

dateRange('not a range', { loose: true }); // null
Edit this pageUpdated Nov 12, 2026