0
# Date Queries
1

2
Comprehensive set of functions for comparing dates, getting date ranges, and performing locale-aware date operations.
3

4
## Capabilities
5

6
### Date Comparison Functions
7

8
Compare dates across different calendar systems and check for equality.
9

10
```typescript { .api }
11
/**
12
 * Checks if dates occur on same day (cross-calendar)
13
 * @param a - First date to compare
14
 * @param b - Second date to compare  
15
 * @returns true if dates represent the same day
16
 */
17
function isSameDay(a: DateValue, b: DateValue): boolean;
18

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

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

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

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

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

59
/**
60
 * Checks if two calendars are the same
61
 * @param a - First calendar to compare
62
 * @param b - Second calendar to compare
63
 * @returns true if calendars are identical
64
 */
65
function isEqualCalendar(a: Calendar, b: Calendar): boolean;
66

67
type DateValue = CalendarDate | CalendarDateTime | ZonedDateTime;
68
```
69

70
**Usage Examples:**
71

72
```typescript
73
import { 
74
  isSameDay, 
75
  isSameMonth, 
76
  isEqualDay,
77
  CalendarDate,
78
  createCalendar 
79
} from "@internationalized/date";
80

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

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

89
// Same calendar comparison
90
const sameGregorianDay = isEqualDay(gregorianDate, differentDay); // false
91
const sameMonth = isSameMonth(gregorianDate, differentDay); // true
92
```
93

94
### Current Time Functions
95

96
Get current date and time information in specific timezones.
97

98
```typescript { .api }
99
/**
100
 * Returns current time in timezone
101
 * @param timeZone - IANA timezone identifier
102
 * @returns ZonedDateTime representing current moment in timezone
103
 */
104
function now(timeZone: string): ZonedDateTime;
105

106
/**
107
 * Returns today's date in timezone
108
 * @param timeZone - IANA timezone identifier  
109
 * @returns CalendarDate representing today in timezone
110
 */
111
function today(timeZone: string): CalendarDate;
112

113
/**
114
 * Checks if date is today in given timezone
115
 * @param date - Date to check
116
 * @param timeZone - IANA timezone identifier
117
 * @returns true if date represents today
118
 */
119
function isToday(date: DateValue, timeZone: string): boolean;
120
```
121

122
**Usage Examples:**
123

124
```typescript
125
import { now, today, isToday, CalendarDate } from "@internationalized/date";
126

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

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

136
// Check if a date is today
137
const someDate = new CalendarDate(2024, 3, 15);
138
const isTodayCheck = isToday(someDate, 'UTC');
139
```
140

141
### Locale-Aware Date Functions
142

143
Functions that consider locale-specific conventions for weekends, weekdays, and week structure.
144

145
```typescript { .api }
146
/**
147
 * Gets day of week number for locale
148
 * @param date - Date to get day of week for
149
 * @param locale - Locale identifier (e.g., 'en-US', 'de-DE')
150
 * @param firstDayOfWeek - Optional first day of week override
151
 * @returns Day of week number (0-6)
152
 */
153
function getDayOfWeek(date: DateValue, locale: string, firstDayOfWeek?: DayOfWeek): number;
154

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

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

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

174
**Usage Examples:**
175

176
```typescript
177
import { 
178
  getDayOfWeek, 
179
  isWeekend, 
180
  isWeekday,
181
  CalendarDate 
182
} from "@internationalized/date";
183

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

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

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

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

198
### Date Range Functions
199

200
Get start and end dates for various time periods.
201

202
```typescript { .api }
203
/**
204
 * Returns first date of the month
205
 */
206
function startOfMonth<T extends DateValue>(date: T): T;
207

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

217
/**
218
 * Returns first date of the year
219
 */
220
function startOfYear<T extends DateValue>(date: T): T;
221

222
/**
223
 * Returns last date of the month
224
 */
225
function endOfMonth<T extends DateValue>(date: T): T;
226

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

236
/**
237
 * Returns last date of the year
238
 */
239
function endOfYear<T extends DateValue>(date: T): T;
240
```
241

242
**Usage Examples:**
243

