Date Queries

/**
 * Checks if dates occur on same day (cross-calendar)
 * @param a - First date to compare
 * @param b - Second date to compare  
 * @returns true if dates represent the same day
 */
function isSameDay(a: DateValue, b: DateValue): boolean;

/**
 * Checks if dates occur in same month
 * @param a - First date to compare
 * @param b - Second date to compare
 * @returns true if dates are in the same month
 */
function isSameMonth(a: DateValue, b: DateValue): boolean;

/**
 * Checks if dates occur in same year
 * @param a - First date to compare
 * @param b - Second date to compare
 * @returns true if dates are in the same year
 */
function isSameYear(a: DateValue, b: DateValue): boolean;

/**
 * Checks if dates are same day and calendar system
 * @param a - First date to compare
 * @param b - Second date to compare
 * @returns true if dates are equal in same calendar
 */
function isEqualDay(a: DateValue, b: DateValue): boolean;

/**
 * Checks if dates are same month and calendar system
 * @param a - First date to compare
 * @param b - Second date to compare
 * @returns true if dates are equal month in same calendar
 */
function isEqualMonth(a: DateValue, b: DateValue): boolean;

/**
 * Checks if dates are same year and calendar system
 * @param a - First date to compare
 * @param b - Second date to compare
 * @returns true if dates are equal year in same calendar
 */
function isEqualYear(a: DateValue, b: DateValue): boolean;

/**
 * Checks if two calendars are the same
 * @param a - First calendar to compare
 * @param b - Second calendar to compare
 * @returns true if calendars are identical
 */
function isEqualCalendar(a: Calendar, b: Calendar): boolean;

type DateValue = CalendarDate | CalendarDateTime | ZonedDateTime;

import { 
  isSameDay, 
  isSameMonth, 
  isEqualDay,
  CalendarDate,
  createCalendar 
} from "@internationalized/date";

const gregorianDate = new CalendarDate(2024, 3, 15);
const buddhistDate = new CalendarDate(createCalendar('buddhist'), 2567, 3, 15);
const differentDay = new CalendarDate(2024, 3, 16);

// Cross-calendar comparison (same absolute day)
const sameDay = isSameDay(gregorianDate, buddhistDate); // true
const equalDay = isEqualDay(gregorianDate, buddhistDate); // false (different calendars)

// Same calendar comparison
const sameGregorianDay = isEqualDay(gregorianDate, differentDay); // false
const sameMonth = isSameMonth(gregorianDate, differentDay); // true

/**
 * Returns current time in timezone
 * @param timeZone - IANA timezone identifier
 * @returns ZonedDateTime representing current moment in timezone
 */
function now(timeZone: string): ZonedDateTime;

/**
 * Returns today's date in timezone
 * @param timeZone - IANA timezone identifier  
 * @returns CalendarDate representing today in timezone
 */
function today(timeZone: string): CalendarDate;

/**
 * Checks if date is today in given timezone
 * @param date - Date to check
 * @param timeZone - IANA timezone identifier
 * @returns true if date represents today
 */
function isToday(date: DateValue, timeZone: string): boolean;

import { now, today, isToday, CalendarDate } from "@internationalized/date";

// Get current time in different timezones
const nowUTC = now('UTC');
const nowNY = now('America/New_York');
const nowTokyo = now('Asia/Tokyo');

// Get today's date
const todayUTC = today('UTC');
const todayLocal = today('America/Los_Angeles');

// Check if a date is today
const someDate = new CalendarDate(2024, 3, 15);
const isTodayCheck = isToday(someDate, 'UTC');

/**
 * Gets day of week number for locale
 * @param date - Date to get day of week for
 * @param locale - Locale identifier (e.g., 'en-US', 'de-DE')
 * @param firstDayOfWeek - Optional first day of week override
 * @returns Day of week number (0-6)
 */
function getDayOfWeek(date: DateValue, locale: string, firstDayOfWeek?: DayOfWeek): number;

