Skip to main content
The ms() function is the main entry point for Enhanced MS. It formats milliseconds into human-readable duration strings and parses duration strings back into milliseconds.

​
Import

import ms from 'enhanced-ms';
// or
import { ms } from 'enhanced-ms';

​
Overloads

The ms() function has multiple overloads to support different use cases:

​
Format milliseconds (default)

ms(milliseconds: number): string | null
Formats a duration from milliseconds to a human-readable string using default options.
​
milliseconds
number
required
The duration in milliseconds to format
​
return
string | null
The formatted duration string, or null if the duration is invalid
Example 
ms(90061000)
// Returns: "1 day 1 hour 1 minute"

​
Format with options

ms(milliseconds: number, options: FormatOptions): string | null
Formats a duration from milliseconds to a human-readable string with custom formatting options.
​
milliseconds
number
required
The duration in milliseconds to format
​
options
FormatOptions
required
The formatting options to customize the output. See FormatOptions for details.
​
return
string | null
The formatted duration string, or null if the duration is invalid
Examples 
ms(90061000, { useAbbreviations: true })
// Returns: "1d 1h 1m"

ms(90061000, { unitLimit: 1 })
// Returns: "1 day"

ms(90061000, { useAbbreviations: true, unitLimit: 1 })
// Returns: "1d"

​
Format with preset

ms(milliseconds: number, preset: FormatOptionsPreset): string | null
Formats a duration from milliseconds to a human-readable string using a formatting preset.
​
milliseconds
number
required
The duration in milliseconds to format
​
preset
'short' | 'fullPrecision' | 'colonNotation'
required
The formatting preset to use:
  • 'short': Abbreviated format (e.g., "1m 30s")
  • 'fullPrecision': Includes milliseconds, microseconds, and nanoseconds
  • 'colonNotation': Colon-separated format (e.g., "00:01:30")
​
return
string | null
The formatted duration string, or null if the duration is invalid
Examples 
ms(90061000, 'short')
// Returns: "1d 1h"

ms(90061000, 'colonNotation')
// Returns: "25:01:01"

​
Parse duration string

ms(duration: string): number
Parses a human-readable duration string into milliseconds.
​
duration
string
required
The duration string to parse (e.g., "2h 30m", "1 day, 5 hours")
​
return
number
The total duration in milliseconds, or 0 if the duration is invalid
Examples 
ms("1 day 1 hour 1 minute")
// Returns: 90060000

ms("1m 30s")
// Returns: 90000

​
Error handling

When formatting milliseconds, the function validates the input:
  • Throws TypeError if the value is not a finite number
  • Throws TypeError if the value is negative
  • Returns null if the duration cannot be formatted
When parsing strings:
  • Returns 0 if the string cannot be parsed or is invalid

​
Type definition

interface Ms {
  (milliseconds: number): string | null;
  (milliseconds: number, options: FormatOptions): string | null;
  (milliseconds: number, preset: FormatOptionsPreset): string | null;
  (duration: string): number;
}

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us