/**
 * @fileoverview Date comparison, sorting, and array manipulation utilities
 */
/**
 * Compare two dates for sorting
 * @param a - First date
 * @param b - Second date
 * @returns Negative if a < b, positive if a > b, 0 if equal
 * @example
 * [date3, date1, date2].sort(compareDates) // [date1, date2, date3]
 */
export declare function compareDates(a: Date, b: Date): number;
/**
 * Compare two dates in reverse order for sorting
 * @param a - First date
 * @param b - Second date
 * @returns Positive if a < b, negative if a > b, 0 if equal
 * @example
 * [date1, date3, date2].sort(compareDatesDesc) // [date3, date2, date1]
 */
export declare function compareDatesDesc(a: Date, b: Date): number;
/**
 * Sort an array of dates
 * @param dates - Array of dates to sort
 * @param direction - Sort direction: 'asc' (oldest first) or 'desc' (newest first)
 * @returns New sorted array (does not mutate original)
 * @example
 * sortDates([date3, date1, date2]) // [date1, date2, date3]
 * sortDates([date1, date2, date3], 'desc') // [date3, date2, date1]
 */
export declare function sortDates(dates: Date[], direction?: 'asc' | 'desc'): Date[];
/**
 * Find the minimum (earliest) date in an array
 * @param dates - Array of dates
 * @returns The earliest date, or undefined if array is empty
 * @example
 * minDate([date2, date1, date3]) // date1
 */
export declare function minDate(dates: Date[]): Date | undefined;
/**
 * Find the maximum (latest) date in an array
 * @param dates - Array of dates
 * @returns The latest date, or undefined if array is empty
 * @example
 * maxDate([date1, date3, date2]) // date3
 */
export declare function maxDate(dates: Date[]): Date | undefined;
/**
 * Find the date range (min and max) in an array
 * @param dates - Array of dates
 * @returns Object with min and max dates, or undefined if array is empty
 * @example
 * dateRange([date2, date1, date3]) // { min: date1, max: date3 }
 */
export declare function dateExtent(dates: Date[]): {
    min: Date;
    max: Date;
} | undefined;
/**
 * Remove duplicate dates from an array
 * @param dates - Array of dates
 * @param precision - Precision for comparison: 'ms' (exact), 'second', 'minute', 'hour', 'day'
 * @returns New array with duplicates removed (preserves first occurrence)
 * @example
 * uniqueDates([date1, date1Copy, date2]) // [date1, date2]
 */
export declare function uniqueDates(dates: Date[], precision?: 'ms' | 'second' | 'minute' | 'hour' | 'day'): Date[];
/**
 * Find the closest date to a target from an array of candidates
 * @param target - The target date
 * @param candidates - Array of candidate dates
 * @returns The closest date, or undefined if candidates is empty
 * @example
 * closestDate(targetDate, [date1, date2, date3]) // closest to target
 */
export declare function closestDate(target: Date, candidates: Date[]): Date | undefined;
/**
 * Find the closest future date to a target
 * @param target - The target date
 * @param candidates - Array of candidate dates
 * @returns The closest future date, or undefined if none found
 */
export declare function closestFutureDate(target: Date, candidates: Date[]): Date | undefined;
/**
 * Find the closest past date to a target
 * @param target - The target date
 * @param candidates - Array of candidate dates
 * @returns The closest past date, or undefined if none found
 */
export declare function closestPastDate(target: Date, candidates: Date[]): Date | undefined;
/**
 * Clamp a date to be within a range
 * @param date - The date to clamp
 * @param min - Minimum allowed date
 * @param max - Maximum allowed date
 * @returns The clamped date
 * @example
 * clampDate(earlyDate, minDate, maxDate) // returns minDate
 * clampDate(lateDate, minDate, maxDate) // returns maxDate
 * clampDate(middleDate, minDate, maxDate) // returns middleDate
 */
export declare function clampDate(date: Date, min: Date, max: Date): Date;
/**
 * Check if a date is within a range (inclusive)
 * @param date - The date to check
 * @param min - Start of range
 * @param max - End of range
 * @returns True if date is within range
 */
export declare function isDateInRange(date: Date, min: Date, max: Date): boolean;
/**
 * Filter dates to only those within a range
 * @param dates - Array of dates
 * @param min - Start of range
 * @param max - End of range
 * @returns New array with only dates in range
 */
export declare function filterDatesInRange(dates: Date[], min: Date, max: Date): Date[];
/**
 * Group dates by a key function
 * @param dates - Array of dates
 * @param keyFn - Function to generate group key from date
 * @returns Map of key to array of dates
 * @example
 * groupDates(dates, d => d.getFullYear()) // Map { 2023 => [...], 2024 => [...] }
 * groupDates(dates, d => d.toISOString().slice(0, 7)) // Group by month
 */