/**
 * Checks if date falls on weekend for locale
 * @param date - Date to check
 * @param locale - Locale identifier
 * @returns true if date is a weekend day
 */
function isWeekend(date: DateValue, locale: string): boolean;

/**
 * Checks if date falls on weekday for locale
 * @param date - Date to check
 * @param locale - Locale identifier
 * @returns true if date is a weekday
 */
function isWeekday(date: DateValue, locale: string): boolean;

type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6; // Sunday = 0, Monday = 1, etc.

import { 
  getDayOfWeek, 
  isWeekend, 
  isWeekday,
  CalendarDate 
} from "@internationalized/date";

const date = new CalendarDate(2024, 3, 15); // Friday

// Get day of week in different locales
const dayUS = getDayOfWeek(date, 'en-US'); // 5 (Friday, Sunday = 0)
const dayDE = getDayOfWeek(date, 'de-DE'); // 5 (Friday, Monday = 1)

// Check weekend/weekday for different locales
const weekendUS = isWeekend(date, 'en-US'); // false (Friday)
const weekdayUS = isWeekday(date, 'en-US'); // true

// Some locales have different weekend days
const weekendSA = isWeekend(date, 'ar-SA'); // true (Friday is weekend in Saudi Arabia)

/**
 * Returns first date of the month
 */
function startOfMonth<T extends DateValue>(date: T): T;

/**
 * Returns first date of the week
 * @param date - Date to get start of week for
 * @param locale - Locale identifier for week conventions
 * @param firstDayOfWeek - Optional first day of week override
 * @returns First date of the week
 */
function startOfWeek(date: DateValue, locale: string, firstDayOfWeek?: DayOfWeek): DateValue;

/**
 * Returns first date of the year
 */
function startOfYear<T extends DateValue>(date: T): T;

/**
 * Returns last date of the month
 */
function endOfMonth<T extends DateValue>(date: T): T;

/**
 * Returns last date of the week
 * @param date - Date to get end of week for
 * @param locale - Locale identifier for week conventions
 * @param firstDayOfWeek - Optional first day of week override
 * @returns Last date of the week
 */
function endOfWeek(date: DateValue, locale: string, firstDayOfWeek?: DayOfWeek): DateValue;

/**
 * Returns last date of the year
 */
function endOfYear<T extends DateValue>(date: T): T;

import { 
  startOfMonth, 
  endOfMonth,
  startOfWeek,
  endOfWeek,
  startOfYear,
  endOfYear,
  CalendarDate 
} from "@internationalized/date";

const date = new CalendarDate(2024, 3, 15); // March 15, 2024

// Month boundaries
const monthStart = startOfMonth(date); // March 1, 2024
const monthEnd = endOfMonth(date); // March 31, 2024

// Week boundaries (locale-dependent)
const weekStartUS = startOfWeek(date, 'en-US'); // March 10, 2024 (Sunday)
const weekEndUS = endOfWeek(date, 'en-US'); // March 16, 2024 (Saturday)

const weekStartDE = startOfWeek(date, 'de-DE'); // March 11, 2024 (Monday)
const weekEndDE = endOfWeek(date, 'de-DE'); // March 17, 2024 (Sunday)

// Year boundaries
const yearStart = startOfYear(date); // January 1, 2024
const yearEnd = endOfYear(date); // December 31, 2024

/**
 * Gets minimum month number in year (calendar-specific)
 * @param date - Date to get minimum month for
 * @returns Minimum month number (usually 1, but varies in some calendars)
 */
function getMinimumMonthInYear(date: AnyCalendarDate): number;

/**
 * Gets minimum day number in month (calendar-specific)
 * @param date - Date to get minimum day for
 * @returns Minimum day number (usually 1, but varies in some calendars)
 */
function getMinimumDayInMonth(date: AnyCalendarDate): number;

/**
 * Gets number of weeks in month
 * @param date - Date in the month to analyze
 * @param locale - Locale identifier for week conventions
 * @param firstDayOfWeek - Optional first day of week override
 * @returns Number of weeks in the month (4-6)
 */
