Date & Time

/**
 * Parse string to Date object with format support
 * @param str - Date string to parse
 * @param formats - Array of format strings to try
 * @returns Parsed Date object or Invalid Date
 */
function toStringDate(str: string, formats?: string[]): Date;

/**
 * Get current timestamp
 * @returns Current timestamp in milliseconds
 */
function now(): number;

/**
 * Convert date to timestamp
 * @param date - Date to convert
 * @param format - Optional format for parsing string dates
 * @returns Timestamp in milliseconds
 */
function timestamp(date?: Date | string | number, format?: string): number;

/**
 * Format date to string with custom format
 * @param date - Date to format
 * @param format - Format string (default: 'yyyy-MM-dd HH:mm:ss.SSS')
 * @param options - Formatting options
 * @returns Formatted date string
 */
function toDateString(
  date: Date | string | number, 
  format?: string, 
  options?: ToDateStringOptions
): string;

interface ToDateStringOptions {
  /** Starting day of week (0=Sunday, 1=Monday, etc.) */
  firstDay?: number;
  /** Custom format templates */
  formats?: {
    /** Quarter formatting */
    q?: string[] | ((value: any, match: string, date: Date) => string);
    /** Day of week formatting */
    E?: string[] | ((value: any, match: string, date: Date) => string);
  };
}

/**
 * Check if date is valid
 * @param date - Date to validate
 * @returns True if date is valid
 */
function isValidDate(date: any): boolean;

/**
 * Check if two dates are the same based on format
 * @param date1 - First date
 * @param date2 - Second date
 * @param format - Format to compare (default: full date)
 * @returns True if dates are same according to format
 */
function isDateSame(date1: Date, date2: Date, format?: string): boolean;

/**
 * Get year from date
 * @param date - Date to analyze
 * @param startDay - Starting day for year calculation
 * @returns Year number
 */
function getWhatYear(date: Date, startDay?: number): number;

/**
 * Get quarter from date (1-4)
 * @param date - Date to analyze
 * @param startDay - Starting day for quarter calculation
 * @returns Quarter number (1-4)
 */
function getWhatQuarter(date: Date, startDay?: number): number;

/**
 * Get month from date (0-11)
 * @param date - Date to analyze
 * @param startDay - Starting day for month calculation
 * @returns Month number (0-11)
 */
function getWhatMonth(date: Date, startDay?: number): number;

/**
 * Get week number from date
 * @param date - Date to analyze
 * @param startDay - Starting day of week (0=Sunday, 1=Monday)
 * @returns Week number
 */
function getWhatWeek(date: Date, startDay?: number): number;

/**
 * Get day from date
 * @param date - Date to analyze
 * @param startDay - Starting day for day calculation
 * @returns Day number
 */
function getWhatDay(date: Date, startDay?: number): number;

/**
 * Get day of year (1-366)
 * @param date - Date to analyze
 * @returns Day of year
 */
function getYearDay(date: Date): number;

/**
 * Get day of year alias
 * @param date - Date to analyze
 * @returns Day of year
 */
function getDayOfYear(date: Date): number;

/**
 * Get day of month (1-31)
 * @param date - Date to analyze
 * @returns Day of month
 */
function getDayOfMonth(date: Date): number;

/**
 * Get week of year (1-53)
 * @param date - Date to analyze
 * @param startDay - Starting day of week
 * @returns Week of year
 */
function getYearWeek(date: Date, startDay?: number): number;

/**
 * Get week of month (1-6)
 * @param date - Date to analyze
 * @param startDay - Starting day of week
 * @returns Week of month
 */
function getMonthWeek(date: Date, startDay?: number): number;

/**
 * Calculate difference between dates
 * @param startDate - Start date
 * @param endDate - End date
 * @param unit - Unit for difference calculation
 * @returns Difference in specified unit
 */
function getDateDiff(
  startDate: Date | string | number, 
  endDate: Date | string | number, 
  unit?: 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond'
): number;

import { 
  toDateString, toStringDate, now, getDateDiff, 
  getWhatQuarter, getYearDay, isValidDate 
} from 'xe-utils';

// Current time
const currentTime = now();
console.log(currentTime); // 1672531200000

// Date formatting
const date = new Date();
console.log(toDateString(date)); // '2023-01-01 00:00:00.000'
console.log(toDateString(date, 'yyyy-MM-dd')); // '2023-01-01'
console.log(toDateString(date, 'MM/dd/yyyy HH:mm')); // '01/01/2023 00:00'

// Custom formatting
console.log(toDateString(date, 'yyyy年MM月dd日')); // '2023年01月01日'
console.log(toDateString(date, 'EEEE, MMMM dd, yyyy')); // Custom day/month names

// Date parsing
const parsed1 = toStringDate('2023-01-15');
const parsed2 = toStringDate('01/15/2023', ['MM/dd/yyyy']);
const parsed3 = toStringDate('15-01-2023', ['dd-MM-yyyy']);

// Date validation
console.log(isValidDate(new Date())); // true
console.log(isValidDate('invalid')); // false
console.log(isValidDate(new Date('2023-02-30'))); // false

// Date components
const testDate = new Date('2023-06-15');
console.log(getWhatQuarter(testDate)); // 2 (Q2)
console.log(getYearDay(testDate)); // 166 (166th day of year)

// Date differences
const start = new Date('2023-01-01');
const end = new Date('2023-12-31');

console.log(getDateDiff(start, end, 'day')); // 364
console.log(getDateDiff(start, end, 'month')); // 11
console.log(getDateDiff(start, end, 'year')); // 0

// Relative date calculations
const birthday = new Date('1990-05-15');
const today = new Date();
const age = getDateDiff(birthday, today, 'year');
console.log(`Age: ${age} years`);

// Scheduling example
function getNextMeeting(lastMeeting, intervalDays) {
  const next = new Date(lastMeeting);
  next.setDate(next.getDate() + intervalDays);
  return toDateString(next, 'yyyy-MM-dd');
}

const lastMeeting = new Date('2023-06-01');
console.log(getNextMeeting(lastMeeting, 14)); // '2023-06-15'

// International formatting
const options = {
  formats: {
    E: ['日', '一', '二', '三', '四', '五', '六'],
    q: ['第一季度', '第二季度', '第三季度', '第四季度']
  }
};

console.log(toDateString(testDate, 'EEEE', options)); // Chinese day names
console.log(toDateString(testDate, 'q季度', options)); // Chinese quarter names