0
# Internationalized Date
1

2
The @internationalized/date library provides comprehensive, locale-aware date and time manipulation utilities with support for 13 international calendar systems. It offers immutable typed objects for dates, times, and date-time combinations with timezone support, designed for maximum reusability across internationalized applications requiring robust date handling.
3

4
## Package Information
5

6
- **Package Name**: @internationalized/date
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @internationalized/date`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  CalendarDate, 
16
  CalendarDateTime, 
17
  Time, 
18
  ZonedDateTime,
19
  DateFormatter,
20
  createCalendar,
21
  parseDate,
22
  parseDateTime,
23
  parseZonedDateTime,
24
  now,
25
  today,
26
  startOfMonth,
27
  isWeekend
28
} from "@internationalized/date";
29
```
30

31
For CommonJS:
32

33
```javascript
34
const { 
35
  CalendarDate, 
36
  CalendarDateTime, 
37
  Time, 
38
  ZonedDateTime,
39
  DateFormatter,
40
  createCalendar,
41
  parseDate,
42
  parseDateTime,
43
  parseZonedDateTime,
44
  now,
45
  today,
46
  startOfMonth,
47
  isWeekend
48
} = require("@internationalized/date");
49
```
50

51
## Basic Usage
52

53
```typescript
54
import { 
55
  CalendarDate, 
56
  ZonedDateTime, 
57
  now, 
58
  parseDate,
59
  parseDateTime,
60
  createCalendar,
61
  GregorianCalendar,
62
  startOfMonth,
63
  isWeekend
64
} from "@internationalized/date";
65

66
// Create dates in different calendar systems
67
const date = new CalendarDate(2024, 3, 15);
68
const persianDate = new CalendarDate(createCalendar('persian'), 1403, 1, 26);
69

70
// Work with timezone-aware dates
71
const zonedNow = now('America/New_York');
72
const zonedDate = new ZonedDateTime(2024, 3, 15, 'UTC', 0, 14, 30);
73

74
// Parse ISO strings
75
const parsedDate = parseDate('2024-03-15');
76
const parsedDateTime = parseDateTime('2024-03-15T14:30:00');
77

78
// Date arithmetic and manipulation
79
const nextWeek = date.add({ weeks: 1 });
80
const startOfMonth = startOfMonth(date);
81
const isWeekendDay = isWeekend(date, 'en-US');
82
```
83

84
## Architecture
85

86
The @internationalized/date library is built around several key components:
87

88
- **Date/Time Objects**: Four immutable classes (`CalendarDate`, `CalendarDateTime`, `Time`, `ZonedDateTime`) representing different temporal concepts
89
- **Calendar Systems**: 13 international calendar implementations with consistent APIs
90
- **Conversion System**: Functions for transforming between date types, calendar systems, and timezones
91
- **Query Functions**: Utilities for comparing dates, getting date ranges, and locale-aware operations
92
- **Parsing System**: ISO 8601 string parsing with support for dates, times, durations, and zoned datetimes
93
- **Formatting**: Internationalized date formatting with browser compatibility fixes
94

95
## Capabilities
96

97
### Date and Time Objects
98

99
Core immutable date and time classes for representing temporal values in different calendar systems, with or without timezone information.
100

101
```typescript { .api }
102
class CalendarDate {
103
  constructor(year: number, month: number, day: number);
104
  constructor(era: string, year: number, month: number, day: number);
105
  constructor(calendar: Calendar, year: number, month: number, day: number);
106
  constructor(calendar: Calendar, era: string, year: number, month: number, day: number);
107
  
108
  readonly calendar: Calendar;
109
  readonly era: string;
110
  readonly year: number;
111
  readonly month: number;
112
  readonly day: number;
113
}
114

115
class ZonedDateTime {
116
  constructor(year: number, month: number, day: number, timeZone: string, offset: number, hour?: number, minute?: number, second?: number, millisecond?: number);
117
  constructor(era: string, year: number, month: number, day: number, timeZone: string, offset: number, hour?: number, minute?: number, second?: number, millisecond?: number);
118
  constructor(calendar: Calendar, year: number, month: number, day: number, timeZone: string, offset: number, hour?: number, minute?: number, second?: number, millisecond?: number);
119
  constructor(calendar: Calendar, era: string, year: number, month: number, day: number, timeZone: string, offset: number, hour?: number, minute?: number, second?: number, millisecond?: number);
120
  
121
  readonly calendar: Calendar;
122
  readonly era: string;
123
  readonly year: number;
124
  readonly month: number;
125
  readonly day: number;
126
  readonly hour: number;
127
  readonly minute: number;
128
  readonly second: number;
129
  readonly millisecond: number;
130
  readonly timeZone: string;
131
  readonly offset: number;
132
}
133
```
134

