0
# Duration Operations
1

2
Complete duration system for working with time intervals, performing duration arithmetic, and formatting duration output. Durations represent lengths of time rather than specific points in time.
3

4
## Capabilities
5

6
### Duration Creation
7

8
Methods for creating Duration instances from various input types.
9

10
```javascript { .api }
11
/**
12
 * Create a Duration instance
13
 * @param inp - Duration input (number, string, object, Duration, or from/to object)
14
 * @param unit - Unit of time when inp is number/string
15
 * @returns New Duration instance
16
 */
17
function duration(inp?: DurationInputArg1, unit?: DurationInputArg2): Duration;
18

19
// Input types
20
type DurationInputArg1 = Duration | number | string | FromTo | DurationInputObject | void;
21
type DurationInputArg2 = unitOfTime.DurationConstructor;
22

23
interface DurationInputObject extends MomentInputObject {
24
  quarters?: numberlike;
25
  quarter?: numberlike;
26
  Q?: numberlike;
27
  weeks?: numberlike;
28
  week?: numberlike;
29
  w?: numberlike;
30
}
31

32
interface FromTo {
33
  from: MomentInput;
34
  to: MomentInput;
35
}
36

37
// Duration constructor units
38
type DurationConstructor = "year" | "years" | "y" |
39
                          "quarter" | "quarters" | "Q" |
40
                          "month" | "months" | "M" |
41
                          "week" | "weeks" | "w" |
42
                          "isoWeek" | "isoWeeks" | "W" |
43
                          "day" | "days" | "d" |
44
                          "hour" | "hours" | "h" |
45
                          "minute" | "minutes" | "m" |
46
                          "second" | "seconds" | "s" |
47
                          "millisecond" | "milliseconds" | "ms";
48
```
49

50
**Usage Examples:**
51

52
```javascript
53
import moment from "moment";
54

55
// From number and unit
56
const hours2 = moment.duration(2, "hours");
57
const minutes30 = moment.duration(30, "minutes");
58
const days5 = moment.duration(5, "days");
59

60
// From milliseconds (default unit)
61
const ms5000 = moment.duration(5000); // 5 seconds
62

63
// From object
64
const complex = moment.duration({
65
  years: 1,
66
  months: 2,
67
  days: 3,
68
  hours: 4,
69
  minutes: 5,
70
  seconds: 6
71
});
72

73
// From string (ISO 8601 duration format)
74
const iso = moment.duration("P1Y2M3DT4H5M6S"); // 1 year, 2 months, 3 days, 4 hours, 5 minutes, 6 seconds
75
const simple = moment.duration("2:30:45"); // 2 hours, 30 minutes, 45 seconds
76

77
// From two moments (time between them)
78
const start = moment("2023-12-25T10:00:00");
79
const end = moment("2023-12-25T15:30:00");
80
const between = moment.duration({ from: start, to: end });
81

82
// Clone existing duration
83
const original = moment.duration(2, "hours");
84
const copy = moment.duration(original);
85

86
console.log(hours2.asHours()); // 2
87
console.log(minutes30.asMinutes()); // 30
88
console.log(complex.asMilliseconds()); // Total milliseconds
89
console.log(between.asHours()); // 5.5 hours
90
```
91

92
### Duration Arithmetic
93

94
Methods for adding and subtracting durations.
95

96
```javascript { .api }
97
/**
98
 * Add time to this duration
99
 * @param inp - Amount to add (number, string, Duration, or object)
100
 * @param unit - Unit of time when inp is number/string
101
 * @returns New Duration instance (original is not modified)
102
 */
103
add(inp?: DurationInputArg1, unit?: DurationInputArg2): Duration;
104

105
/**
106
 * Subtract time from this duration
107
 * @param inp - Amount to subtract (number, string, Duration, or object)
108
 * @param unit - Unit of time when inp is number/string
109
 * @returns New Duration instance (original is not modified)
110
 */
111
subtract(inp?: DurationInputArg1, unit?: DurationInputArg2): Duration;
112

113
/**
114
 * Get absolute value of duration (remove negative sign)
115
 * @returns New Duration instance with positive value
116
 */
117
abs(): Duration;
118

119
/**
120
 * Create a copy of this Duration instance
121
 * @returns New Duration instance with same values
122
 */
123
clone(): Duration;
124
```
125