function getWeeksInMonth(date: DateValue, locale: string, firstDayOfWeek?: DayOfWeek): number;

import { 
  getMinimumMonthInYear,
  getMinimumDayInMonth,
  getWeeksInMonth,
  CalendarDate,
  createCalendar 
} from "@internationalized/date";

const gregorianDate = new CalendarDate(2024, 3, 15);
const japaneseDate = new CalendarDate(createCalendar('japanese'), 'reiwa', 6, 3, 15);

// Most calendars start at 1
const gregMinMonth = getMinimumMonthInYear(gregorianDate); // 1
const gregMinDay = getMinimumDayInMonth(gregorianDate); // 1

// Japanese calendar may have different minimums due to era transitions
const japMinMonth = getMinimumMonthInYear(japaneseDate); // May be > 1 if era started mid-year
const japMinDay = getMinimumDayInMonth(japaneseDate); // May be > 1 if era started mid-month

// Weeks in month varies by calendar layout
const weeksInMarch = getWeeksInMonth(gregorianDate, 'en-US'); // 5 or 6 depending on year

/**
 * Gets hours in day (accounts for DST)
 * @param date - Date to check
 * @param timeZone - IANA timezone identifier
 * @returns Number of hours in the day (23, 24, or 25 depending on DST)
 */
function getHoursInDay(date: CalendarDate, timeZone: string): number;

/**
 * Gets user's local timezone identifier
 * @returns IANA timezone identifier for user's location
 */
function getLocalTimeZone(): string;

/**
 * Sets local timezone identifier
 * @param timeZone - IANA timezone identifier to set as local
 */
function setLocalTimeZone(timeZone: string): void;

/**
 * Resets local timezone to system default
 */
function resetLocalTimeZone(): void;

import { 
  getHoursInDay,
  getLocalTimeZone,
  setLocalTimeZone,
  resetLocalTimeZone,
  CalendarDate 
} from "@internationalized/date";

// DST transitions affect hours in day
const springForward = new CalendarDate(2024, 3, 10); // Spring DST in US
const fallBack = new CalendarDate(2024, 11, 3); // Fall DST in US
const normalDay = new CalendarDate(2024, 6, 15); // Summer day

const hoursSpring = getHoursInDay(springForward, 'America/New_York'); // 23 hours
const hoursFall = getHoursInDay(fallBack, 'America/New_York'); // 25 hours  
const hoursNormal = getHoursInDay(normalDay, 'America/New_York'); // 24 hours

// Local timezone management
const currentLocal = getLocalTimeZone(); // e.g., 'America/New_York'

setLocalTimeZone('Europe/London');
const newLocal = getLocalTimeZone(); // 'Europe/London'

resetLocalTimeZone();
const resetLocal = getLocalTimeZone(); // Back to system default

/**
 * Returns earlier of two dates
 * @param a - First date (can be null/undefined)
 * @param b - Second date (can be null/undefined)
 * @returns Earlier date, or null/undefined if both are null/undefined
 */
function minDate<A, B>(a?: A | null, b?: B | null): A | B | null | undefined;

/**
 * Returns later of two dates
 * @param a - First date (can be null/undefined)
 * @param b - Second date (can be null/undefined)
 * @returns Later date, or null/undefined if both are null/undefined
 */
function maxDate<A, B>(a?: A | null, b?: B | null): A | B | null | undefined;

import { minDate, maxDate, CalendarDate } from "@internationalized/date";

const date1 = new CalendarDate(2024, 3, 15);
const date2 = new CalendarDate(2024, 6, 20);
const date3 = null;

// Find earlier/later dates
const earlier = minDate(date1, date2); // date1 (March 15)
const later = maxDate(date1, date2); // date2 (June 20)

// Handle null values
const earlierWithNull = minDate(date1, date3); // date1
const laterWithNull = maxDate(date3, date2); // date2
const bothNull = minDate(date3, null); // null