export declare function groupDates<K>(dates: Date[], keyFn: (date: Date) => K): Map<K, Date[]>;
/**
 * Group dates by year
 * @param dates - Array of dates
 * @returns Map of year to array of dates
 */
export declare function groupDatesByYear(dates: Date[]): Map<number, Date[]>;
/**
 * Group dates by month (YYYY-MM format)
 * @param dates - Array of dates
 * @returns Map of month key to array of dates
 */
export declare function groupDatesByMonth(dates: Date[]): Map<string, Date[]>;
/**
 * Group dates by day (YYYY-MM-DD format)
 * @param dates - Array of dates
 * @returns Map of day key to array of dates
 */
export declare function groupDatesByDay(dates: Date[]): Map<string, Date[]>;
/**
 * Group dates by day of week (0-6, Sunday-Saturday)
 * @param dates - Array of dates
 * @returns Map of day of week to array of dates
 */
export declare function groupDatesByDayOfWeek(dates: Date[]): Map<number, Date[]>;
/**
 * Calculate the median date from an array
 * @param dates - Array of dates
 * @returns The median date, or undefined if array is empty
 */
export declare function medianDate(dates: Date[]): Date | undefined;
/**
 * Calculate the average/mean date from an array
 * @param dates - Array of dates
 * @returns The average date, or undefined if array is empty
 */
export declare function averageDate(dates: Date[]): Date | undefined;
/**
 * Round a date to the nearest unit
 * @param date - The date to round
 * @param unit - Unit to round to
 * @returns New rounded date
 * @example
 * roundDate(new Date('2024-03-15T14:37:00'), 'hour') // 2024-03-15T15:00:00
 * roundDate(new Date('2024-03-15T14:22:00'), 'hour') // 2024-03-15T14:00:00
 */
export declare function roundDate(date: Date, unit: 'minute' | 'hour' | 'day'): Date;
/**
 * Snap a date to a grid interval
 * @param date - The date to snap
 * @param intervalMinutes - Interval in minutes (e.g., 15 for quarter-hour)
 * @param mode - Snap mode: 'floor' (down), 'ceil' (up), or 'round' (nearest)
 * @returns New snapped date
 * @example
 * snapDate(new Date('2024-03-15T14:37:00'), 15) // 2024-03-15T14:30:00
 * snapDate(new Date('2024-03-15T14:37:00'), 15, 'ceil') // 2024-03-15T14:45:00
 */
export declare function snapDate(date: Date, intervalMinutes: number, mode?: 'floor' | 'ceil' | 'round'): Date;
/**
 * Check if dates are in chronological order
 * @param dates - Array of dates
 * @param strict - If true, requires strictly increasing (no duplicates)
 * @returns True if dates are in order
 */
export declare function isChronological(dates: Date[], strict?: boolean): boolean;
/**
 * Get the span (duration) between min and max dates
 * @param dates - Array of dates
 * @returns Duration in milliseconds, or 0 if less than 2 dates
 */
export declare function dateSpan(dates: Date[]): number;
/**
 * Partition dates into buckets based on a predicate
 * @param dates - Array of dates
 * @param predicate - Function that returns true for dates in first partition
 * @returns Tuple of [matching, non-matching] date arrays
 */
export declare function partitionDates(dates: Date[], predicate: (date: Date) => boolean): [Date[], Date[]];
/**
 * Get the nth date from an array (supports negative indices)
 * @param dates - Array of dates (will be sorted)
 * @param n - Index (0-based, negative counts from end)
 * @returns The nth date, or undefined if out of bounds
 * @example
 * nthDate(dates, 0) // earliest
 * nthDate(dates, -1) // latest
 * nthDate(dates, 2) // third earliest
 */
export declare function nthDate(dates: Date[], n: number): Date | undefined;
/**
 * Find the index of the closest date to a target in an array
 * @param dates - Array of candidate dates
 * @param target - The target date
 * @returns Index of the closest date, or -1 if array is empty
 * @example
 * closestIndexTo([date1, date2, date3], targetDate) // 1
 */
export declare function closestIndexTo(dates: Date[], target: Date): number;
/**
 * Get the number of overlapping days between two date ranges
 * @param range1 - First range { start, end }
 * @param range2 - Second range { start, end }
 * @returns Number of overlapping days (0 if no overlap)
 * @example
 * getOverlappingDaysInIntervals(
 *   { start: new Date('2024-01-01'), end: new Date('2024-01-10') },
 *   { start: new Date('2024-01-05'), end: new Date('2024-01-15') }
 * ) // 6 (Jan 5-10 inclusive)
 */
export declare function getOverlappingDaysInIntervals(range1: {
    start: Date;
    end: Date;
}, range2: {
    start: Date;
    end: Date;
}): number;
//# sourceMappingURL=compare.d.ts.map