0
# Duration API
1

2
The Duration class represents time periods and supports operations like addition, subtraction, and unit conversion. It handles units from milliseconds to years with flexible conversion accuracy settings.
3

4
## Capabilities
5

6
### Static Factory Methods
7

8
Methods for creating Duration instances from various sources.
9

10
```javascript { .api }
11
/**
12
 * Create Duration from milliseconds
13
 * @param count - Number of milliseconds
14
 * @param opts - Options including locale, numberingSystem, conversionAccuracy
15
 */
16
static fromMillis(count: number, opts?): Duration;
17

18
/**
19
 * Create Duration from object with duration units
20
 * @param obj - Object with duration properties (years, months, days, etc.)
21
 * @param opts - Options including locale, numberingSystem, conversionAccuracy
22
 */
23
static fromObject(obj: object, opts?): Duration;
24

25
/**
26
 * Create Duration from Duration-like input
27
 * @param durationLike - Duration instance, object, or number (milliseconds)
28
 */
29
static fromDurationLike(durationLike: Duration | object | number): Duration;
30

31
/**
32
 * Parse Duration from ISO 8601 duration string
33
 * @param text - ISO 8601 duration string (e.g., "P1Y2M3DT4H5M6S")
34
 * @param opts - Options including locale, numberingSystem, conversionAccuracy
35
 */
36
static fromISO(text: string, opts?): Duration;
37

38
/**
39
 * Parse Duration from ISO 8601 time string (if less than 24 hours)
40
 * @param text - ISO 8601 time string (e.g., "14:30:15")
41
 * @param opts - Options including locale, numberingSystem, conversionAccuracy
42
 */
43
static fromISOTime(text: string, opts?): Duration;
44

45
/**
46
 * Create an invalid Duration
47
 * @param reason - Reason for invalidity
48
 * @param explanation - Additional explanation
49
 */
50
static invalid(reason: string, explanation?: string): Duration;
51

52
/**
53
 * Check if object is a Duration instance
54
 * @param o - Object to check
55
 */
56
static isDuration(o: any): boolean;
57
```
58

59
### Instance Properties
60

61
Access duration components and metadata.
62

63
```javascript { .api }
64
// Configuration
65
locale: string;
66
numberingSystem: string;
67

68
// Duration components
69
years: number;
70
quarters: number;
71
months: number;
72
weeks: number;
73
days: number;
74
hours: number;
75
minutes: number;
76
seconds: number;
77
milliseconds: number;
78

79
// Validation
80
isValid: boolean;
81
invalidReason: string | null;
82
invalidExplanation: string | null;
83
```
84

85
### Instance Methods
86

87
#### Formatting
88

89
```javascript { .api }
90
/**
91
 * Format duration with custom format string
92
 * @param fmt - Format pattern using duration tokens
93
 * @param opts - Options including round
94
 */
95
toFormat(fmt: string, opts?): string;
96

97
/**
98
 * Human-readable string with all significant units
99
 * @param opts - Options including listStyle, unitDisplay, locale
100
 */
101
toHuman(opts?): string;
102

103
/**
104
 * Convert to JavaScript object
105
 */
106
toObject(): object;
107

108
/**
109
 * Convert to ISO 8601 duration string
110
 */
111
toISO(): string;
112

113
/**
114
 * Convert to ISO 8601 time string (if less than 24 hours)
115
 * @param opts - Options including suppressMilliseconds, suppressSeconds
116
 */
117
toISOTime(opts?): string;
118

119
/**
120
 * JSON representation (ISO string)
121
 */
122
toJSON(): string;
123

124
/**
125
 * String representation (ISO format)
126
 */
127
toString(): string;
128
```
129

130
#### Numeric Conversion
131

132
```javascript { .api }
133
/**
134
 * Total duration in milliseconds
135
 */
136
toMillis(): number;
137

138
/**
139
 * Total duration in milliseconds (for sorting/comparison)
140
 */
141
valueOf(): number;
142
```
143

144
#### Arithmetic Operations
145

146
```javascript { .api }
147
/**
148
 * Add another duration
149
 * @param duration - Duration to add or object with duration units
150
 */
151
plus(duration: Duration | object): Duration;
152

153
/**
154
 * Subtract another duration
155
 * @param duration - Duration to subtract or object with duration units
156
 */
157
minus(duration: Duration | object): Duration;
158

159
/**
160
 * Return negative duration
161
 */
162
negate(): Duration;
163
```
164

