enhanced-ms

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

📦 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
Spanish	es
Dutch	nl
Italian	it
French	fr

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.

function ms(duration: string): number;

Changelog

4.1.0

Minor Changes

• 37840a3: Added language support for Dutch, French, Italian and Spanish

Patch Changes

• 10d9b89: Fixed handling of includeMs and includeSubMs options