0
# Temporal Polyfill
1
2
Temporal Polyfill provides a lightweight polyfill implementation of the Temporal API, which is the successor to JavaScript's Date object. The polyfill is designed to be highly optimized with only 20 KB minified+gzipped size, making it significantly smaller than alternative implementations while maintaining near-perfect spec compliance with just 4 intentional deviations.
3
4
## Package Information
5
6
- **Package Name**: temporal-polyfill
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install temporal-polyfill`
10
11
## Core Imports
12
13
Standard import for ES modules:
14
```typescript
15
import { Temporal, Intl } from "temporal-polyfill";
16
```
17
18
Implementation-only import:
19
```typescript
20
import { Temporal, Intl, toTemporalInstant } from "temporal-polyfill/impl";
21
```
22
23
Global polyfill (adds to globalThis):
24
```typescript
25
import "temporal-polyfill/global";
26
// Now Temporal and enhanced Intl are available globally
27
```
28
29
For CommonJS:
30
```javascript
31
const { Temporal, Intl } = require("temporal-polyfill");
32
```
33
34
## Basic Usage
35
36
```typescript
37
import { Temporal } from "temporal-polyfill";
38
39
// Current time
40
const now = Temporal.Now.instant();
41
const today = Temporal.Now.plainDateISO();
42
43
// Create specific dates and times
44
const date = Temporal.PlainDate.from("2024-03-15");
45
const time = Temporal.PlainTime.from("14:30:00");
46
const dateTime = Temporal.PlainDateTime.from("2024-03-15T14:30:00");
47
48
// With timezone
49
const zonedDateTime = Temporal.ZonedDateTime.from("2024-03-15T14:30:00[America/New_York]");
50
51
// Durations
52
const duration = Temporal.Duration.from({ hours: 2, minutes: 30 });
53
const futureDate = date.add(duration);
54
55
// Formatting with enhanced Intl
56
const formatter = new Intl.DateTimeFormat("en-US", {
57
weekday: "long",
58
year: "numeric",
59
month: "long",
60
day: "numeric"
61
});
62
console.log(formatter.format(date));
63
```
64
65
## Architecture
66
67
Temporal Polyfill is organized around several key components:
68
69
- **Core Classes**: 8 main Temporal classes for representing dates, times, and durations
70
- **Temporal Namespace**: Main entry point containing all Temporal classes and utilities
71
- **Now Utilities**: Functions for getting current time values in various formats
72
- **Enhanced Intl**: Extended DateTimeFormat class supporting Temporal types
73
- **Global Extensions**: Polyfills for global objects like Date.prototype.toTemporalInstant
74
- **Type System**: Complete TypeScript definitions with generic type preservation
75
76
## Capabilities
77
78
### Date and Time Classes
79
80
Core classes for representing dates, times, and moments with comprehensive functionality for manipulation and formatting.
81
82
```typescript { .api }
83
// Basic date/time classes
84
class PlainDate {
85
static from(item: PlainDateLike | string, options?: AssignmentOptions): PlainDate;
86
static compare(one: PlainDateLike, two: PlainDateLike): ComparisonResult;
87
constructor(isoYear: number, isoMonth: number, isoDay: number, calendar?: CalendarLike);
88
readonly year: number;
89
readonly month: number;
90
readonly day: number;
91
add(duration: DurationLike, options?: ArithmeticOptions): PlainDate;
92
subtract(duration: DurationLike, options?: ArithmeticOptions): PlainDate;
93
with(dateLike: PlainDateLike, options?: AssignmentOptions): PlainDate;
94
until(other: PlainDateLike, options?: DifferenceOptions<DateUnit>): Duration;
95
since(other: PlainDateLike, options?: DifferenceOptions<DateUnit>): Duration;
96
equals(other: PlainDateLike): boolean;
97
toString(options?: ShowCalendarOption): string;
98
}
99
100
class PlainTime {
101
static from(item: PlainTimeLike | string, options?: AssignmentOptions): PlainTime;
102
static compare(one: PlainTimeLike, two: PlainTimeLike): ComparisonResult;
103
constructor(hour?: number, minute?: number, second?: number, millisecond?: number, microsecond?: number, nanosecond?: number);
104
readonly hour: number;
105
readonly minute: number;
106
readonly second: number;
107
readonly millisecond: number;
108
readonly microsecond: number;
109
readonly nanosecond: number;
110
add(duration: DurationLike): PlainTime;
111
subtract(duration: DurationLike): PlainTime;
112
with(timeLike: PlainTimeLike, options?: AssignmentOptions): PlainTime;
113
until(other: PlainTimeLike, options?: DifferenceOptions<TimeUnit>): Duration;
114
since(other: PlainTimeLike, options?: DifferenceOptions<TimeUnit>): Duration;
115
round(roundTo: TimeUnit | RoundingOptions<TimeUnit>): PlainTime;
116
equals(other: PlainTimeLike): boolean;
117
toString(options?: ToStringPrecisionOptions): string;
118
}
119
120
class PlainDateTime {
121
static from(item: PlainDateTimeLike | string, options?: AssignmentOptions): PlainDateTime;
122
static compare(one: PlainDateTimeLike, two: PlainDateTimeLike): ComparisonResult;
123
constructor(isoYear: number, isoMonth: number, isoDay: number, hour?: number, minute?: number, second?: number, millisecond?: number, microsecond?: number, nanosecond?: number, calendar?: CalendarLike);
124
// All PlainDate and PlainTime properties
125
readonly year: number;
126
readonly month: number;
127
readonly day: number;
128
readonly hour: number;
129
readonly minute: number;
130
readonly second: number;
131
readonly millisecond: number;
132
readonly microsecond: number;
133
readonly nanosecond: number;
134
add(duration: DurationLike, options?: ArithmeticOptions): PlainDateTime;
135
subtract(duration: DurationLike, options?: ArithmeticOptions): PlainDateTime;
136
with(dateTimeLike: PlainDateTimeLike, options?: AssignmentOptions): PlainDateTime;
137
withPlainTime(plainTime?: PlainTimeLike): PlainDateTime;
138
round(roundTo: DateTimeUnit | RoundingOptions<DateTimeUnit>): PlainDateTime;
139
equals(other: PlainDateTimeLike): boolean;
140
toString(options?: CalendarDisplayOptions & ToStringPrecisionOptions): string;
141
}
142
```
143
144
[Date and Time Classes](./date-time-classes.md)
145
146
### Instant and Zoned Date-Time
147
148
Classes for representing exact moments in time and timezone-aware date-times with full timezone support.
149
150
```typescript { .api }
151
class Instant {
152
static from(item: InstantLike | string): Instant;
153
static fromEpochMilliseconds(epochMilliseconds: number): Instant;
154
static fromEpochNanoseconds(epochNanoseconds: bigint): Instant;
155
static compare(one: InstantLike, two: InstantLike): ComparisonResult;
156
readonly epochMilliseconds: number;
157
readonly epochNanoseconds: bigint;
158
add(duration: DurationLike): Instant;
159
subtract(duration: DurationLike): Instant;
160
until(other: InstantLike, options?: DifferenceOptions<TimeUnit>): Duration;
161
since(other: InstantLike, options?: DifferenceOptions<TimeUnit>): Duration;
162
round(roundTo: TimeUnit | RoundingOptions<TimeUnit>): Instant;
163
equals(other: InstantLike): boolean;
164
toZonedDateTimeISO(timeZone: TimeZoneLike): ZonedDateTime;
165
toString(options?: InstantToStringOptions): string;
166
}
167
168
class ZonedDateTime {
169
static from(item: ZonedDateTimeLike | string, options?: ZonedDateTimeAssignmentOptions): ZonedDateTime;
170
static compare(one: ZonedDateTimeLike, two: ZonedDateTimeLike): ComparisonResult;
171
// All PlainDateTime properties plus timezone-specific ones
172
readonly timeZoneId: string;
173
readonly offset: string;
174
readonly offsetNanoseconds: number;
175
readonly epochSeconds: number;
176
readonly epochMilliseconds: number;
177
readonly epochMicroseconds: bigint;
178
readonly epochNanoseconds: bigint;
179
readonly hoursInDay: number;
180
readonly startOfDay: ZonedDateTime;
181
add(duration: DurationLike, options?: ArithmeticOptions): ZonedDateTime;
182
subtract(duration: DurationLike, options?: ArithmeticOptions): ZonedDateTime;
183
with(zonedDateTimeLike: ZonedDateTimeLike, options?: ZonedDateTimeAssignmentOptions): ZonedDateTime;
184
withTimeZone(timeZone: TimeZoneLike): ZonedDateTime;
185
round(roundTo: DateTimeUnit | RoundingOptions<DateTimeUnit>): ZonedDateTime;
186
equals(other: ZonedDateTimeLike): boolean;
187
toInstant(): Instant;
188
toString(options?: ZonedDateTimeToStringOptions): string;
189
}
190
```
191
192
[Instant and Zoned Date-Time](./instant-zoned-datetime.md)
193
194
### Duration and Arithmetic
195
196
Duration class for representing time spans and performing date arithmetic operations.
197
198
```typescript { .api }
199
class Duration {
200
static from(item: DurationLike | string): Duration;
201
static compare(one: DurationLike, two: DurationLike, options?: DurationArithmeticOptions): ComparisonResult;
202
constructor(years?: number, months?: number, weeks?: number, days?: number, hours?: number, minutes?: number, seconds?: number, milliseconds?: number, microseconds?: number, nanoseconds?: number);
203
readonly years: number;
204
readonly months: number;
205
readonly weeks: number;
206
readonly days: number;
207
readonly hours: number;
208
readonly minutes: number;
209
readonly seconds: number;
210
readonly milliseconds: number;
211
readonly microseconds: number;
212
readonly nanoseconds: number;
213
readonly sign: -1 | 0 | 1;
214
readonly blank: boolean;
215
with(durationLike: DurationLike): Duration;
216
negated(): Duration;
217
abs(): Duration;
218
add(other: DurationLike, options?: DurationArithmeticOptions): Duration;
219
subtract(other: DurationLike, options?: DurationArithmeticOptions): Duration;
220
round(roundTo: DurationUnit | DurationRoundingOptions): Duration;
221
total(totalOf: DurationUnit | DurationTotalOfOptions): number;
222
toString(options?: DurationToStringOptions): string;
223
}
224
```
225
226
[Duration and Arithmetic](./duration-arithmetic.md)
227
228
### Calendar System
229
230
Specialized classes for working with calendar-specific date components like year-month and month-day combinations.
231
232
```typescript { .api }
233
class PlainYearMonth {
234
static from(item: PlainYearMonthLike | string, options?: AssignmentOptions): PlainYearMonth;
235
static compare(one: PlainYearMonthLike, two: PlainYearMonthLike): ComparisonResult;
236
readonly year: number;
237
readonly month: number;
238
readonly monthCode: string;
239
readonly daysInMonth: number;
240
readonly daysInYear: number;
241
readonly monthsInYear: number;
242
readonly inLeapYear: boolean;
243
add(duration: DurationLike, options?: ArithmeticOptions): PlainYearMonth;
244
subtract(duration: DurationLike, options?: ArithmeticOptions): PlainYearMonth;
245
with(yearMonthLike: PlainYearMonthLike, options?: AssignmentOptions): PlainYearMonth;
246
until(other: PlainYearMonthLike, options?: DifferenceOptions<YearMonthUnit>): Duration;
247
since(other: PlainYearMonthLike, options?: DifferenceOptions<YearMonthUnit>): Duration;
248
equals(other: PlainYearMonthLike): boolean;
249
toPlainDate(day: PlainDateLike): PlainDate;
250
toString(options?: ShowCalendarOption): string;
251
}
252
253
class PlainMonthDay {
254
static from(item: PlainMonthDayLike | string, options?: AssignmentOptions): PlainMonthDay;
255
readonly monthCode: string;
256
readonly day: number;
257
with(monthDayLike: PlainMonthDayLike, options?: AssignmentOptions): PlainMonthDay;
258
equals(other: PlainMonthDayLike): boolean;
259
toPlainDate(year: PlainYearMonthLike): PlainDate;
260
toString(options?: ShowCalendarOption): string;
261
}
262
```
263
264
[Calendar System](./calendar-system.md)
265
266
### Current Time Utilities
267
268
Utilities for getting current time values in various Temporal formats and time zones.
269
270
```typescript { .api }
271
namespace Now {
272
function timeZoneId(): string;
273
function instant(): Instant;
274
function plainDateTimeISO(timeZone?: TimeZoneLike): PlainDateTime;
275
function zonedDateTimeISO(timeZone?: TimeZoneLike): ZonedDateTime;
276
function plainDateISO(timeZone?: TimeZoneLike): PlainDate;
277
function plainTimeISO(timeZone?: TimeZoneLike): PlainTime;
278
}
279
```
280
281
[Current Time Utilities](./current-time.md)
282
283
### International Formatting
284
285
Enhanced Intl.DateTimeFormat with native Temporal type support for formatting dates and times.
286
287
```typescript { .api }
288
class DateTimeFormat extends Intl.DateTimeFormat {
289
constructor(locales?: LocalesArgument, options?: Intl.DateTimeFormatOptions);
290
format(date: TemporalObject | Date): string;
291
formatToParts(date: TemporalObject | Date): Intl.DateTimeFormatPart[];
292
formatRange(startDate: TemporalObject, endDate: TemporalObject): string;
293
formatRangeToParts(startDate: TemporalObject, endDate: TemporalObject): Intl.DateTimeFormatPart[];
294
}
295
296
interface TemporalObject {
297
// Union of all formattable Temporal types
298
}
299
```
300
301
[International Formatting](./intl-formatting.md)
302
303
## Types
304
305
```typescript { .api }
306
// Core argument types
307
type PlainDateLike = PlainDate | PlainDateISOFields;
308
type PlainTimeLike = PlainTime | PlainTimeISOFields;
309
type PlainDateTimeLike = PlainDateTime | PlainDateTimeISOFields;
310
type ZonedDateTimeLike = ZonedDateTime | ZonedDateTimeISOFields | string;
311
type DurationLike = Duration | DurationFields | string;
312
type InstantLike = Instant | string;
313
type CalendarLike = string | Calendar;
314
type TimeZoneLike = string | TimeZone;
315
316
// Field interfaces
317
interface PlainDateISOFields {
318
era?: string;
319
eraYear?: number;
320
year: number;
321
month: number;
322
monthCode?: string;
323
day: number;
324
calendar?: CalendarLike;
325
}
326
327
interface PlainTimeISOFields {
328
hour?: number;
329
minute?: number;
330
second?: number;
331
millisecond?: number;
332
microsecond?: number;
333
nanosecond?: number;
334
}
335
336
interface PlainDateTimeISOFields extends PlainDateISOFields, PlainTimeISOFields {}
337
338
interface ZonedDateTimeISOFields extends PlainDateTimeISOFields {
339
timeZone: TimeZoneLike;
340
offset?: string;
341
}
342
343
interface DurationFields {
344
years?: number;
345
months?: number;
346
weeks?: number;
347
days?: number;
348
hours?: number;
349
minutes?: number;
350
seconds?: number;
351
milliseconds?: number;
352
microseconds?: number;
353
nanoseconds?: number;
354
}
355
356
// Units and options
357
type DateUnit = 'year' | 'month' | 'week' | 'day';
358
type TimeUnit = 'hour' | 'minute' | 'second' | 'millisecond' | 'microsecond' | 'nanosecond';
359
type DateTimeUnit = DateUnit | TimeUnit;
360
type DurationUnit = DateTimeUnit;
361
type YearMonthUnit = 'year' | 'month';
362
363
type ComparisonResult = -1 | 0 | 1;
364
type RoundingMode = 'ceil' | 'floor' | 'expand' | 'trunc' | 'halfCeil' | 'halfFloor' | 'halfExpand' | 'halfTrunc' | 'halfEven';
365
type OverflowMode = 'constrain' | 'reject';
366
type DisambiguationMode = 'compatible' | 'earlier' | 'later' | 'reject';
367
type OffsetDisambiguationMode = 'use' | 'ignore' | 'prefer' | 'reject';
368
369
// Option interfaces
370
interface AssignmentOptions {
371
overflow?: OverflowMode;
372
}
373
374
interface ArithmeticOptions {
375
overflow?: OverflowMode;
376
}
377
378
interface DifferenceOptions<T extends string> {
379
largestUnit?: T;
380
smallestUnit?: T;
381
roundingIncrement?: number;
382
roundingMode?: RoundingMode;
383
}
384
385
interface RoundingOptions<T extends string> {
386
smallestUnit: T;
387
roundingIncrement?: number;
388
roundingMode?: RoundingMode;
389
}
390
391
interface ZonedDateTimeAssignmentOptions extends AssignmentOptions {
392
disambiguation?: DisambiguationMode;
393
offset?: OffsetDisambiguationMode;
394
}
395
396
interface DurationArithmeticOptions {
397
relativeTo?: PlainDateLike | ZonedDateTimeLike | string;
398
}
399
```