165
#### Unit Operations
166

167
```javascript { .api }
168
/**
169
 * Transform duration units with function
170
 * @param fn - Function to apply to each unit value
171
 */
172
mapUnits(fn: (value: number, unit: string) => number): Duration;
173

174
/**
175
 * Get value of specific unit
176
 * @param unit - Unit name (years, months, days, etc.)
177
 */
178
get(unit: string): number;
179

180
/**
181
 * Set specific duration values
182
 * @param values - Object with duration properties to set
183
 */
184
set(values: object): Duration;
185

186
/**
187
 * Reconfigure duration settings
188
 * @param opts - Options including locale, numberingSystem, conversionAccuracy
189
 */
190
reconfigure(opts: {locale?, numberingSystem?, conversionAccuracy?}): Duration;
191

192
/**
193
 * Convert duration to single unit
194
 * @param unit - Target unit (years, months, days, hours, minutes, seconds, milliseconds)
195
 */
196
as(unit: string): number;
197

198
/**
199
 * Normalize duration to canonical representation
200
 */
201
normalize(): Duration;
202

203
/**
204
 * Convert to different units
205
 * @param units - Array of target units in preferred order
206
 */
207
shiftTo(...units: string[]): Duration;
208
```
209

210
#### Comparison
211

212
```javascript { .api }
213
/**
214
 * Check equality with other Duration
215
 * @param other - Duration to compare
216
 */
217
equals(other: Duration): boolean;
218
```
219

220
### Conversion Matrix Constants
221

222
Constants for unit conversion accuracy.
223

224
```javascript { .api }
225
/**
226
 * Low-order conversion matrix for precise calculations
227
 */
228
static lowOrderMatrix: object;
229

230
/**
231
 * Casual conversion matrix (default) - 1 month = 30 days, 1 year = 365 days
232
 */
233
static casualMatrix: object;
234

235
/**
236
 * Accurate conversion matrix for more precise date-aware calculations
237
 */
238
static accurateMatrix: object;
239
```
240

241
## Usage Examples
242

243
```javascript
244
import { Duration } from "luxon";
245

246
// Creating durations
247
const duration1 = Duration.fromObject({ hours: 2, minutes: 30 });
248
const duration2 = Duration.fromMillis(5400000); // 1.5 hours in milliseconds
249
const duration3 = Duration.fromISO("PT2H30M"); // ISO duration string
250

251
console.log(duration1.hours);    // 2
252
console.log(duration1.minutes);  // 30
253
console.log(duration1.toMillis()); // 9000000
254

255
// Formatting
256
console.log(duration1.toFormat("h 'hours', m 'minutes'")); // "2 hours, 30 minutes"
257
console.log(duration1.toHuman()); // "2 hours, 30 minutes"
258
console.log(duration1.toISO());   // "PT2H30M"
259

260
// Unit conversion
261
console.log(duration1.as('minutes')); // 150
262
console.log(duration1.shiftTo('minutes').minutes); // 150
263

264
// Arithmetic
265
const total = duration1.plus({ minutes: 15 }); // 2 hours, 45 minutes
266
const difference = duration1.minus({ minutes: 30 }); // 2 hours
267
const negative = duration1.negate(); // -2 hours, -30 minutes
268

269
// Working with different conversion matrices
270
const precise = Duration.fromObject(
271
  { months: 1, days: 15 }, 
272
  { conversionAccuracy: 'longterm' }
273
);
274
```
275

276
## Format Tokens
277

278
Duration formatting uses these tokens:
279

280
- `S` - milliseconds
281
- `s` - seconds  
282
- `m` - minutes
283
- `h` - hours
284
- `d` - days
285
- `w` - weeks
286
- `M` - months
287
- `y` - years
288

289
Modifiers:
290
- Single token (e.g., `s`) - minimal digits
291
- Padded token (e.g., `ss`) - zero-padded to 2 digits
292
- Literal text in quotes (e.g., `'hours'`)
293

294
## Conversion Accuracy
295

296
Duration supports different conversion accuracy modes:
297

298
- **`casual`** (default): 1 month = 30 days, 1 year = 365 days
299
- **`longterm`**: More accurate for longer periods, considers leap years  
300
- **`accurate`**: Most precise, but may be slower for large durations