135
[Date and Time Objects](./date-time-objects.md)
136

137
### Calendar Systems
138

139
Support for 13 international calendar systems including Gregorian, Buddhist, Islamic, Hebrew, Persian, and others with factory creation.
140

141
```typescript { .api }
142
function createCalendar(identifier: CalendarIdentifier): Calendar;
143

144
type CalendarIdentifier = 'gregory' | 'buddhist' | 'chinese' | 'coptic' | 'dangi' | 
145
  'ethioaa' | 'ethiopic' | 'hebrew' | 'indian' | 'islamic' | 'islamic-umalqura' | 
146
  'islamic-tbla' | 'islamic-civil' | 'islamic-rgsa' | 'iso8601' | 'japanese' | 'persian' | 'roc';
147
```
148

149
[Calendar Systems](./calendar-systems.md)
150

151
### Date Conversion and Transformation
152

153
Functions for converting between date types, calendar systems, and timezones with proper handling of ambiguous time situations.
154

155
```typescript { .api }
156
function toCalendar<T extends AnyCalendarDate>(date: T, calendar: Calendar): T;
157
function toZoned(date: CalendarDate | CalendarDateTime | ZonedDateTime, timeZone: string, disambiguation?: Disambiguation): ZonedDateTime;
158
function fromDate(date: Date, timeZone: string): ZonedDateTime;
159
function fromAbsolute(ms: number, timeZone: string): ZonedDateTime;
160

161
type Disambiguation = 'compatible' | 'earlier' | 'later' | 'reject';
162
```
163

164
[Date Conversion](./date-conversion.md)
165

166
### Date Queries and Comparisons
167

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

170
```typescript { .api }
171
function isSameDay(a: DateValue, b: DateValue): boolean;
172
function isWeekend(date: DateValue, locale: string): boolean;
173
function now(timeZone: string): ZonedDateTime;
174
function today(timeZone: string): CalendarDate;
175
function startOfMonth<T extends DateValue>(date: T): T;
176
function endOfWeek(date: DateValue, locale: string, firstDayOfWeek?: DayOfWeek): DateValue;
177
```
178

179
[Date Queries](./date-queries.md)
180

181
### String Parsing
182

183
ISO 8601 string parsing for dates, times, durations, and timezone-aware datetimes with comprehensive format support.
184

185
```typescript { .api }
186
function parseDate(value: string): CalendarDate;
187
function parseDateTime(value: string): CalendarDateTime;
188
function parseZonedDateTime(value: string, disambiguation?: Disambiguation): ZonedDateTime;
189
function parseDuration(value: string): Required<DateTimeDuration>;
190
```
191

192
[String Parsing](./string-parsing.md)
193

194
### Date Formatting
195

196
Internationalized date formatting with cross-browser compatibility and comprehensive format options.
197

198
```typescript { .api }
199
class DateFormatter {
200
  constructor(locale: string, options?: Intl.DateTimeFormatOptions);
201
  format(date: Date): string;
202
  formatToParts(date: Date): Intl.DateTimeFormatPart[];
203
  formatRange(start: Date, end: Date): string;
204
}
205
```
206

207
[Date Formatting](./date-formatting.md)
208

209
## Types
210

211
```typescript { .api }
212
interface AnyCalendarDate {
213
  readonly calendar: Calendar;
214
  readonly era: string;
215
  readonly year: number;
216
  readonly month: number;
217
  readonly day: number;
218
  copy(): this;
219
}
220

221
interface AnyTime {
222
  readonly hour: number;
223
  readonly minute: number;
224
  readonly second: number;
225
  readonly millisecond: number;
226
  copy(): this;
227
}
228

229
interface AnyDateTime extends AnyCalendarDate, AnyTime {}
230

231
interface DateDuration {
232
  years?: number;
233
  months?: number;
234
  weeks?: number;
235
  days?: number;
236
}
237

238
interface TimeDuration {
239
  hours?: number;
240
  minutes?: number;
241
  seconds?: number;
242
  milliseconds?: number;
243
}
244

245
interface DateTimeDuration extends DateDuration, TimeDuration {}
246

247
interface Calendar {
248
  identifier: CalendarIdentifier;
249
  fromJulianDay(jd: number): CalendarDate;
250
  toJulianDay(date: AnyCalendarDate): number;
251
  getDaysInMonth(date: AnyCalendarDate): number;
252
  getMonthsInYear(date: AnyCalendarDate): number;
253
  getYearsInEra(date: AnyCalendarDate): number;
254
  getEras(): string[];
255
}
256
```