/**
 * @fileoverview Countdown and timer utilities for tracking time until/since a target date
 * Provides countdown timers, remaining time calculations, and progress tracking
 */
import type { DateInput } from './types.js';
/**
 * Represents the remaining time broken down by units
 */
export interface RemainingTime {
    /** Total milliseconds remaining */
    totalMilliseconds: number;
    /** Total seconds remaining */
    totalSeconds: number;
    /** Total minutes remaining */
    totalMinutes: number;
    /** Total hours remaining */
    totalHours: number;
    /** Total days remaining */
    totalDays: number;
    /** Milliseconds component (0-999) */
    milliseconds: number;
    /** Seconds component (0-59) */
    seconds: number;
    /** Minutes component (0-59) */
    minutes: number;
    /** Hours component (0-23) */
    hours: number;
    /** Days component */
    days: number;
    /** Weeks component */
    weeks: number;
    /** Whether the target date has passed */
    isExpired: boolean;
}
/**
 * Options for countdown creation
 */
export interface CountdownOptions {
    /** Callback fired on each tick */
    onTick?: (remaining: RemainingTime) => void;
    /** Callback fired when countdown reaches zero */
    onComplete?: () => void;
    /** Callback fired if target date is in the past */
    onExpired?: () => void;
    /** Tick interval in milliseconds (default: 1000) */
    interval?: number;
    /** Whether to fire onTick immediately (default: true) */
    immediate?: boolean;
}
/**
 * Countdown timer instance
 */
export interface Countdown {
    /** Start the countdown */
    start: () => void;
    /** Stop the countdown */
    stop: () => void;
    /** Reset countdown with a new target date */
    reset: (targetDate: DateInput) => void;
    /** Get current remaining time */
    getRemaining: () => RemainingTime;
    /** Check if countdown is running */
    isRunning: () => boolean;
    /** Check if target date has passed */
    isExpired: () => boolean;
}
/**
 * Creates a countdown timer to a target date
 * @param targetDate - The date to count down to
 * @param options - Countdown options and callbacks
 * @returns A countdown instance with control methods
 *
 * @example
 * ```ts
 * const countdown = createCountdown(
 *   new Date('2024-12-31T23:59:59'),
 *   {
 *     onTick: (remaining) => {
 *       console.log(`${remaining.days}d ${remaining.hours}h ${remaining.minutes}m ${remaining.seconds}s`);
 *     },
 *     onComplete: () => {
 *       console.log('Happy New Year!');
 *     }
 *   }
 * );
 *
 * countdown.start();
 * // Later...
 * countdown.stop();
 * ```
 */
export declare function createCountdown(targetDate: DateInput, options?: CountdownOptions): Countdown;
/**
 * Gets the remaining time until/since a target date
 * @param targetDate - The target date
 * @param fromDate - The date to calculate from (defaults to now)
 * @returns Object with remaining time broken down by units
 *
 * @example
 * ```ts
 * const remaining = getRemainingTime(new Date('2024-12-31'));
 * console.log(`${remaining.days} days, ${remaining.hours} hours remaining`);
 *
 * // Check if expired
 * if (remaining.isExpired) {
 *   console.log('Target date has passed');
 * }
 * ```
 */
export declare function getRemainingTime(targetDate: DateInput, fromDate?: DateInput): RemainingTime;
/**
 * Formats the remaining time as a human-readable string
 * @param targetDate - The target date
 * @param options - Formatting options
 * @returns Formatted countdown string
 *
 * @example
 * ```ts
 * formatCountdown(new Date('2024-12-31'));
 * // "45d 12h 30m 15s"
 *
 * formatCountdown(new Date('2024-12-31'), { units: ['days', 'hours'] });
 * // "45 days, 12 hours"
 *
 * formatCountdown(new Date('2024-12-31'), { short: false });
 * // "45 days 12 hours 30 minutes 15 seconds"
 * ```
 */
export declare function formatCountdown(targetDate: DateInput, options?: {
    /** Date to calculate from (defaults to now) */
    from?: DateInput;
    /** Units to include in output */
    units?: ('weeks' | 'days' | 'hours' | 'minutes' | 'seconds' | 'milliseconds')[];
    /** Use short format (d, h, m, s) */
    short?: boolean;
    /** Maximum number of units to show */
    maxUnits?: number;
    /** Show zero values */
    showZero?: boolean;
    /** Separator between units */
    separator?: string;
}): string;
/**
 * Checks if a date has expired (is in the past)
 * @param date - The date to check
 * @param fromDate - The reference date (defaults to now)
 * @returns True if the date is in the past
 *
 * @example
 * ```ts
 * isExpired(new Date('2020-01-01')); // true
 * isExpired(new Date('2030-01-01')); // false
 * ```
 */
export declare function isExpired(date: DateInput, fromDate?: DateInput): boolean;
/**
 * Calculates the progress percentage between two dates
 * @param startDate - The start date
 * @param endDate - The end date
 * @param currentDate - The current date (defaults to now)
 * @returns Progress percentage (0-100), clamped to range
 *
 * @example
 * ```ts
 * const progress = getProgressPercentage(
 *   new Date('2024-01-01'),
 *   new Date('2024-12-31'),
 *   new Date('2024-07-01')
 * );
 * console.log(`${progress}% complete`); // ~50% complete
 * ```
 */
export declare function getProgressPercentage(startDate: DateInput, endDate: DateInput, currentDate?: DateInput): number;
/**
 * Gets time until a target date in a specific unit
 * @param targetDate - The target date
 * @param unit - The unit to return
 * @param fromDate - The date to calculate from (defaults to now)
 * @returns Time remaining in the specified unit
 *
 * @example
 * ```ts
 * getTimeUntil(new Date('2024-12-31'), 'days'); // 45.5
 * getTimeUntil(new Date('2024-12-31'), 'hours'); // 1092
 * getTimeUntil(new Date('2024-12-31'), 'weeks'); // 6.5
 * ```
 */
export declare function getTimeUntil(targetDate: DateInput, unit: 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks', fromDate?: DateInput): number;
/**
 * Creates a deadline object with useful methods
 * @param targetDate - The deadline date
 * @returns An object with deadline-related methods
 *
 * @example
 * ```ts
 * const deadline = createDeadline(new Date('2024-12-31'));
 *
 * deadline.isExpired(); // false
 * deadline.daysRemaining(); // 45
 * deadline.hoursRemaining(); // 1092
 * deadline.formatRemaining(); // "45d 12h 30m"
 * deadline.progressFrom(new Date('2024-01-01')); // 67.5%
 * ```
 */
export declare function createDeadline(targetDate: DateInput): {
    target: Date;
    isExpired: () => boolean;
    getRemaining: () => RemainingTime;
    daysRemaining: () => number;
    hoursRemaining: () => number;
    minutesRemaining: () => number;
    secondsRemaining: () => number;
    formatRemaining: (options?: Parameters<typeof formatCountdown>[1]) => string;
    progressFrom: (startDate: DateInput) => number;
    countdown: (options?: CountdownOptions) => Countdown;
};
//# sourceMappingURL=countdown.d.ts.map