Compare

Sort, group, and analyze date arrays

Import

import { ... } from 'ts-time-utils/compare';

Examples

Sort & Filter

Sort dates and find min/max

import { sortDates, minDate, maxDate, closestDate } from 'ts-time-utils/compare';

const dates = [
  new Date('2025-09-15'),
  new Date('2025-01-01'),
  new Date('2025-12-31'),
  new Date('2025-06-15'),
];

// Sort dates
console.log(sortDates(dates, 'asc').map(d => d.toDateString()));
console.log(sortDates(dates, 'desc').map(d => d.toDateString()));

// Find min/max
console.log('Earliest:', minDate(dates).toDateString());
console.log('Latest:', maxDate(dates).toDateString());

// Find closest to target
const target = new Date('2025-07-01');
console.log('Closest to July 1:', closestDate(target, dates).toDateString());

Group Dates

Group dates by year, month, or day of week

import { groupDatesByMonth, groupDatesByYear, snapDate } from 'ts-time-utils/compare';

const dates = [
  new Date('2025-01-15'),
  new Date('2025-01-20'),
  new Date('2025-02-10'),
  new Date('2025-02-25'),
  new Date('2025-03-05'),
];

// Group by month (returns Map<string, Date[]>)
const byMonth = groupDatesByMonth(dates);
byMonth.forEach((monthDates, month) => {
  console.log(`${month}: ${monthDates.length} dates`);
});

// Snap to intervals (intervalMinutes)
const meeting = new Date('2025-09-14T14:37:00');
console.log('Original:', meeting.toTimeString());
console.log('Snapped to 15min:', snapDate(meeting, 15).toTimeString());
console.log('Snapped to hour:', snapDate(meeting, 60).toTimeString());