126
**Usage Examples:**
127

128
```javascript
129
import moment from "moment";
130

131
const duration1 = moment.duration(2, "hours");
132
const duration2 = moment.duration(30, "minutes");
133

134
// Add durations
135
const sum = duration1.add(duration2);
136
console.log(sum.asMinutes()); // 150 minutes (2.5 hours)
137

138
// Add with different input types
139
const base = moment.duration(1, "hour");
140
const added1 = base.add(30, "minutes");
141
const added2 = base.add({ minutes: 45, seconds: 30 });
142
const added3 = base.add("PT30M"); // ISO 8601 format
143

144
console.log(added1.asMinutes()); // 90 minutes
145
console.log(added2.asMinutes()); // 105.5 minutes
146
console.log(added3.asMinutes()); // 90 minutes
147

148
// Subtract durations
149
const total = moment.duration(3, "hours");
150
const remaining = total.subtract(45, "minutes");
151
console.log(remaining.asHours()); // 2.25 hours
152

153
// Absolute value
154
const negative = moment.duration(-2, "hours");
155
const positive = negative.abs();
156
console.log(negative.asHours()); // -2
157
console.log(positive.asHours()); // 2
158

159
// Chaining operations
160
const result = moment.duration(1, "day")
161
  .add(6, "hours")
162
  .subtract(30, "minutes")
163
  .add({ hours: 2, minutes: 15 });
164
console.log(result.asHours()); // 31.75 hours
165

166
// Clone to avoid mutation
167
const original = moment.duration(2, "hours");
168
const modified = original.clone().add(1, "hour");
169
console.log(original.asHours()); // 2 (unchanged)
170
console.log(modified.asHours()); // 3
171
```
172

173
### Duration Getters
174

175
Methods for retrieving duration components and converted values.
176

177
```javascript { .api }
178
/**
179
 * Get duration component for specific unit
180
 * @param units - Time unit to get
181
 * @returns Value for the specified unit
182
 */
183
get(units: unitOfTime.Base): number;
184

185
/**
186
 * Convert entire duration to specified unit
187
 * @param units - Time unit to convert to
188
 * @returns Total duration in specified unit
189
 */
190
as(units: unitOfTime.Base): number;
191

192
// Specific component getters (get portion of duration)
193
milliseconds(): number;
194
seconds(): number;
195
minutes(): number;
196
hours(): number;
197
days(): number;
198
weeks(): number;
199
months(): number;
200
years(): number;
201

202
// Total duration converters (convert entire duration)
203
asMilliseconds(): number;
204
asSeconds(): number;
205
asMinutes(): number;
206
asHours(): number;
207
asDays(): number;
208
asWeeks(): number;
209
asMonths(): number;
210
asYears(): number;
211

212
// Base units
213
type Base = "year" | "years" | "y" |
214
            "month" | "months" | "M" |
215
            "week" | "weeks" | "w" |
216
            "day" | "days" | "d" |
217
            "hour" | "hours" | "h" |
218
            "minute" | "minutes" | "m" |
219
            "second" | "seconds" | "s" |
220
            "millisecond" | "milliseconds" | "ms";
221
```
222

223
**Usage Examples:**
224

