Enhanced-ms NPM

🤔 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

Install using your preferred package manager:

npm install enhanced-ms
pnpm add enhanced-ms
yarn add enhanced-ms

🧭 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
German	de
Russian	ru
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`	`Locale` \| `LanguageDefinition`	The language to use for parsing and formatting, if your preferred isn't supported, you can directly pass a language definition.	`en`
`formatOptions`	`FormatOptions` \| `FormatOptionsPreset`	The options to use for formatting.	see below

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
`extends`	`FormatOptionsPreset`	Extends the preset with the given options.	none
`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`	`ParseUnit[]`	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 0.