0
# Pretty MS
1

2
Pretty MS converts milliseconds to human-readable duration strings with extensive formatting options. It supports both regular numbers and BigInt values, offering features like compact display, verbose output, colon notation, decimal precision control, and sub-millisecond formatting.
3

4
## Package Information
5

6
- **Package Name**: pretty-ms
7
- **Package Type**: npm  
8
- **Language**: JavaScript (ES modules)
9
- **Installation**: `npm install pretty-ms`
10

11
## Core Imports
12

13
```javascript
14
import prettyMilliseconds from "pretty-ms";
15
```
16

17
CommonJS:
18

19
```javascript
20
const prettyMilliseconds = require("pretty-ms");
21
```
22

23
## Basic Usage
24

25
```javascript
26
import prettyMilliseconds from "pretty-ms";
27

28
// Basic formatting
29
prettyMilliseconds(1337000000);
30
//=> '15d 11h 23m 20s'
31

32
// BigInt support
33
prettyMilliseconds(1337000000n);
34
//=> '15d 11h 23m 20s'
35

36
// Small durations
37
prettyMilliseconds(1337);
38
//=> '1.3s'
39

40
prettyMilliseconds(133);
41
//=> '133ms'
42

43
// With options
44
prettyMilliseconds(1337, {compact: true});
45
//=> '1s'
46

47
prettyMilliseconds(95500, {colonNotation: true});
48
//=> '1:35.5'
49
```
50

51
## Capabilities
52

53
### Duration Formatting
54

55
Converts milliseconds to human-readable duration strings with comprehensive formatting options.
56

57
```javascript { .api }
58
/**
59
 * Convert milliseconds to a human readable string
60
 * @param milliseconds - Milliseconds to humanize (number or BigInt)
61
 * @param options - Optional configuration object
62
 * @returns Human-readable duration string
63
 * @throws TypeError when milliseconds is not a finite number or bigint
64
 */
65
function prettyMilliseconds(
66
  milliseconds: number | bigint,
67
  options?: Options
68
): string;
69
```
70

71
**Usage Examples:**
72

73
```javascript
74
// Time duration calculations
75
const duration = new Date(2014, 0, 1, 10, 40) - new Date(2014, 0, 1, 10, 5);
76
prettyMilliseconds(duration);
77
//=> '35m'
78

79
// Performance timing
80
console.time('operation');
81
// ... some operation
82
console.timeEnd('operation'); // logs time in ms
83
const elapsed = performance.now() - startTime;
84
prettyMilliseconds(elapsed);
85
//=> '245ms'
86

87
// BigInt for very large values
88
prettyMilliseconds(123456789012345n);
89
//=> '1425d 20h 40m 9s'
90
```
91

92
### Formatting Options
93

94
Control the output format and precision with comprehensive configuration options.
95

96
```javascript { .api }
97
interface Options {
98
  /** Number of digits after seconds decimal point (default: 1) */
99
  secondsDecimalDigits?: number;
100
  
101
  /** Number of digits after milliseconds decimal point (default: 0) */
102
  millisecondsDecimalDigits?: number;
103
  
104
  /** Keep decimals on whole seconds: '13s' → '13.0s' (default: false) */
105
  keepDecimalsOnWholeSeconds?: boolean;
106
  
107
  /** Show only first unit: '1h 10m' → '1h' (default: false) */
108
  compact?: boolean;
109
  
110
  /** Number of units to show (default: Infinity) */
111
  unitCount?: number;
112
  
113
  /** Use full unit names: '5h 1m 45s' → '5 hours 1 minute 45 seconds' (default: false) */
114
  verbose?: boolean;
115
  
116
  /** Show milliseconds separately from seconds (default: false) */
117
  separateMilliseconds?: boolean;
118
  
119
  /** Show microseconds and nanoseconds (default: false) */
120
  formatSubMilliseconds?: boolean;
121
  
122
  /** Digital watch style: '5h 1m 45s' → '5:01:45' (default: false) */
123
  colonNotation?: boolean;
124
  
125
  /** Hide year, show as additional days (default: false) */
126
  hideYear?: boolean;
127
  
128
  /** Hide year and days, show as additional hours (default: false) */  
129
  hideYearAndDays?: boolean;
130
  
131
  /** Hide seconds from output (default: false) */
132
  hideSeconds?: boolean;
133
}
134
```
135

136
**Option Examples:**
137

138
```javascript
139
// Compact format - only first unit
140
prettyMilliseconds(1337000, {compact: true});
141
//=> '22m'
142

143
// Verbose format - full unit names  
144
prettyMilliseconds(1335669000, {verbose: true});
145
//=> '15 days 11 hours 1 minute 9 seconds'
146

147
// Digital watch style
148
prettyMilliseconds(95500, {colonNotation: true});
149
//=> '1:35.5'
150

151
// Sub-millisecond precision
152
prettyMilliseconds(100.400080, {formatSubMilliseconds: true});
153
//=> '100ms 400µs 80ns'
154

155
// Limited unit count
156
prettyMilliseconds(1335669000, {unitCount: 2});
157
//=> '15d 11h'
158

159
// Custom decimal precision
160
prettyMilliseconds(1337, {secondsDecimalDigits: 3});
161
//=> '1.337s'
162

163
// Separate milliseconds from seconds
164
prettyMilliseconds(1337, {separateMilliseconds: true});
165
//=> '1s 337ms'
166

167
// Keep decimals on whole seconds
168
prettyMilliseconds(1000, {keepDecimalsOnWholeSeconds: true});
169
//=> '1.0s'
170

171
// Hide time units
172
prettyMilliseconds(365 * 24 * 60 * 60 * 1000 + 5000, {hideYear: true});
173
//=> '365d 5s'
174

175
prettyMilliseconds(365 * 24 * 60 * 60 * 1000 + 5000, {hideYearAndDays: true});
176
//=> '8760h 5s'
177

178
prettyMilliseconds(65000, {hideSeconds: true});
179
//=> '1m'
180
```
181

182
### Option Interactions
183

184
Some options override others for consistent output:
185

186
- Setting `colonNotation: true` disables `compact`, `formatSubMilliseconds`, `separateMilliseconds`, and `verbose`
187
- Setting `compact: true` forces `unitCount: 1` and sets both decimal digit options to 0
188
- `unitCount` is ignored when `compact: true`
189

190
### Error Handling
191

192
```javascript
193
// Throws TypeError for invalid input
194
prettyMilliseconds(NaN);        // TypeError: Expected a finite number or bigint
195
prettyMilliseconds(Infinity);   // TypeError: Expected a finite number or bigint  
196
prettyMilliseconds("1000");     // TypeError: Expected a finite number or bigint
197

198
// Handles edge cases gracefully
199
prettyMilliseconds(0);          //=> '0ms'
200
prettyMilliseconds(-1000);      //=> '-1s'
201
```