0
# Timezone API
1

2
Luxon provides comprehensive timezone support through multiple Zone implementations. The Zone system handles timezone conversions, offset calculations, and timezone name resolution.
3

4
## Capabilities
5

6
### Zone Abstract Base Class
7

8
The base class that all timezone implementations extend.
9

10
```javascript { .api }
11
/**
12
 * Abstract base class for all timezone implementations
13
 */
14
abstract class Zone {
15
  /** Type identifier for the zone implementation */
16
  abstract type: string;
17
  
18
  /** Zone name or identifier */
19
  abstract name: string;
20
  
21
  /** IANA timezone name (defaults to name) */
22
  get ianaName(): string;
23
  
24
  /** Whether the zone has a fixed offset (no DST) */
25
  abstract isUniversal: boolean;
26
  
27
  /** Whether the zone is valid */
28
  abstract isValid: boolean;
29
  
30
  /**
31
   * Get timezone offset name at specific timestamp
32
   * @param ts - Timestamp in milliseconds
33
   * @param opts - Options including format and locale
34
   */
35
  abstract offsetName(ts: number, opts: {format?: string, locale?: string}): string;
36
  
37
  /**
38
   * Format offset as string
39
   * @param ts - Timestamp in milliseconds  
40
   * @param format - Format type ('short', 'narrow', 'long')
41
   */
42
  abstract formatOffset(ts: number, format: string): string;
43
  
44
  /**
45
   * Get offset in minutes at specific timestamp
46
   * @param ts - Timestamp in milliseconds
47
   */
48
  abstract offset(ts: number): number;
49
  
50
  /**
51
   * Check equality with another zone
52
   * @param otherZone - Zone to compare
53
   */
54
  abstract equals(otherZone: Zone): boolean;
55
}
56
```
57

58
### FixedOffsetZone
59

60
Zone implementation for fixed UTC offsets.
61

62
```javascript { .api }
63
/**
64
 * Timezone with fixed offset from UTC (no daylight saving time)
65
 */
66
class FixedOffsetZone extends Zone {
67
  type: "fixed";
68
  isUniversal: true;
69
  isValid: true;
70
  
71
  /**
72
   * UTC timezone singleton
73
   */
74
  static utcInstance: FixedOffsetZone;
75
  
76
  /**
77
   * Get or create FixedOffsetZone instance
78
   * @param offset - Offset in minutes from UTC
79
   */
80
  static instance(offset: number): FixedOffsetZone;
81
  
82
  /**
83
   * Parse UTC offset string to create FixedOffsetZone
84
   * @param s - Offset string (e.g., "+05:00", "-0700", "Z")
85
   */
86
  static parseSpecifier(s: string): FixedOffsetZone;
87
  
88
  name: string;           // e.g., "UTC", "UTC+5", "UTC-7"
89
  ianaName: string;       // e.g., "Etc/UTC", "Etc/GMT-5"
90
  
91
  /**
92
   * Returns zone name
93
   */
94
  offsetName(): string;
95
  
96
  /**
97
   * Format offset string
98
   * @param ts - Timestamp (unused for fixed zones)
99
   * @param format - Format type
100
   */
101
  formatOffset(ts: number, format: string): string;
102
  
103
  /**
104
   * Returns the fixed offset
105
   * @param ts - Timestamp (unused for fixed zones)
106
   */
107
  offset(ts: number): number;
108
  
109
  /**
110
   * Check equality with another zone
111
   * @param otherZone - Zone to compare
112
   */
113
  equals(otherZone: Zone): boolean;
114
}
115
```
116

117
### IANAZone
118

119
Zone implementation using the IANA timezone database.
120

