0
# Date and Time Classes
1

2
Core date and time classes providing comprehensive functionality for representing dates, times, and date-time combinations without timezone information. These classes form the foundation of the Temporal API.
3

4
## Capabilities
5

6
### PlainDate
7

8
Represents a calendar date without time or timezone information. Ideal for birthdays, holidays, or any date-only use cases.
9

10
```typescript { .api }
11
/**
12
 * Represents a calendar date without time or timezone
13
 */
14
class PlainDate {
15
  /** Creates a PlainDate from various inputs */
16
  static from(item: PlainDateLike | string, options?: AssignmentOptions): PlainDate;
17
  /** Compares two dates and returns -1, 0, or 1 */
18
  static compare(one: PlainDateLike, two: PlainDateLike): ComparisonResult;
19
  /** Constructs a new PlainDate */
20
  constructor(isoYear: number, isoMonth: number, isoDay: number, calendar?: CalendarLike);
21

22
  // Date component properties
23
  readonly calendarId: string;
24
  readonly year: number;
25
  readonly month: number;
26
  readonly monthCode: string;
27
  readonly day: number;
28
  readonly era: string | undefined;
29
  readonly eraYear: number | undefined;
30
  readonly dayOfWeek: number;
31
  readonly dayOfYear: number;
32
  readonly weekOfYear: number;
33
  readonly yearOfWeek: number;
34
  readonly daysInWeek: number;
35
  readonly daysInMonth: number;
36
  readonly daysInYear: number;
37
  readonly monthsInYear: number;
38
  readonly inLeapYear: boolean;
39

40
  // Date manipulation methods
41
  /** Returns a new PlainDate with the duration added */
42
  add(duration: DurationLike, options?: ArithmeticOptions): PlainDate;
43
  /** Returns a new PlainDate with the duration subtracted */
44
  subtract(duration: DurationLike, options?: ArithmeticOptions): PlainDate;
45
  /** Returns a new PlainDate with the specified fields changed */
46
  with(dateLike: PlainDateLike, options?: AssignmentOptions): PlainDate;
47
  /** Changes the calendar system of this date */
48
  withCalendar(calendar: CalendarLike): PlainDate;
49

50
  // Comparison and difference methods
51
  /** Returns the duration from this date until the other date */
52
  until(other: PlainDateLike, options?: DifferenceOptions<DateUnit>): Duration;
53
  /** Returns the duration from the other date since this date */
54
  since(other: PlainDateLike, options?: DifferenceOptions<DateUnit>): Duration;
55
  /** Tests if this date equals another date */
56
  equals(other: PlainDateLike): boolean;
57

58
  // Conversion methods
59
  /** Combines this date with a time to create a PlainDateTime */
60
  toPlainDateTime(plainTime?: PlainTimeLike): PlainDateTime;
61
  /** Converts this date to a ZonedDateTime in the specified timezone */
62
  toZonedDateTime(timeZone: TimeZoneLike | {timeZone: TimeZoneLike, plainTime?: PlainTimeLike}): ZonedDateTime;
63
  /** Extracts the year-month portion */
64
  toPlainYearMonth(): PlainYearMonth;
65
  /** Extracts the month-day portion */
66
  toPlainMonthDay(): PlainMonthDay;
67

68
  // String representation methods
69
  /** Returns a locale-formatted string representation */
70
  toLocaleString(locales?: string | string[], options?: Intl.DateTimeFormatOptions): string;
71
  /** Returns an ISO 8601 string representation */
72
  toString(options?: ShowCalendarOption): string;
73
  /** Returns a JSON representation (same as toString) */
74
  toJSON(): string;
75
  /** Throws a TypeError when used in comparison operators */
76
  valueOf(): never;
77
}
78
```
79

80
**Usage Examples:**
81

