pretty-ms

What is pretty-ms?

The pretty-ms npm package is a utility that converts milliseconds into a human-readable format. It is useful for displaying time durations in a more understandable way, such as in logging, performance monitoring, or user interfaces where time intervals need to be presented.

What are pretty-ms's main functionalities?

Convert milliseconds to human-readable string

This feature allows you to convert a numeric value representing milliseconds into a string that describes the duration in days, hours, minutes, and seconds.

const prettyMs = require('pretty-ms');
console.log(prettyMs(1337000000)); // '15d 11h 23m 20s'

Compact output for duration

With the 'compact' option, you can get a shorter string that only includes the largest time unit.

const prettyMs = require('pretty-ms');
console.log(prettyMs(1337000000, {compact: true})); // '15d'

Verbose output for duration

The 'verbose' option allows you to get a more descriptive string with full time unit names.

const prettyMs = require('pretty-ms');
console.log(prettyMs(1337000000, {verbose: true})); // '15 days 11 hours 23 minutes 20 seconds'

Include milliseconds in the output

This feature allows you to include milliseconds in the output with control over the number of decimal places.

const prettyMs = require('pretty-ms');
console.log(prettyMs(1337, {msDecimalDigits: 0})); // '1s 337ms'

Customize the number of decimal places

You can customize the number of decimal places for seconds to tailor the precision of the output.

const prettyMs = require('pretty-ms');
console.log(prettyMs(33333, {secDecimalDigits: 2})); // '33.33s'

Format as colon-separated time

The 'colonNotation' option formats the duration as a colon-separated time, similar to a digital clock display.

const prettyMs = require('pretty-ms');
console.log(prettyMs(9876543210, {colonNotation: true})); // '275:42:34'

Other packages similar to pretty-ms

moment-duration-format

This package extends Moment.js's duration object to format durations. It offers more customization in formatting durations but requires Moment.js as a dependency, which is a larger library compared to pretty-ms.

dayjs

Day.js is a lightweight date library that can also format durations with the duration plugin. It is similar in size to pretty-ms and provides additional date manipulation functionalities.

ms

The ms package is another simple utility to parse various time formats to milliseconds and vice versa. It is less feature-rich than pretty-ms, focusing mainly on conversion between string formats and milliseconds.

humanize-duration

Humanize-duration is a more feature-rich library for converting durations to human-readable strings. It supports multiple languages and has options for rounding, decimal places, and more. It is more comprehensive but also larger in size compared to pretty-ms.

README

pretty-ms

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

Install

npm install pretty-ms

Usage

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'

// 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.

options

Type: object

secondsDecimalDigits

Type: number
Default: 1

Number of digits to appear after the seconds decimal point.

millisecondsDecimalDigits

Type: number
Default: 0

Number of digits to appear after the milliseconds decimal point.

Useful in combination with process.hrtime().

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.

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.

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

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

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.

Related

• pretty-ms-cli - CLI for this module
• parse-ms - Parse milliseconds into an object
• to-milliseconds - Convert an object of time properties to milliseconds
• pretty-bytes - Convert bytes to a human readable string