225
```javascript
226
import moment from "moment";
227

228
// Create a complex duration
229
const duration = moment.duration({
230
  hours: 25,
231
  minutes: 90,
232
  seconds: 130
233
});
234

235
// Component getters (individual parts)
236
console.log(duration.hours()); // 1 (25 hours = 1 day + 1 hour)
237
console.log(duration.minutes()); // 32 (90 minutes + 130 seconds = 92 minutes = 1 hour + 32 minutes)
238
console.log(duration.seconds()); // 10 (130 seconds = 2 minutes + 10 seconds)
239
console.log(duration.days()); // 1 (from 25 hours)
240

241
// Total converters (entire duration in unit)
242
console.log(duration.asHours()); // 26.53... (total hours)
243
console.log(duration.asMinutes()); // 1592.17... (total minutes)
244
console.log(duration.asSeconds()); // 95530 (total seconds)
245
console.log(duration.asMilliseconds()); // 95530000 (total milliseconds)
246

247
// Generic get and as methods
248
console.log(duration.get("hours")); // 1 (component)
249
console.log(duration.as("hours")); // 26.53... (total)
250
console.log(duration.get("minutes")); // 32 (component)
251
console.log(duration.as("minutes")); // 1592.17... (total)
252

253
// Simple duration examples
254
const simple = moment.duration(2.5, "hours");
255
console.log(simple.hours()); // 2 (component)
256
console.log(simple.minutes()); // 30 (component)
257
console.log(simple.asHours()); // 2.5 (total)
258
console.log(simple.asMinutes()); // 150 (total)
259

260
// Negative durations
261
const negative = moment.duration(-75, "minutes");
262
console.log(negative.hours()); // -1
263
console.log(negative.minutes()); // -15
264
console.log(negative.asHours()); // -1.25
265
```
266

267
### Duration Formatting and Display
268

269
Methods for converting durations to human-readable strings.
270

271
```javascript { .api }
272
/**
273
 * Get human-readable representation of duration
274
 * @param argWithSuffix - Include "ago"/"in" suffix (default: false)
275
 * @param argThresholds - Custom thresholds for units
276
 * @returns Human-readable string like "2 hours", "a day"
277
 */
278
humanize(argWithSuffix?: boolean, argThresholds?: argThresholdOpts): string;
279
humanize(argThresholds?: argThresholdOpts): string;
280

281
/**
282
 * Get ISO 8601 duration string representation
283
 * @returns ISO 8601 formatted string like "PT2H30M"
284
 */
285
toISOString(): string;
286

287
/**
288
 * Get JSON representation (same as toISOString)
289
 * @returns ISO 8601 formatted string for JSON serialization
290
 */
291
toJSON(): string;
292

293
/**
294
 * Check if this duration represents a valid time span
295
 * @returns true if valid, false otherwise
296
 */
297
isValid(): boolean;
298

299
/**
300
 * Get numeric value (milliseconds, same as asMilliseconds)
301
 * @returns Duration in milliseconds
302
 */
303
valueOf(): number;
304

305
interface argThresholdOpts {
306
  ss?: number; // seconds
307
  s?: number;  // second
308
  m?: number;  // minute
309
  h?: number;  // hour
310
  d?: number;  // day
311
  w?: number | void; // week
312
  M?: number;  // month
313
}
314
```
315

316
**Usage Examples:**
317