82
```typescript
83
import { Temporal } from "temporal-polyfill";
84

85
// Creating dates
86
const today = Temporal.Now.plainDateISO();
87
const birthday = new Temporal.PlainDate(1990, 6, 15);
88
const fromString = Temporal.PlainDate.from("2024-03-15");
89
const fromObject = Temporal.PlainDate.from({ year: 2024, month: 3, day: 15 });
90

91
// Date arithmetic
92
const nextWeek = today.add({ days: 7 });
93
const lastMonth = today.subtract({ months: 1 });
94

95
// Modifying dates
96
const sameYear = birthday.with({ year: 2024 });
97
const endOfMonth = today.with({ day: today.daysInMonth });
98

99
// Comparisons
100
const daysBetween = birthday.until(today).days;
101
const isAfter = Temporal.PlainDate.compare(today, birthday) > 0;
102

103
// Conversions
104
const dateTime = today.toPlainDateTime(Temporal.PlainTime.from("09:00"));
105
const yearMonth = today.toPlainYearMonth();
106
```
107

108
### PlainTime
109

110
Represents a wall-clock time without date or timezone information. Perfect for schedules, alarms, or any time-only use cases.
111

112
```typescript { .api }
113
/**
114
 * Represents a wall-clock time without date or timezone
115
 */
116
class PlainTime {
117
  /** Creates a PlainTime from various inputs */
118
  static from(item: PlainTimeLike | string, options?: AssignmentOptions): PlainTime;
119
  /** Compares two times and returns -1, 0, or 1 */
120
  static compare(one: PlainTimeLike, two: PlainTimeLike): ComparisonResult;
121
  /** Constructs a new PlainTime */
122
  constructor(hour?: number, minute?: number, second?: number, millisecond?: number, microsecond?: number, nanosecond?: number);
123

124
  // Time component properties
125
  readonly hour: number;
126
  readonly minute: number;
127
  readonly second: number;
128
  readonly millisecond: number;
129
  readonly microsecond: number;
130
  readonly nanosecond: number;
131

132
  // Time manipulation methods
133
  /** Returns a new PlainTime with the duration added */
134
  add(duration: DurationLike): PlainTime;
135
  /** Returns a new PlainTime with the duration subtracted */
136
  subtract(duration: DurationLike): PlainTime;
137
  /** Returns a new PlainTime with the specified fields changed */
138
  with(timeLike: PlainTimeLike, options?: AssignmentOptions): PlainTime;
139

140
  // Comparison and difference methods
141
  /** Returns the duration from this time until the other time */
142
  until(other: PlainTimeLike, options?: DifferenceOptions<TimeUnit>): Duration;
143
  /** Returns the duration from the other time since this time */
144
  since(other: PlainTimeLike, options?: DifferenceOptions<TimeUnit>): Duration;
145
  /** Rounds this time to the specified unit or precision */
146
  round(roundTo: TimeUnit | RoundingOptions<TimeUnit>): PlainTime;
147
  /** Tests if this time equals another time */
148
  equals(other: PlainTimeLike): boolean;
149

150
  // Conversion methods
151
  /** Combines this time with a date to create a PlainDateTime */
152
  toPlainDateTime(plainDate: PlainDateLike): PlainDateTime;
153
  /** Converts this time to a ZonedDateTime with the specified date and timezone */
154
  toZonedDateTime(options: {timeZone: TimeZoneLike, plainDate: PlainDateLike}): ZonedDateTime;
155

156
  // String representation methods
157
  /** Returns a locale-formatted string representation */
158
  toLocaleString(locales?: string | string[], options?: Intl.DateTimeFormatOptions): string;
159
  /** Returns an ISO 8601 string representation */
160
  toString(options?: ToStringPrecisionOptions): string;
161
  /** Returns a JSON representation (same as toString) */
162
  toJSON(): string;
163
  /** Throws a TypeError when used in comparison operators */
164
  valueOf(): never;
165
}
166
```
167

168
**Usage Examples:**
169

