Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/sindresorhus/pretty-ms

Convert milliseconds to a human readable string: `1337000000` → `15d 11h 23m 20s`
https://github.com/sindresorhus/pretty-ms

humanize milliseconds npm-package

Last synced: 20 days ago
JSON representation

Convert milliseconds to a human readable string: `1337000000` → `15d 11h 23m 20s`

Awesome Lists containing this project

README 

          
# pretty-ms



> Convert milliseconds to a human readable string: `1337000000` → `15d 11h 23m 20s`



*See [`parse-duration-ms`](https://github.com/sindresorhus/parse-duration-ms) for the inverse.*



## Install



```sh

npm install pretty-ms

```



## Usage



```js

import prettyMilliseconds from 'pretty-ms';



prettyMilliseconds(1337000000);

//=> '15d 11h 23m 20s'



prettyMilliseconds(1337000000n);

//=> '15d 11h 23m 20s'



prettyMilliseconds(1337);

//=> '1.3s'



prettyMilliseconds(133);

//=> '133ms'



// `compact` option

prettyMilliseconds(1337, {compact: true});

//=> '1s'



// `verbose` option

prettyMilliseconds(1335669000, {verbose: true});

//=> '15 days 11 hours 1 minute 9 seconds'



// `colonNotation` option

prettyMilliseconds(95500, {colonNotation: true});

//=> '1:35.5'



// `formatSubMilliseconds` option

prettyMilliseconds(100.400080, {formatSubMilliseconds: true})

//=> '100ms 400µs 80ns'



// `subSecondsAsDecimals` option

prettyMilliseconds(900, {subSecondsAsDecimals: true});

//=> '0.9s'



// Can be useful for time durations

prettyMilliseconds(new Date(2014, 0, 1, 10, 40) - new Date(2014, 0, 1, 10, 5))

//=> '35m'

```



## API



### prettyMilliseconds(milliseconds, options?)



#### milliseconds



Type: `number | bigint`



Milliseconds to humanize.



An integer (`number` or `bigint`) is exact at any size.



A fractional number is first rounded to 15 significant digits, the precision of a number, which removes float noise:



- `0.57 * 100_000` (`56999.99999999999`) is `57s`.

- `999.9999999999999` (16 digits) is `1s`, but `999.99999999999` (14 digits) is `999ms`.



From `1e14` milliseconds (about 3,170 years) up, no digits are left for the fraction, so the duration is rounded to whole milliseconds, and from `1e15` (about 31,700 years) up, to the nearest 10 milliseconds.



#### options



Type: `object`



##### secondsDecimalDigits



Type: `number`\

Default: `1`



Number of digits to appear after the seconds decimal point.



Digits are floored, not rounded, so the seconds never round up into the next step: `1999ms` is `1.9s`, and at `0` digits it is `1s`, never `2s`. The flooring applies to the duration after it is read (see `milliseconds` for how a fractional number is read).



##### millisecondsDecimalDigits



Type: `number`\

Default: `0`



Number of digits to appear after the milliseconds decimal point.



The milliseconds are rounded, not floored, but they never round up to `1000ms`, and a nonzero duration under a second never rounds down to `0ms`: `999.6ms` is `999ms`, and `0.2ms` is `1ms`. This does not apply with `formatSubMilliseconds`, which floors instead.



Useful in combination with [`process.hrtime()`](https://nodejs.org/api/process.html#process_process_hrtime_time).



##### keepDecimalsOnWholeSeconds



Type: `boolean`\

Default: `false`



Keep milliseconds on whole seconds: `13s` → `13.0s`.



Useful when you are showing a number of seconds spent on an operation and don't want the width of the output to change when hitting a whole number.



##### compact



Type: `boolean`\

Default: `false`



Only show the first unit: `1h 10m` → `1h`.



Also ensures that `millisecondsDecimalDigits` and `secondsDecimalDigits` are both set to `0`.



##### unitCount



Type: `number`\

Default: `Infinity`



Number of units to show. Setting `compact` to `true` overrides this option. It is ignored with `colonNotation`.



##### verbose



Type: `boolean`\

Default: `false`



Use full-length units: `5h 1m 45s` → `5 hours 1 minute 45 seconds`



##### separateMilliseconds



Type: `boolean`\

Default: `false`



Show milliseconds separately. This means they won't be included in the decimal part of the seconds.



##### formatSubMilliseconds



Type: `boolean`\

Default: `false`



Show microseconds and nanoseconds.



The values are floored to whole nanoseconds, so a duration under 1 nanosecond is `0ms`.



##### colonNotation



Type: `boolean`\

Default: `false`



Display time using colon notation: `5h 1m 45s` → `5:01:45`. Always shows time in at least minutes: `1s` → `0:01`, or in at least hours with `hideSeconds`: `1m` → `0:01`.



Useful when you want to display time without the time units, similar to a digital watch.



Setting `colonNotation` to `true` overrides the following options to `false`:

- `compact`

- `formatSubMilliseconds`

- `separateMilliseconds`

- `verbose`



Days after a year are padded to 3 digits to keep the width: `1:005:00:00:00`.



It also ignores `unitCount`, as dropping a field would change what the remaining fields mean: `1:01:01` would become `1:01`, which reads as 1 minute.



##### hideYear



Type: `boolean`\

Default: `false`



Hides the year and shows the hidden year additionally as days (365 per year): `1y 3d 5h 1m 45s` → `368d 5h 1m 45s`.



##### hideYearAndDays



Type: `boolean`\

Default: `false`



Hides the year and days and shows the hidden values additionally as hours: `1y 3d 5h 1m 45s` → `8837h 1m 45s`.



##### hideSeconds



Type: `boolean`\

Default: `false`



Hides the seconds: `1y 3d 5h 1m 45s` → `1y 3d 5h 1m`.



A duration under a minute has no coarser unit, so it keeps its seconds rather than showing nothing. With `colonNotation`, the hours are always shown, so the fields read as `h:mm`: `60000` → `0:01`, and `45000` → `0:00:45`.



##### subSecondsAsDecimals



Type: `boolean`\

Default: `false`



Show sub-second values as decimal seconds: `900ms` → `0.9s`.



Useful for progress indicators where you want consistent unit format to prevent flickering.



Also floored, so `999ms` is `0.9s`.



A duration too small for the seconds field to show, like `50ms` at the default `secondsDecimalDigits` of `1`, stays in milliseconds rather than showing as zero. With `compact`, the seconds have no decimals, so a duration under a second stays in milliseconds.



## FAQ



### Why doesn't this package support months?



This package formats time durations, not calendar dates. Months (28-31 days) have variable lengths, making duration calculations ambiguous. Years are shown as a fixed 365 days, so they do not account for leap years. Use the [`hideYear`](#hideyear) option to show days as the largest unit, since days are always exactly 24 hours. For calendar-based formatting, use [Temporal API](https://tc39.es/proposal-temporal/docs/) or a date library like [date-fns](https://github.com/date-fns/date-fns).



### Why doesn't the formatted difference of two values match the formatted values?



```js

prettyMilliseconds(3670);        //=> '3.6s'

prettyMilliseconds(5230);        //=> '5.2s'

prettyMilliseconds(5230 - 3670); //=> '1.5s' // Not '1.6s'

```



This is inherent to displaying rounded numbers, the same reason [rounded percentages don't always add up to 100%](https://help.surveymonkey.com/en/surveymonkey/analyze/percents-not-totaling/). Values are rounded independently, and rounding does not distribute over subtraction. `prettyMilliseconds(5230 - 3670)` correctly represents the true difference; it just won't always match subtracting the two rounded strings by eye.



## Related



- [pretty-ms-cli](https://github.com/sindresorhus/pretty-ms-cli) - CLI for this module

- [parse-ms](https://github.com/sindresorhus/parse-ms) - Parse milliseconds into an object

- [to-milliseconds](https://github.com/sindresorhus/to-milliseconds) - Convert an object of time properties to milliseconds

- [parse-duration-ms](https://github.com/sindresorhus/parse-duration-ms) - Parse duration strings to milliseconds

- [pretty-bytes](https://github.com/sindresorhus/pretty-bytes) - Convert bytes to a human readable string