Enhanced MS

Convert milliseconds to human-readable duration strings and vice versa
npm install enhanced-ms

🤔 About

enhanced-ms is a flexible library for formatting milliseconds into human-readable durations and vice versa. It is an enhanced version of the popular ms with support for multiple inputs, localization, and more options.

🏓 Table of Contents

• 📦 Installation
• 🧭 Comparison
• 🚀 Usage
• 🌀 Examples

🧭 Comparison

As mentioned above, enhanced-ms is an enhanced version of the popular ms, so how does it compare?

Feature	enhanced-ms	ms	pretty-ms	itty-time
Convert Milliseconds to Duration	✅	✅	✅	✅
Convert Milliseconds to Multiple Duration Units	✅	❌	❌	❌
Convert Duration to Milliseconds	✅	✅	❌	✅
Convert Multiple Duration Units to Milliseconds	✅	❌	❌	❌
Localization Support	✅	❌	❌	❌

🌐 Languages

The currently supported languages include:

Language	Key
English (default)	en
Chinese (Simplified)	zh-CN
Spanish	es
French	fr
Portuguese	pt
Russian	ru
German	de
Italian	it
Polish	pl
Dutch	nl
Czech	cs
Māori	mi

You can help by adding support for more languages.

Make a pull request here.

🚀 Usage

Language and Default Options

The createMs function allows you to create a new instance of ms with a custom language and custom default options. This is useful if you want to use a different language or prefer different default options for parsing and formatting.

function createMs(options?: CreateMsOptions): typeof ms;

Option	Type	Description	Default
language	LanguageDefinition	The language to use for parsing and formatting.	none
formatOptions	FormatOptions | FormatOptionsPreset	The options to use for formatting.	see below

import fr from 'enhanced-ms/locales/fr';

const ms = createMs({
  language: fr,
  formatOptions: 'short',
});

ms(1000); // '1 seconde 111 millisecondes'

Formatting Milliseconds to Duration

The ms function allows you to format a number of milliseconds to a duration string. Passing a number of milliseconds will return a duration string, if the number is invalid, it will return null. The milliseconds overloads also allows you to pass a FormatOptions object or a FormatOptionsPreset to customise the formatting.

function ms(milliseconds: number): string | null;
function ms(milliseconds: number, options: FormatOptions): string | null;
function ms(milliseconds: number, preset: FormatOptionsPreset): string | null;

Option	Type	Description	Default
hideUnitNames	boolean	Hide unit names from the output.	false
useAbbreviations	boolean	Use abbreviations for unit names.	false
includeZero	boolean	Include units with the value 0 in the output.	false
includeMs	boolean	Include milliseconds in the output.	false
includeSubMs	boolean	Include sub-millisecond units in the output.	false
includedUnits	Time[]	Which units should be included in the output.	['year', 'day', 'hour', 'minute', 'second']
unitLimit	number	The maximum number of units to include in the output.	-1
unitSeparator	string	The separator to use between units.
minimumDigits	number	The minimum number of digits for a unit, aka will pad with zeroes.	0

Preset	Example
short	1m 30s
fullPrecision	10 seconds 100 milliseconds 100 microseconds 100 nanoseconds
colonNotation	00:01:30

Parsing Duration to Milliseconds

The ms function also allows you to parse a duration string (1 day, 3 weeks 4 days, etc). Passing a duration string will return a number of milliseconds, if no valid duration units are found, it will return null.

function ms(duration: string): number | null;