170
```typescript
171
import { Temporal } from "temporal-polyfill";
172

173
// Creating times
174
const now = Temporal.Now.plainTimeISO();
175
const meetingTime = new Temporal.PlainTime(14, 30, 0);
176
const fromString = Temporal.PlainTime.from("09:00:00");
177
const fromObject = Temporal.PlainTime.from({ hour: 9, minute: 0 });
178

179
// Time arithmetic
180
const laterTime = meetingTime.add({ hours: 1, minutes: 30 });
181
const earlierTime = meetingTime.subtract({ minutes: 15 });
182

183
// Modifying times
184
const topOfHour = meetingTime.with({ minute: 0, second: 0 });
185
const precise = meetingTime.with({ millisecond: 500 });
186

187
// Rounding
188
const rounded = now.round({ smallestUnit: "minute" });
189
const hourly = now.round("hour");
190

191
// Comparisons
192
const duration = meetingTime.until(laterTime);
193
const isLater = Temporal.PlainTime.compare(laterTime, meetingTime) > 0;
194

195
// Conversions
196
const today = Temporal.Now.plainDateISO();
197
const dateTime = meetingTime.toPlainDateTime(today);
198
```
199

200
### PlainDateTime
201

202
Represents a date and time without timezone information. Combines all functionality of PlainDate and PlainTime.
203

204
```typescript { .api }
205
/**
206
 * Represents a date and time without timezone information
207
 */
208
class PlainDateTime {
209
  /** Creates a PlainDateTime from various inputs */
210
  static from(item: PlainDateTimeLike | string, options?: AssignmentOptions): PlainDateTime;
211
  /** Compares two date-times and returns -1, 0, or 1 */
212
  static compare(one: PlainDateTimeLike, two: PlainDateTimeLike): ComparisonResult;
213
  /** Constructs a new PlainDateTime */
214
  constructor(isoYear: number, isoMonth: number, isoDay: number, hour?: number, minute?: number, second?: number, millisecond?: number, microsecond?: number, nanosecond?: number, calendar?: CalendarLike);
215

216
  // All PlainDate properties
217
  readonly calendarId: string;
218
  readonly year: number;
219
  readonly month: number;
220
  readonly monthCode: string;
221
  readonly day: number;
222
  readonly era: string | undefined;
223
  readonly eraYear: number | undefined;
224
  readonly dayOfWeek: number;
225
  readonly dayOfYear: number;
226
  readonly weekOfYear: number;
227
  readonly yearOfWeek: number;
228
  readonly daysInWeek: number;
229
  readonly daysInMonth: number;
230
  readonly daysInYear: number;
231
  readonly monthsInYear: number;
232
  readonly inLeapYear: boolean;
233

234
  // All PlainTime properties
235
  readonly hour: number;
236
  readonly minute: number;
237
  readonly second: number;
238
  readonly millisecond: number;
239
  readonly microsecond: number;
240
  readonly nanosecond: number;
241

242
  // DateTime manipulation methods
243
  /** Returns a new PlainDateTime with the duration added */
244
  add(duration: DurationLike, options?: ArithmeticOptions): PlainDateTime;
245
  /** Returns a new PlainDateTime with the duration subtracted */
246
  subtract(duration: DurationLike, options?: ArithmeticOptions): PlainDateTime;
247
  /** Returns a new PlainDateTime with the specified fields changed */
248
  with(dateTimeLike: PlainDateTimeLike, options?: AssignmentOptions): PlainDateTime;
249
  /** Changes the calendar system of this date-time */
250
  withCalendar(calendar: CalendarLike): PlainDateTime;
251
  /** Changes the time portion of this date-time */
252
  withPlainTime(plainTime?: PlainTimeLike): PlainDateTime;
253

254
  // Comparison and difference methods
255
  /** Returns the duration from this date-time until the other date-time */
256
  until(other: PlainDateTimeLike, options?: DifferenceOptions<DateTimeUnit>): Duration;
257
  /** Returns the duration from the other date-time since this date-time */
258
  since(other: PlainDateTimeLike, options?: DifferenceOptions<DateTimeUnit>): Duration;
259
  /** Rounds this date-time to the specified unit or precision */
260
  round(roundTo: DateTimeUnit | RoundingOptions<DateTimeUnit>): PlainDateTime;
261
  /** Tests if this date-time equals another date-time */
262
  equals(other: PlainDateTimeLike): boolean;
263

264
  // Conversion methods
265
  /** Converts this date-time to a ZonedDateTime in the specified timezone */
266
  toZonedDateTime(options: TimeZoneLike | {timeZone: TimeZoneLike, disambiguation?: DisambiguationMode}): ZonedDateTime;
267
  /** Extracts the date portion */
268
  toPlainDate(): PlainDate;
269
  /** Extracts the time portion */
270
  toPlainTime(): PlainTime;
271
  /** Extracts the year-month portion */
272
  toPlainYearMonth(): PlainYearMonth;
273
  /** Extracts the month-day portion */
274
  toPlainMonthDay(): PlainMonthDay;
275

276
  // String representation methods
277
  /** Returns a locale-formatted string representation */
278
  toLocaleString(locales?: string | string[], options?: Intl.DateTimeFormatOptions): string;
279
  /** Returns an ISO 8601 string representation */
280
  toString(options?: CalendarDisplayOptions & ToStringPrecisionOptions): string;
281
  /** Returns a JSON representation (same as toString) */
282
  toJSON(): string;
283
  /** Throws a TypeError when used in comparison operators */
284
  valueOf(): never;
285
}
286
```
287

