0
# Moment Duration Format
1

2
Moment Duration Format is a comprehensive plugin for Moment.js that adds powerful formatting capabilities to Moment Duration objects. It provides a template-based formatting system with extensive customization options including precision control, intelligent trimming, localization support, and flexible output formatting.
3

4
## Package Information
5

6
- **Package Name**: moment-duration-format
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install moment-duration-format`
10
- **Dependencies**: moment.js (peer dependency)
11

12
## Core Imports
13

14
CommonJS (Node.js):
15
```javascript
16
var moment = require("moment");
17
var momentDurationFormatSetup = require("moment-duration-format");
18
```
19

20
AMD:
21
```javascript
22
define(['moment'], factory);
23
```
24

25
Browser (global):
26
```html
27
<script src="path/to/moment.js"></script>
28
<script src="path/to/moment-duration-format.js"></script>
29
```
30

31
Manual setup for other moment packages:
32
```javascript
33
var moment = require("moment-timezone");
34
var momentDurationFormatSetup = require("moment-duration-format");
35
momentDurationFormatSetup(moment);
36
```
37

38
## Basic Usage
39

40
```javascript
41
var moment = require("moment");
42
require("moment-duration-format");
43

44
// Basic formatting with default template
45
moment.duration(123, "minutes").format();
46
// "2:03:00"
47

48
// Custom template formatting
49
moment.duration(3661, "seconds").format("h [hours], m [minutes], s [seconds]");
50
// "1 hour, 1 minute, 1 second"
51

52
// Formatting with precision
53
moment.duration(3780, "seconds").format("h [hours]", 1);
54
// "1.1 hours"
55

56
// Multiple duration formatting
57
moment.duration.format([
58
    moment.duration(1, "hour"),
59
    moment.duration(30, "minutes")
60
], "h:mm");
61
// ["1:00", "0:30"]
62
```
63

64
## Architecture
65

66
Moment Duration Format extends the Moment.js Duration prototype with formatting capabilities:
67

68
- **Template System**: Flexible template strings with moment tokens (y, M, w, d, h, m, s, S)
69
- **Format Functions**: Both single duration (`duration.fn.format`) and multi-duration (`duration.format`) formatting
70
- **Settings Engine**: Comprehensive configuration system with intelligent defaults
71
- **Trimming Logic**: Smart removal of zero-value tokens based on magnitude and user preferences
72
- **Localization**: Full i18n support with auto-pluralization and number formatting
73
- **Fallback System**: Robust fallback number formatting when native APIs are unavailable
74

75
## Capabilities
76

77
### Single Duration Formatting
78

79
Format individual moment duration objects with extensive customization options including templates, precision, and comprehensive settings.
80

81
```javascript { .api }
82
/**
83
 * Format a duration using template, precision, and settings
84
 * @param template - Format template string or function (optional)
85
 * @param precision - Number of decimal places or integer truncation (optional)
86
 * @param settings - Configuration object (optional)
87
 * @returns Formatted duration string
88
 */
89
moment.duration.fn.format([template] [, precision] [, settings]): string
90
```
91

92
[Duration Formatting](./duration-formatting.md)
93

94
### Multiple Duration Formatting
95

96
Format arrays of duration objects with coordinated output, ensuring consistent formatting across all durations in the set.
97

98
```javascript { .api }
99
/**
100
 * Format multiple durations with coordinated output
101
 * @param durationsArray - Array of moment duration objects  
102
 * @param template - Format template string or function (optional)
103
 * @param precision - Number of decimal places or integer truncation (optional)
104
 * @param settings - Configuration object (optional)
105
 * @returns Array of formatted duration strings
106
 */
107
moment.duration.format(durationsArray, [template] [, precision] [, settings]): string[]
108
```
109

110
[Multiple Duration Formatting](./multiple-duration-formatting.md)
111

112
### Template System
113

114
Powerful template engine with moment tokens, escape sequences, auto-localization markers, and dynamic template functions.
115

116
```javascript { .api }
117
// Template tokens: Y/y (years), M (months), W/w (weeks), D/d (days), 
118
// H/h (hours), m (minutes), s (seconds), S (milliseconds)
119
// Escape sequences: [text]
120
// Auto-localization: _ (short), __ (standard), _HMS_, _HM_, _MS_
121
```
122

123
[Template System](./template-system.md)
124

125
### Configuration Settings
126

127
Comprehensive settings system controlling trimming, precision, localization, value ranges, and output formatting.
128

129
```javascript { .api }
130
interface FormatSettings {
131
  template?: string | function;
132
  precision?: number;
133
  trim?: string | boolean | null;
134
  largest?: number | null;
135
  useSignificantDigits?: boolean;
136
  // ... 20+ additional configuration options
137
}
138
```
139

140
[Configuration Settings](./configuration-settings.md)
141

142
### Localization
143

144
Complete internationalization support with auto-pluralization, locale-specific number formatting, and extensible locale definitions.
145

146
```javascript { .api }
147
// Locale extensions for duration labels and pluralization
148
moment.updateLocale('en', {
149
  durationLabelsStandard: { /* ... */ },
150
  durationLabelsShort: { /* ... */ },
151
  durationTimeTemplates: { /* ... */ },
152
  durationPluralKey: function(token, integerValue, decimalValue) { /* ... */ }
153
});
154
```
155

156
[Localization](./localization.md)
157

158
## Setup and Installation
159

160
### Manual Setup Function
161

162
```javascript { .api }
163
/**
164
 * Setup function to initialize the plugin on a moment instance
165
 * @param moment - The moment instance to extend
166
 */
167
function momentDurationFormatSetup(moment: any): void;
168
```
169

170
The plugin automatically attempts to install on the global moment instance if available, but the setup function can be used to manually initialize on specific moment instances (useful with moment-timezone or other moment variants).
171

172
## Error Handling
173

174
Invalid durations are treated as having a value of 0 for formatting purposes:
175

176
```javascript
177
var invalidDuration = moment.duration(NaN, "second");
178
invalidDuration.isValid(); // false
179
invalidDuration.format(); // "0 seconds"
180
```
181

182
## Feature Detection
183

184
The plugin performs feature tests on initialization to determine the best number formatting method available:
185

186
- **Intl.NumberFormat**: Modern internationalization API with full locale support
187
- **Number.toLocaleString**: Fallback locale-aware number formatting  
188
- **Internal Formatter**: Plugin's own number formatting when native APIs are unavailable or buggy
189

190
The plugin automatically selects the most capable formatter and handles cross-browser compatibility transparently. Use `useToLocaleString: false` in settings to force the internal formatter.