318
```javascript
319
import moment from "moment";
320

321
// Basic humanization
322
const duration1 = moment.duration(2, "hours");
323
const duration2 = moment.duration(90, "minutes");
324
const duration3 = moment.duration(1, "day");
325

326
console.log(duration1.humanize()); // "2 hours"
327
console.log(duration2.humanize()); // "an hour" (90 minutes rounds to 1 hour)
328
console.log(duration3.humanize()); // "a day"
329

330
// With suffix
331
console.log(duration1.humanize(true)); // "in 2 hours"
332
console.log(moment.duration(-2, "hours").humanize(true)); // "2 hours ago"
333

334
// Various durations
335
const examples = [
336
  moment.duration(45, "seconds"),
337
  moment.duration(2, "minutes"),
338
  moment.duration(1, "hour"),
339
  moment.duration(2, "days"),
340
  moment.duration(1, "week"),
341
  moment.duration(3, "months"),
342
  moment.duration(1, "year")
343
];
344

345
examples.forEach(d => {
346
  console.log(`${d.asMilliseconds()}ms -> ${d.humanize()}`);
347
});
348
// Output:
349
// "45000ms -> a few seconds"
350
// "120000ms -> 2 minutes" 
351
// "3600000ms -> an hour"
352
// "172800000ms -> 2 days"
353
// "604800000ms -> 7 days"
354
// "7776000000ms -> 3 months"
355
// "31536000000ms -> a year"
356

357
// ISO 8601 formatting
358
const complex = moment.duration({
359
  years: 1,
360
  months: 2,
361
  days: 3,
362
  hours: 4,
363
  minutes: 5,
364
  seconds: 6
365
});
366

367
console.log(complex.toISOString()); // "P1Y2M3DT4H5M6S"
368
console.log(duration1.toISOString()); // "PT2H"
369
console.log(moment.duration(90, "minutes").toISOString()); // "PT1H30M"
370

371
// JSON serialization
372
console.log(JSON.stringify({ duration: duration1 })); // {"duration":"PT2H"}
373

374
// Validation
375
console.log(duration1.isValid()); // true
376
console.log(moment.duration("invalid").isValid()); // false
377

378
// Numeric value
379
console.log(duration1.valueOf()); // 7200000 (milliseconds)
380
console.log(+duration1); // 7200000 (same as valueOf)
381

382
// Custom thresholds for humanize
383
const customDuration = moment.duration(90, "seconds");
384
console.log(customDuration.humanize()); // "2 minutes" (default)
385
console.log(customDuration.humanize({ ss: 60 })); // "a minute" (custom threshold)
386
```
387

388
### Duration Localization
389

390
Localization support for duration formatting.
391

392
```javascript { .api }
393
/**
394
 * Get or set locale for this duration instance
395
 * @param locale - Locale identifier (when setting)
396
 * @returns Current locale string (when getting) or this duration (when setting)
397
 */
398
locale(): string;
399
locale(locale: LocaleSpecifier): Duration;
400

401
/**
402
 * Get locale data object for this duration's locale
403
 * @returns Locale data object
404
 */
405
localeData(): Locale;
406

407
type LocaleSpecifier = string | Moment | Duration | string[] | boolean;
408
```
409

410
**Usage Examples:**
411

412
```javascript
413
import moment from "moment";
414

415
const duration = moment.duration(2, "hours");
416

417
// Default locale
418
console.log(duration.humanize()); // "2 hours"
419
console.log(duration.locale()); // "en"
420

421
// Set locale
422
const frenchDuration = duration.clone().locale("fr");
423
console.log(frenchDuration.humanize()); // "2 heures"
424
console.log(frenchDuration.locale()); // "fr"
425

426
// Different locales
427
const germanDuration = duration.clone().locale("de");
428
console.log(germanDuration.humanize()); // "2 Stunden"
429

430
// Relative time with suffix in different locales
431
const relativeDuration = moment.duration(30, "minutes");
432
console.log(relativeDuration.humanize(true)); // "in 30 minutes"
433
console.log(relativeDuration.clone().locale("fr").humanize(true)); // "dans 30 minutes"
434
console.log(relativeDuration.clone().locale("es").humanize(true)); // "en 30 minutos"
435

436
// Locale data
437
const localeData = frenchDuration.localeData();
438
console.log(localeData.relativeTime.h); // "une heure" (French hour format)
439
```
440

441
### Duration Utilities and Advanced Usage
442

443
Advanced patterns and utility methods for working with durations.
444

445
```javascript { .api }
446
/**
447
 * Create duration from the difference between two moments
448
 * @param from - Start moment
449
 * @param to - End moment
450
 * @returns Duration representing the time between moments
451
 */
452
// Usage: moment.duration({ from: moment1, to: moment2 })
453

454
/**
455
 * Parse ISO 8601 duration strings
456
 * @param input - ISO 8601 duration string
457
 * @returns Duration instance
458
 */
459
// Usage: moment.duration("P1Y2M3DT4H5M6S")
460
```
461

462
**Advanced Usage Examples:**
463

