houser-js-utils/dist/DateUtils.d.ts

A comprehensive collection of TypeScript utility functions for common development tasks including array manipulation, string processing, date handling, random number generation, validation, and much more.

/**
 * @module DateUtils
 * @description Utility functions for date manipulation and calculations.
 *
 * This module provides a comprehensive set of functions for working with dates,
 * including date arithmetic, comparisons, formatting, and validation.
 *
 * @example
 * ```typescript
 * import { DateUtils } from 'houser-js-utils';
 *
 * // Add 2 days to current date
 * const tomorrow = DateUtils.add({ days: 2 });
 *
 * // Calculate age
 * const age = DateUtils.calculateAge(new Date('1990-01-01'));
 *
 * // Check if date is weekend
 * const isWeekend = DateUtils.isWeekend(new Date());
 * ```
 */
export type DateArg = Date | number | string;
/**
 * Supported time units for date calculations
 */
export type TimeUnit = "years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds";
/**
 * Object type for specifying time units and their values
 */
export type TimeUnitArgs = {
    [K in TimeUnit]?: number;
};
export declare const DateUtils: {
    /**
     * Adds specified time units to a date.
     * @param args - Object containing time units to add
     * @param date - Date to add to (defaults to current date)
     * @returns New date with added time units
     * @throws {Error} If any time unit is negative
     * @example
     * ```typescript
     * DateUtils.add({ days: 7, hours: 2 }); // Add 7 days and 2 hours to now
     * DateUtils.add({ months: 1 }, new Date('2023-01-15')); // Add 1 month to specific date
     * ```
     */
    add(args: TimeUnitArgs, date?: DateArg): Date;
    /**
     * Internal helper for modifying a date by adding or subtracting time units
     * @param args - Object containing time units
     * @param date - Date to modify
     * @param direction - 1 for addition, -1 for subtraction
     * @returns New date with modified time units
     */
    adjustDate(args: TimeUnitArgs, date: DateArg, direction: 1 | -1): Date;
    /**
     * Calculates age based on birth date
     * @param date - Birth date to calculate age from
     * @returns Age in years or null if date is invalid
     */
    calculateAge(date: Date | string | null): number | null;
    /**
     * Calculates the number of days between two dates
     * @param first - First date
     * @param second - Second date
     * @returns Number of days between dates
     */
    calculateDaysBetween(first: DateArg, second: DateArg): number;
    /**
     * Compares two dates and returns the result based on order parameter
     * @param a - First date to compare
     * @param b - Second date to compare
     * @param order - Sort order ('asc' or 'desc')
     * @returns Comparison result (-1, 0, or 1)
     */
    compareDates(a: DateArg, b: DateArg, order?: "asc" | "desc"): number;
    /**
     * Converts various date formats to a Date object
     * @param dateStr - Date to convert (Date, number, or string)
     * @returns Date object
     * @throws Error if date string is invalid
     */
    convertToDate(dateStr: DateArg): Date;
    /**
     * Copies time from one date to another
     * @param fromDate - Source date to copy time from
     * @param toDate - Target date to copy time to
     * @returns New date with copied time
     */
    copyTimeToDate(fromDate: DateArg, toDate: DateArg): Date;
    /**
     * Returns the age in years between two dates
     * @param birthDate - Birth date
     * @param referenceDate - Reference date (defaults to current date)
     * @returns Age in years
     */
    getAge(birthDate: DateArg, referenceDate?: DateArg): number;
    /**
     * Returns the number of days in a given month
     * @param year - Year to check
     * @param month - Month to check (0-11)
     * @returns Number of days in the month
     */
    getDaysInMonth(year: number, month: number): number;
    /**
     * Returns the number of days between two dates, inclusive
     * @param startDate - Start date
     * @param endDate - End date
     * @returns Number of days between dates, inclusive
     */
    getDaysBetweenInclusive(startDate: DateArg, endDate: DateArg): number;
    /**
     * Returns the first day of the month
     * @param date - Date to get first day of month for (defaults to current date)
     * @returns Date set to first day of month
     */
    getFirstDayOfMonth(date?: DateArg): Date;
    /**
     * Returns the first day of the quarter
     * @param date - Date to get first day of quarter for (defaults to current date)
     * @returns Date set to first day of quarter
     */
    getFirstDayOfQuarter(date?: DateArg): Date;
    /**
     * Returns the first day of the week (Sunday)
     * @param date - Date to get first day of week for (defaults to current date)
     * @returns Date set to first day of week
     */
    getFirstDayOfWeek(date?: DateArg): Date;
    /**
     * Returns the first day of the year
     * @param date - Date to get first day of year for (defaults to current date)
     * @returns Date set to first day of year
     */
    getFirstDayOfYear(date?: DateArg): Date;
    /**
     * Returns the end of the day (23:59:59.999)
     * @param date - Date to get end of day for (defaults to current date)
     * @returns Date set to end of day
     */
    getEndOfDay(date?: DateArg): Date;
    /**
     * Returns the last day of the month
     * @param date - Date to get last day of month for (defaults to current date)
     * @returns Date set to last day of month
     */
    getLastDayOfMonth(date?: DateArg): Date;
    /**
     * Returns the last day of the quarter
     * @param date - Date to get last day of quarter for (defaults to current date)
     * @returns Date set to last day of quarter
     */
    getLastDayOfQuarter(date?: DateArg): Date;
    /**
     * Returns the last day of the week (Saturday)
     * @param date - Date to get last day of week for (defaults to current date)
     * @returns Date set to last day of week
     */
    getLastDayOfWeek(date?: DateArg): Date;
    /**
     * Returns the last day of the year
     * @param date - Date to get last day of year for (defaults to current date)
     * @returns Date set to last day of year
     */
    getLastDayOfYear(date?: DateArg): Date;
    /**
     * Returns the quarter (1-4) of the year
     * @param date - Date to get quarter for (defaults to current date)
     * @returns Quarter number
     */
    getQuarter(date?: DateArg): number;
    /**
     * Returns the start of the day (00:00:00.000)
     * @param date - Date to get start of day for (defaults to current date)
     * @returns Date set to start of day
     */
    getStartOfDay(date?: DateArg): Date;
    /**
     * Returns the week number of the year (1-53)
     * @param date - Date to get week number for (defaults to current date)
     * @returns Week number
     */
    getWeekNumber(date?: DateArg): number;
    /**
     * Checks if a date is after another date
     * @param date1 - First date to compare
     * @param date2 - Second date to compare
     * @returns True if date1 is after date2
     */
    isAfter(date1: DateArg, date2: DateArg): boolean;
    /**
     * Checks if a date is before another date
     * @param date1 - First date to compare
     * @param date2 - Second date to compare
     * @returns True if date1 is before date2
     */
    isBefore(date1: DateArg, date2: DateArg): boolean;
    /**
     * Checks if a date is in the past
     * @param date - Date to check
     * @returns True if date is in the past
     */
    isDateInThePast(date: DateArg): boolean;
    /**
     * Checks if two dates are the same day
     * @param date1 - First date to compare
     * @param date2 - Second date to compare
     * @returns True if dates are the same day
     */
    isSameDay(date1: DateArg, date2: DateArg): boolean;
    /**
     * Checks if two dates have the same time
     * @param date1 - First date to compare
     * @param date2 - Second date to compare
     * @returns True if dates have the same time
     */
    isSameTime(date1: DateArg, date2: DateArg): boolean;
    /**
     * Checks if a date is today
     * @param date - Date to check
     * @returns True if date is today
     */
    isToday(date: DateArg): boolean;
    /**
     * Checks if a date is tomorrow
     * @param date - Date to check
     * @returns True if date is tomorrow
     */
    isTomorrow(date: DateArg): boolean;
    /**
     * Checks if a date is valid
     * @param date - Date to check
     * @returns True if date is valid
     */
    isValidDate(date: DateArg): boolean;
    /**
     * Checks if a date falls on a weekday
     * @param date - Date to check
     * @returns True if the date is a weekday
     */
    isWeekday(date: DateArg): boolean;
    /**
     * Checks if a date falls on a weekend
     * @param date - Date to check
     * @returns True if the date is a weekend
     */
    isWeekend(date: DateArg): boolean;
    /**
     * Checks if a date is yesterday
     * @param date - Date to check
     * @returns True if date is yesterday
     */
    isYesterday(date: DateArg): boolean;
    /**
     * Normalizes a date to UTC midnight
     * @param date - Date to normalize
     * @returns Normalized date or null if invalid
     */
    normalizeDate(date: DateArg): Date | null;
    /**
     * Subtracts specified time units from a date
     * @param args - Object containing time units to subtract
     * @param date - Date to subtract from (defaults to current date)
     * @returns New date with subtracted time units
     * @throws Error if any time unit is negative
     */
    subtract(args: TimeUnitArgs, date?: DateArg): Date;
    /**
     * Converts a date to a local ISO string
     * @param date - Date to convert
     * @returns Local ISO string representation
     */
    toLocalISOString(date: Date): string;
    /**
     * Validates time unit arguments
     * @param args - Time unit arguments to validate
     * @throws Error if any time unit is negative
     */
    validateTimeUnits(args: TimeUnitArgs): void;
};