0
# Luxon
1

2
Luxon is a comprehensive JavaScript library for working with dates and times, designed as a modern successor to Moment.js. It provides immutable DateTime, Duration, and Interval classes with extensive timezone support, internationalization, and parsing/formatting capabilities.
3

4
## Package Information
5

6
- **Package Name**: luxon
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install luxon`
10

11
## Core Imports
12

13
```javascript
14
import { 
15
  DateTime, 
16
  Duration, 
17
  Interval, 
18
  Info, 
19
  Settings, 
20
  Zone,
21
  FixedOffsetZone,
22
  IANAZone,
23
  SystemZone,
24
  InvalidZone,
25
  VERSION,
26
  lowOrderMatrix
27
} from "luxon";
28
```
29

30
For CommonJS:
31

32
```javascript
33
const { 
34
  DateTime, 
35
  Duration, 
36
  Interval, 
37
  Info, 
38
  Settings, 
39
  Zone,
40
  FixedOffsetZone,
41
  IANAZone,
42
  SystemZone,
43
  InvalidZone,
44
  VERSION,
45
  lowOrderMatrix
46
} = require("luxon");
47
```
48

49
## Basic Usage
50

51
```javascript
52
import { DateTime, Duration } from "luxon";
53

54
// Create current DateTime
55
const now = DateTime.now();
56

57
// Create specific dates
58
const dt = DateTime.local(2023, 10, 25, 14, 30);
59
const utcTime = DateTime.utc(2023, 10, 25, 14, 30);
60

61
// Parse from strings
62
const fromISO = DateTime.fromISO("2023-10-25T14:30:00");
63
const fromFormat = DateTime.fromFormat("25/10/2023", "dd/MM/yyyy");
64

65
// Format dates
66
console.log(dt.toISO()); // "2023-10-25T14:30:00.000-07:00"
67
console.log(dt.toFormat("yyyy LLL dd")); // "2023 Oct 25"
68

69
// Work with durations
70
const duration = Duration.fromObject({ hours: 2, minutes: 30 });
71
const later = dt.plus(duration);
72