464
```javascript
465
import moment from "moment";
466

467
// Calculate age as duration
468
function getAge(birthDate) {
469
  const birth = moment(birthDate);
470
  const now = moment();
471
  return moment.duration({ from: birth, to: now });
472
}
473

474
const age = getAge("1990-06-15");
475
console.log(age.humanize()); // "33 years" (approximate)
476
console.log(age.asYears()); // 33.5... (precise)
477

478
// Time remaining calculations
479
function timeUntil(targetDate) {
480
  const target = moment(targetDate);
481
  const now = moment();
482
  return moment.duration({ from: now, to: target });
483
}
484

485
const christmas = timeUntil("2024-12-25");
486
console.log(christmas.humanize()); // "11 months" (approximate)
487
console.log(`${christmas.days()} days remaining`); // Exact days
488

489
// Working time calculations
490
function calculateWorkingHours(startTime, endTime, breaks = []) {
491
  let totalTime = moment.duration({ from: startTime, to: endTime });
492
  
493
  breaks.forEach(breakPeriod => {
494
    const breakDuration = moment.duration({
495
      from: breakPeriod.start,
496
      to: breakPeriod.end
497
    });
498
    totalTime = totalTime.subtract(breakDuration);
499
  });
500
  
501
  return totalTime;
502
}
503

504
const workStart = moment("2023-12-25T09:00:00");
505
const workEnd = moment("2023-12-25T17:30:00");
506
const breaks = [
507
  { start: moment("2023-12-25T12:00:00"), end: moment("2023-12-25T13:00:00") },
508
  { start: moment("2023-12-25T15:00:00"), end: moment("2023-12-25T15:15:00") }
509
];
510

511
const workingTime = calculateWorkingHours(workStart, workEnd, breaks);
512
console.log(workingTime.asHours()); // 7.25 hours
513

514
// Duration formatting for timers
515
function formatTimer(milliseconds) {
516
  const duration = moment.duration(milliseconds);
517
  const hours = String(Math.floor(duration.asHours())).padStart(2, '0');
518
  const minutes = String(duration.minutes()).padStart(2, '0');
519
  const seconds = String(duration.seconds()).padStart(2, '0');
520
  return `${hours}:${minutes}:${seconds}`;
521
}
522

523
console.log(formatTimer(3661000)); // "01:01:01"
524
console.log(formatTimer(7323000)); // "02:02:03"
525

526
// Sum multiple durations
527
function sumDurations(durations) {
528
  return durations.reduce((total, current) => {
529
    return total.add(current);
530
  }, moment.duration(0));
531
}
532

533
const durations = [
534
  moment.duration(1, "hour"),
535
  moment.duration(30, "minutes"),
536
  moment.duration(45, "minutes"),
537
  moment.duration(15, "minutes")
538
];
539

540
const total = sumDurations(durations);
541
console.log(total.asHours()); // 2.5 hours
542

543
// Parse complex duration strings
544
const isoDurations = [
545
  "PT1H30M",          // 1 hour 30 minutes
546
  "P1DT2H",           // 1 day 2 hours
547
  "P1Y2M3DT4H5M6S",   // Complex duration
548
  "PT45S"             // 45 seconds
549
];
550

551
isoDurations.forEach(iso => {
552
  const duration = moment.duration(iso);
553
  console.log(`${iso} -> ${duration.humanize()}`);
554
});
555
```
556

557
## Duration Constants and Thresholds
558

559
Moment.js uses internal thresholds to determine humanized output:
560

561
```javascript
562
// Default thresholds (approximate)
563
// ss: 44 seconds -> "a few seconds"
564
// s: 44 seconds -> "a minute" 
565
// m: 44 minutes -> "an hour"
566
// h: 21 hours -> "a day"
567
// d: 25 days -> "a month"
568
// M: 10 months -> "a year"
569
```
570

571
These can be configured globally using `moment.relativeTimeThreshold()` or per-call using the thresholds parameter in `humanize()`.