121
```javascript { .api }
122
/**
123
 * Timezone using IANA timezone database (e.g., "America/New_York")
124
 */
125
class IANAZone extends Zone {
126
  type: "iana";
127
  isUniversal: false;
128
  
129
  /**
130
   * Create or retrieve cached IANA zone
131
   * @param name - IANA timezone name
132
   */
133
  static create(name: string): IANAZone;
134
  
135
  /**
136
   * Reset internal cache
137
   */
138
  static resetCache(): void;
139
  
140
  /**
141
   * Check if timezone name exists in IANA database
142
   * @param zone - Timezone name to check
143
   */
144
  static isValidZone(zone: string): boolean;
145
  
146
  name: string;          // IANA timezone name
147
  isValid: boolean;      // Whether timezone exists
148
  
149
  /**
150
   * Get timezone offset name at timestamp
151
   * @param ts - Timestamp in milliseconds
152
   * @param opts - Options including format and locale
153
   */
154
  offsetName(ts: number, opts: {format?: string, locale?: string}): string;
155
  
156
  /**
157
   * Format offset as string
158
   * @param ts - Timestamp in milliseconds
159
   * @param format - Format type
160
   */
161
  formatOffset(ts: number, format: string): string;
162
  
163
  /**
164
   * Get offset in minutes at timestamp (accounts for DST)
165
   * @param ts - Timestamp in milliseconds
166
   */
167
  offset(ts: number): number;
168
  
169
  /**
170
   * Check equality with another zone
171
   * @param otherZone - Zone to compare
172
   */
173
  equals(otherZone: Zone): boolean;
174
}
175
```
176

177
### SystemZone
178

179
Zone implementation using the system's local timezone.
180

181
```javascript { .api }
182
/**
183
 * System/local timezone implementation
184
 */
185
class SystemZone extends Zone {
186
  type: "system";
187
  isUniversal: false;
188
  isValid: true;
189
  
190
  /**
191
   * Singleton system zone instance
192
   */
193
  static instance: SystemZone;
194
  
195
  name: string;          // System timezone name (detected)
196
  
197
  /**
198
   * Get timezone offset name at timestamp
199
   * @param ts - Timestamp in milliseconds
200
   * @param opts - Options including format and locale
201
   */
202
  offsetName(ts: number, opts: {format?: string, locale?: string}): string;
203
  
204
  /**
205
   * Format offset as string
206
   * @param ts - Timestamp in milliseconds
207
   * @param format - Format type
208
   */
209
  formatOffset(ts: number, format: string): string;
210
  
211
  /**
212
   * Get system offset in minutes at timestamp
213
   * @param ts - Timestamp in milliseconds
214
   */
215
  offset(ts: number): number;
216
  
217
  /**
218
   * Check equality with another zone
219
   * @param otherZone - Zone to compare
220
   */
221
  equals(otherZone: Zone): boolean;
222
}
223
```
224

225
### InvalidZone
226

227
Zone implementation for invalid timezone specifications.
228

229
```javascript { .api }
230
/**
231
 * Invalid timezone implementation (for error handling)
232
 */
233
class InvalidZone extends Zone {
234
  type: "invalid";
235
  isUniversal: false;
236
  isValid: false;
237
  
238
  name: string;          // The invalid timezone name that was attempted
239
  
240
  /**
241
   * Always returns null
242
   */
243
  offsetName(): null;
244
  
245
  /**
246
   * Always returns empty string
247
   * @param ts - Timestamp (unused)
248
   * @param format - Format (unused)
249
   */
250
  formatOffset(ts: number, format: string): string;
251
  
252
  /**
253
   * Always returns NaN
254
   * @param ts - Timestamp (unused)
255
   */
256
  offset(ts: number): number;
257
  
258
  /**
259
   * Always returns false
260
   * @param otherZone - Zone to compare (unused)
261
   */
262
  equals(otherZone: Zone): boolean;
263
}
264
```
265

266
## Usage Examples
267