244
```typescript
245
import { 
246
  startOfMonth, 
247
  endOfMonth,
248
  startOfWeek,
249
  endOfWeek,
250
  startOfYear,
251
  endOfYear,
252
  CalendarDate 
253
} from "@internationalized/date";
254

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

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

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

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

268
// Year boundaries
269
const yearStart = startOfYear(date); // January 1, 2024
270
const yearEnd = endOfYear(date); // December 31, 2024
271
```
272

273
### Calendar-Specific Query Functions
274

275
Functions for handling calendar-specific variations and constraints.
276

277
```typescript { .api }
278
/**
279
 * Gets minimum month number in year (calendar-specific)
280
 * @param date - Date to get minimum month for
281
 * @returns Minimum month number (usually 1, but varies in some calendars)
282
 */
283
function getMinimumMonthInYear(date: AnyCalendarDate): number;
284

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

292
/**
293
 * Gets number of weeks in month
294
 * @param date - Date in the month to analyze
295
 * @param locale - Locale identifier for week conventions
296
 * @param firstDayOfWeek - Optional first day of week override
297
 * @returns Number of weeks in the month (4-6)
298
 */
299
function getWeeksInMonth(date: DateValue, locale: string, firstDayOfWeek?: DayOfWeek): number;
300
```
301

302
**Usage Examples:**
303

304
```typescript
305
import { 
306
  getMinimumMonthInYear,
307
  getMinimumDayInMonth,
308
  getWeeksInMonth,
309
  CalendarDate,
310
  createCalendar 
311
} from "@internationalized/date";
312

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

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

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

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

328
### Timezone and Time Functions
329

330
Functions for working with timezones and time-specific operations.
331

332
```typescript { .api }
333
/**
334
 * Gets hours in day (accounts for DST)
335
 * @param date - Date to check
336
 * @param timeZone - IANA timezone identifier
337
 * @returns Number of hours in the day (23, 24, or 25 depending on DST)
338
 */
339
function getHoursInDay(date: CalendarDate, timeZone: string): number;
340

341
/**
342
 * Gets user's local timezone identifier
343
 * @returns IANA timezone identifier for user's location
344
 */
345
function getLocalTimeZone(): string;
346

347
/**
348
 * Sets local timezone identifier
349
 * @param timeZone - IANA timezone identifier to set as local
350
 */
351
function setLocalTimeZone(timeZone: string): void;
352

353
/**
354
 * Resets local timezone to system default
355
 */
356
function resetLocalTimeZone(): void;
357
```
358

359
**Usage Examples:**
360

361
```typescript
362
import { 
363
  getHoursInDay,
364
  getLocalTimeZone,
365
  setLocalTimeZone,
366
  resetLocalTimeZone,
367
  CalendarDate 
368
} from "@internationalized/date";
369

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

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

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

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

385
resetLocalTimeZone();
386
const resetLocal = getLocalTimeZone(); // Back to system default
387
```
388

389
### Utility Functions
390

391
Utility functions for date comparisons and selections.
392

393
```typescript { .api }
394
/**
395
 * Returns earlier of two dates
396
 * @param a - First date (can be null/undefined)
397
 * @param b - Second date (can be null/undefined)
398
 * @returns Earlier date, or null/undefined if both are null/undefined
399
 */
400
function minDate<A, B>(a?: A | null, b?: B | null): A | B | null | undefined;
401

402
/**
403
 * Returns later of two dates
404
 * @param a - First date (can be null/undefined)
405
 * @param b - Second date (can be null/undefined)
406
 * @returns Later date, or null/undefined if both are null/undefined
407
 */
408
function maxDate<A, B>(a?: A | null, b?: B | null): A | B | null | undefined;
409
```
410

411
**Usage Examples:**
412

413
```typescript
414
import { minDate, maxDate, CalendarDate } from "@internationalized/date";
415

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

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

424
// Handle null values
425
const earlierWithNull = minDate(date1, date3); // date1
426
const laterWithNull = maxDate(date3, date2); // date2
427
const bothNull = minDate(date3, null); // null
428
```