288
**Usage Examples:**
289

290
```typescript
291
import { Temporal } from "temporal-polyfill";
292

293
// Creating date-times
294
const now = Temporal.Now.plainDateTimeISO();
295
const meeting = new Temporal.PlainDateTime(2024, 3, 15, 14, 30, 0);
296
const fromString = Temporal.PlainDateTime.from("2024-03-15T14:30:00");
297
const combined = Temporal.PlainDate.from("2024-03-15").toPlainDateTime("14:30:00");
298

299
// DateTime arithmetic
300
const nextWeek = meeting.add({ weeks: 1 });
301
const twoHoursEarlier = meeting.subtract({ hours: 2 });
302

303
// Modifying date-times
304
const sameTimeTomorrow = meeting.add({ days: 1 });
305
const topOfHour = meeting.with({ minute: 0, second: 0 });
306
const newTime = meeting.withPlainTime({ hour: 16, minute: 0 });
307

308
// Rounding
309
const roundedToHour = meeting.round("hour");
310
const roundedToMinute = meeting.round({ smallestUnit: "minute" });
311

312
// Comparisons
313
const duration = meeting.until(nextWeek);
314
const hoursUntil = meeting.until(nextWeek, { largestUnit: "hour" }).hours;
315

316
// Conversions
317
const inNewYork = meeting.toZonedDateTime("America/New_York");
318
const justDate = meeting.toPlainDate();
319
const justTime = meeting.toPlainTime();
320
```
321

322
## Types
323

324
```typescript { .api }
325
// Core type definitions for date and time classes
326
type PlainDateLike = PlainDate | PlainDateFields;
327
type PlainTimeLike = PlainTime | PlainTimeFields;
328
type PlainDateTimeLike = PlainDateTime | PlainDateTimeFields;
329
type CalendarLike = string | Calendar;
330

331
interface PlainDateFields {
332
  era?: string;
333
  eraYear?: number;
334
  year: number;
335
  month?: number;
336
  monthCode?: string;
337
  day: number;
338
  calendar?: CalendarLike;
339
}
340

341
interface PlainTimeFields {
342
  hour?: number;
343
  minute?: number;
344
  second?: number;
345
  millisecond?: number;
346
  microsecond?: number;
347
  nanosecond?: number;
348
}
349

350
interface PlainDateTimeFields extends PlainDateFields, PlainTimeFields {}
351

352
// Unit types for date and time operations
353
type DateUnit = 'year' | 'month' | 'week' | 'day';
354
type TimeUnit = 'hour' | 'minute' | 'second' | 'millisecond' | 'microsecond' | 'nanosecond';
355
type DateTimeUnit = DateUnit | TimeUnit;
356

357
// Display and precision options
358
interface ShowCalendarOption {
359
  calendarName?: 'auto' | 'always' | 'never' | 'critical';
360
}
361

362
interface ToStringPrecisionOptions {
363
  fractionalSecondDigits?: 'auto' | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
364
  smallestUnit?: TimeUnit;
365
  roundingMode?: RoundingMode;
366
}
367

368
interface CalendarDisplayOptions {
369
  calendarName?: 'auto' | 'always' | 'never' | 'critical';
370
}
371
```