native-dates

API / Functions

compare() function

Sort and pick boundary values across dates, moments, times, durations, and ranges.

import { compare, earliest, latest } from 'native-dates'core 7.3 kB min+br

Sorting and ordering

compare()

compare(a, b): -1 | 0 | 1

Orders two values of the same kind for Array.prototype.sort(), returning negative, zero, or positive numbers. Works across moments, calendar dates, clock times, durations, and range instances.

When the first argument is a typed point or Duration, a raw second argument such as an ISO string is read as the same kind. Comparing two different kinds throws a TypeError.

sort.js
import { compare, date, datetime, hours, minutes } from 'native-dates';

const dates = [date('2026-12-01'), date('2026-05-10'), date('2026-08-20')];
dates.sort(compare).map(String); // ['2026-05-10', '2026-08-20', '2026-12-01']

const moments = [
  datetime('2026-11-16T18:00', 'Europe/Berlin'),
  datetime('2026-11-16T08:00', 'America/Los_Angeles'),
];
moments.sort(compare)[0].zone; // 'America/Los_Angeles'

const spans = [hours(2), minutes(45), minutes(90)].sort(compare);
spans[0].minutes; // 45

Parameters

aPoint | Duration | Rangerequired

First typed value to compare.

bPoint | Duration | Rangerequired

Second value of the same kind, or a raw input matching a.

Returns

-1 | 0 | 1

Returns -1 when the first value comes earlier, 0 when equal, and 1 when later.

Ranges of the same kind sort by their start point first and break ties by their end point:

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

const windows = [
  dateRange('2026-11-10', '2026-11-20'),
  dateRange('2026-11-10', '2026-11-14'),
  dateRange('2026-11-01', '2026-11-05'),
];

windows.sort(compare).map(String);
// ['2026-11-01/2026-11-05', '2026-11-10/2026-11-14', '2026-11-10/2026-11-20']

Comparing moments across time zones

compare() orders DateTime values by their exact instant rather than their local clock digits. A 9:00 AM meeting in New York sorts before an 8:00 AM meeting on the same day in Los Angeles.

Picking boundary points

Find the minimum or maximum point across a set of dates, moments, or clock times. Both helpers accept rest arguments or a single non-empty array.

earliest()

earliest(...points): DateTime | CalendarDate | Time
earliest(points): DateTime | CalendarDate | Time

Returns the earliest point from one or more arguments or a non-empty array of the same kind. Passing an empty array throws a RangeError.

Parameters

pointsPoint[]required

One or more dates, moments, or clock times of the same kind, passed as arguments or an array.

Returns

DateTime | CalendarDate | Time

The point that comes first. Equal moments keep the earlier item in the list.

import { date, earliest, time } from 'native-dates';

earliest(date('2026-11-20'), date('2026-11-04'), date('2026-11-16')).toString(); // '2026-11-04'
earliest([time('5:30pm'), time('9:00am'), time('12:15pm')]).toString(); // '09:00:00'

latest()

latest(...points): DateTime | CalendarDate | Time
latest(points): DateTime | CalendarDate | Time

Returns the latest point from one or more arguments or a non-empty array of the same kind. Passing an empty array throws a RangeError.

Parameters

pointsPoint[]required

One or more dates, moments, or clock times of the same kind, passed as arguments or an array.

Returns

DateTime | CalendarDate | Time

The point that comes last. Equal moments keep the earlier item in the list.

Combine earliest() and latest() to clamp a value between two bounds:

import { date, earliest, latest } from 'native-dates';

const minDate = date('2026-11-01');
const maxDate = date('2026-11-30');
const picked = date('2026-12-12');

const clamped = earliest(maxDate, latest(minDate, picked));
clamped.toString(); // '2026-11-30'
Edit this pageUpdated Nov 12, 2026