268
```javascript
269
import { DateTime, FixedOffsetZone, IANAZone, SystemZone } from "luxon";
270

271
// Working with fixed offset zones
272
const utc = FixedOffsetZone.utcInstance;
273
const est = FixedOffsetZone.instance(-300); // UTC-5 (300 minutes behind)
274
const parsedOffset = FixedOffsetZone.parseSpecifier("+05:30");
275

276
console.log(utc.name);     // "UTC"
277
console.log(est.name);     // "UTC-5"
278
console.log(est.offset()); // -300
279

280
// Working with IANA zones
281
const nyZone = IANAZone.create("America/New_York");
282
const tokyoZone = IANAZone.create("Asia/Tokyo");
283
const invalidZone = IANAZone.create("Invalid/Zone");
284

285
console.log(nyZone.isValid);     // true
286
console.log(invalidZone.isValid); // false
287

288
// Check if timezone exists
289
console.log(IANAZone.isValidZone("America/New_York")); // true
290
console.log(IANAZone.isValidZone("America/Invalid"));  // false
291

292
// Using zones with DateTime
293
const dt = DateTime.now();
294
const dtInNY = dt.setZone("America/New_York");
295
const dtInTokyo = dt.setZone(tokyoZone);
296
const dtInEST = dt.setZone(est);
297

298
// System timezone
299
const systemZone = SystemZone.instance;
300
console.log(systemZone.name); // System-detected timezone name
301

302
// Timezone information at specific times
303
const timestamp = DateTime.local(2023, 7, 15).toMillis(); // Summer
304
const winterTimestamp = DateTime.local(2023, 1, 15).toMillis(); // Winter
305

306
// DST affects IANA zones but not fixed offset zones
307
console.log(nyZone.offset(timestamp));      // e.g., -240 (EDT)
308
console.log(nyZone.offset(winterTimestamp)); // e.g., -300 (EST)
309
console.log(est.offset(timestamp));         // -300 (always)
310
console.log(est.offset(winterTimestamp));   // -300 (always)
311

312
// Offset names
313
console.log(nyZone.offsetName(timestamp, { format: 'short' }));      // "EDT"
314
console.log(nyZone.offsetName(winterTimestamp, { format: 'short' })); // "EST"
315
console.log(nyZone.offsetName(timestamp, { format: 'long' }));       // "Eastern Daylight Time"
316

317
// Format offsets
318
console.log(nyZone.formatOffset(timestamp, 'short'));      // "-04:00"
319
console.log(nyZone.formatOffset(winterTimestamp, 'short')); // "-05:00"
320
```
321

322
## Timezone Detection and Validation
323

324
```javascript
325
import { Info, Settings, IANAZone } from "luxon";
326

327
// Check if timezone has daylight saving time
328
console.log(Info.hasDST("America/New_York")); // true
329
console.log(Info.hasDST("America/Phoenix"));  // false
330
console.log(Info.hasDST("UTC"));              // false
331

332
// Validate timezone names
333
console.log(Info.isValidIANAZone("America/New_York")); // true
334
console.log(Info.isValidIANAZone("Invalid/Zone"));     // false
335

336
// Convert various inputs to Zone instances
337
const zone1 = Info.normalizeZone("America/New_York");    // IANAZone
338
const zone2 = Info.normalizeZone(-300);                  // FixedOffsetZone
339
const zone3 = Info.normalizeZone("system");              // SystemZone
340

341
// Set default timezone
342
Settings.defaultZone = "America/New_York";
343
Settings.defaultZone = IANAZone.create("Asia/Tokyo");
344
Settings.defaultZone = FixedOffsetZone.instance(330); // UTC+5:30
345
```
346

347
## Common Timezone Patterns
348

349
```javascript
350
// UTC operations
351
const utcNow = DateTime.utc();
352
const utcZone = FixedOffsetZone.utcInstance;
353

354
// Local timezone operations  
355
const localNow = DateTime.local();
356
const systemZone = SystemZone.instance;
357

358
// Specific timezone operations
359
const nyTime = DateTime.now().setZone("America/New_York");
360
const londonTime = DateTime.now().setZone("Europe/London");
361

362
// Fixed offset without DST
363
const alwaysUTCMinus5 = DateTime.now().setZone(FixedOffsetZone.instance(-300));
364

365
// Converting between timezones
366
const meeting = DateTime.local(2023, 6, 15, 14, 0); // 2 PM local
367
const meetingInNY = meeting.setZone("America/New_York");
368
const meetingInTokyo = meeting.setZone("Asia/Tokyo");
369

370
console.log(`Local: ${meeting.toFormat('HH:mm')}`);
371
console.log(`NY: ${meetingInNY.toFormat('HH:mm')}`);
372
console.log(`Tokyo: ${meetingInTokyo.toFormat('HH:mm')}`);
373
```