pretty-ms
Convert milliseconds to human-readable time strings with customizable formatting options.
What is pretty-ms?
pretty-ms is a JavaScript utility library that converts millisecond values into human-readable time duration strings like '15d 11h 23m 20s'. It solves the problem of displaying raw millisecond timestamps in a user-friendly format for applications, logs, or command-line tools. The library offers multiple formatting options including compact, verbose, colon notation, and sub-millisecond precision.
JavaScript and Node.js developers who need to format time durations for display in applications, CLIs, logging systems, or user interfaces.
Developers choose pretty-ms for its simplicity, flexibility, and reliability—it provides numerous formatting options with sensible defaults, handles edge cases like sub-millisecond values, and avoids ambiguous calendar-based units like months and years.
Overview
Convert milliseconds to a human readable string: 1337000000 → 15d 11h 23m 20s
Use Cases
Best For
- Formatting elapsed time measurements in performance monitoring tools
- Displaying countdown timers or duration indicators in web applications
- Converting timestamps to readable formats in logging and debugging output
- Creating human-readable CLI tool output for time-based operations
- Formatting video or audio durations in media players
- Displaying progress indicators with consistent time unit formatting
Not Ideal For
- Applications that need to format calendar dates with months or years, such as '3 months ago' displays
- Projects requiring internationalization (i18n) or localization for time units in different languages
- Non-JavaScript environments where a native or cross-language solution is preferred
- Use cases that involve parsing time duration strings from user input, as it only handles formatting
Pros & Cons
Pros
Supports compact, verbose, colon notation, and sub-millisecond formats, as demonstrated in the README with examples like compact mode converting 1337ms to '1s'.
Can format microseconds and nanoseconds using the formatSubMilliseconds option, ideal for detailed performance measurements or scientific applications.
Excludes variable-length units like months and years to ensure reliable duration calculations, as explained in the FAQ to prevent misleading outputs.
Handles large millisecond values with BigInt, shown in usage examples like 1337000000n, making it suitable for long-duration formatting without precision loss.
Cons
Does not format months or years due to their variable lengths, limiting its use for date-related displays that require these units, as admitted in the FAQ.
Only formats milliseconds to strings; parsing duration strings back to milliseconds requires the parse-duration-ms package, adding extra dependencies and complexity.
Some options override others, such as colonNotation disabling compact and verbose modes, which can lead to unexpected behavior if not carefully managed, as noted in the API documentation.
Frequently Asked Questions
Related Projects
msTiny millisecond conversion utility
timeago.js:clock8: :hourglass: timeago.js is a tiny(2.0 kb) library used to format date with `*** time ago` statement.
fechaLightweight and simple JS date formatting and parsing
pretty-errorSee node.js errors with less clutter
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.