73
// Date arithmetic
74
const diff = later.diff(dt, 'minutes');
75
console.log(diff.minutes); // 150
76
```
77

78
## Architecture
79

80
Luxon is built around several key immutable classes:
81

82
- **DateTime**: Primary date/time class with comprehensive formatting, parsing, and manipulation methods
83
- **Duration**: Represents time periods with units from milliseconds to years
84
- **Interval**: Represents time ranges between two DateTimes with set operations
85
- **Zone Classes**: Multiple timezone implementations (IANA, fixed offset, system, invalid)
86
- **Info**: Static utility class for locale and timezone information
87
- **Settings**: Global configuration for default timezone, locale, and behavior
88

89
All classes follow an immutable pattern where operations return new instances rather than modifying existing ones.
90

91
## Capabilities
92

93
### Date and Time Manipulation
94

95
Core functionality for creating, parsing, formatting, and manipulating dates and times with full timezone and locale support.
96

97
```javascript { .api }
98
class DateTime {
99
  // Factory methods
100
  static now(): DateTime;
101
  static local(year?, month?, day?, hour?, minute?, second?, millisecond?, opts?): DateTime;
102
  static utc(year?, month?, day?, hour?, minute?, second?, millisecond?, opts?): DateTime;
103
  static fromISO(text: string, opts?): DateTime;
104
  static fromFormat(text: string, fmt: string, opts?): DateTime;
105
  
106
  // Core properties
107
  year: number;
108
  month: number;
109
  day: number;
110
  hour: number;
111
  minute: number;
112
  second: number;
113
  
114
  // Manipulation
115
  plus(duration: Duration): DateTime;
116
  minus(duration: Duration): DateTime;
117
  set(values: object): DateTime;
118
  
119
  // Formatting
120
  toISO(opts?): string;
121
  toFormat(fmt: string, opts?): string;
122
  toLocaleString(formatOpts?, opts?): string;
123
}
124
```
125

126
[DateTime API](./datetime.md)
127

128
### Duration and Time Periods
129

130
Represents and manipulates time periods with support for multiple units and conversion between different time representations.
131

132
```javascript { .api }
133
class Duration {
134
  static fromObject(obj: object, opts?): Duration;
135
  static fromISO(text: string, opts?): Duration;
136
  static fromMillis(count: number, opts?): Duration;
137
  
138
  // Properties
139
  years: number;
140
  months: number;
141
  days: number;
142
  hours: number;
143
  minutes: number;
144
  seconds: number;
145
  milliseconds: number;
146
  
147
  // Operations
148
  plus(duration: Duration): Duration;
149
  minus(duration: Duration): Duration;
150
  as(unit: string): number;
151
  shiftTo(...units: string[]): Duration;
152
}
153
```
154

155
[Duration API](./duration.md)
156

157
### Time Intervals and Ranges
158

159
Represents time ranges between two DateTimes with support for set operations, splitting, and interval relationships.
160

161
```javascript { .api }
162
class Interval {
163
  static fromDateTimes(start: DateTime, end: DateTime): Interval;
164
  static after(start: DateTime, duration: Duration): Interval;
165
  static before(end: DateTime, duration: Duration): Interval;
166
  
167
  start: DateTime;
168
  end: DateTime;
169
  
170
  // Relationships
171
  contains(dateTime: DateTime): boolean;
172
  overlaps(other: Interval): boolean;
173
  intersection(other: Interval): Interval;
174
  union(other: Interval): Interval;
175
  
176
  // Operations
177
  length(unit?: string): number;
178
  splitBy(duration: Duration): Interval[];
179
  toDuration(unit?: string): Duration;
180
}
181
```
182

183
[Interval API](./interval.md)
184

185
### Timezone Management
186

187
Comprehensive timezone support including IANA timezone database, fixed offset zones, and system timezone handling.
188

189
```javascript { .api }
190
abstract class Zone {
191
  abstract type: string;
192
  abstract name: string;
193
  abstract offset(ts: number): number;
194
}
195

196
class IANAZone extends Zone {
197
  static create(name: string): IANAZone;
198
  static isValidZone(zone: string): boolean;
199
}
200

201
class FixedOffsetZone extends Zone {
202
  static instance(offset: number): FixedOffsetZone;
203
  static utcInstance: FixedOffsetZone;
204
}
205
```
206

207
[Timezone API](./zones.md)
208

209
### Locale and Settings
210

211
Global configuration and locale information utilities for customizing behavior and accessing internationalization data.
212

213
```javascript { .api }
214
class Settings {
215
  static defaultZone: Zone;
216
  static defaultLocale: string;
217
  static throwOnInvalid: boolean;
218
}
219

220
class Info {
221
  static months(length?: string, opts?): string[];
222
  static weekdays(length?: string, opts?): string[];
223
  static isValidIANAZone(zone: string): boolean;
224
  static features(): object;
225
}
226
```
227

228
[Info & Settings API](./info-settings.md)
229

230
## Types
231

232
```javascript { .api }
233
interface DateTimeOptions {
234
  zone?: string | Zone;
235
  locale?: string;
236
  numberingSystem?: string;
237
  outputCalendar?: string;
238
}
239

240
interface DurationOptions {
241
  locale?: string;
242
  numberingSystem?: string;
243
  conversionAccuracy?: string;
244
}
245

246
interface ToISOOptions {
247
  suppressMilliseconds?: boolean;
248
  suppressSeconds?: boolean;
249
  includeOffset?: boolean;
250
  format?: string;
251
}
252

253
interface ValidationError {
254
  reason: string;
255
  explanation?: string;
256
}
257
```
258

259
## Constants
260

261
```javascript { .api }
262
/**
263
 * Library version string
264
 */
265
const VERSION: string; // "2.5.2"
266

267
/**
268
 * Time unit conversion matrix for precise duration calculations
269
 * Contains conversion factors between time units (weeks, days, hours, minutes, seconds, milliseconds)
270
 */
271
const lowOrderMatrix: object;
272
```