Skip to main content

​
Overview

Formatting is the process of converting a numeric duration (in milliseconds) into a human-readable string. Enhanced MS provides the formatMilliseconds() function and the ms() factory function to handle this conversion with extensive customization options.

​
How formatting works

The formatting process follows four main steps:

​
1. Parsing milliseconds

First, the formatter breaks down the total milliseconds into individual time units using parseMilliseconds() (~/workspace/source/src/format/helpers/parse-milliseconds.ts:28): 
parseMilliseconds(90061000)
// Returns: { day: 1, hour: 1, minute: 1, second: 1, ... }
Only units specified in includedUnits are calculated. Units not included receive a null value.

​
2. Filtering units

Next, the formatter filters out units based on your options (~/workspace/source/src/format/index.ts:49):
  • Units with null values are always removed
  • Units with 0 values are removed unless includeZero: true

​
3. Formatting individual units

Each remaining unit is formatted using formatUnit() (~/workspace/source/src/format/helpers/format-unit.ts:18): 
formatUnit(language.timeUnits.hour, 2, { useAbbreviations: false })
// Returns: "2 hours"

formatUnit(language.timeUnits.hour, 2, { useAbbreviations: true })
// Returns: "2h"
The formatter handles:
  • Pluralization (“1 hour” vs “2 hours”)
  • Abbreviations (“h” vs “hour”)
  • Minimum digits with zero padding
  • Language-specific unit names

​
4. Joining units

Finally, all formatted units are joined using the unitSeparator (~/workspace/source/src/format/index.ts:70): 
formatted.join(unitSeparator) // Default: " "
// Results in: "1 day 1 hour 1 minute"

​
Basic usage

import { formatMilliseconds, getLanguage } from 'enhanced-ms';

const duration = formatMilliseconds(90061000);
// "1 day 1 hour 1 minute 1 second"

const short = formatMilliseconds(90061000, getLanguage('en'), { 
  useAbbreviations: true 
});
// "1d 1h 1m 1s"

​
Format options

You can customize the output using various options defined in ~/workspace/source/src/format/helpers/resolve-options.ts:5:

​
useAbbreviations

Use short abbreviations instead of full unit names: 
ms(3600000, { useAbbreviations: true });
// "1h" instead of "1 hour"

​
unitLimit

Limit the number of units displayed: 
ms(90061000, { unitLimit: 2 });
// "1 day 1 hour" (stops after 2 units)
Setting unitLimit: -1 displays all available units (this is the default).

​
includeZero

Include units with zero values: 
ms(3661000, { 
  includeZero: true,
  includedUnits: ['day', 'hour', 'minute', 'second']
});
// "0 days 1 hour 1 minute 1 second"

​
includedUnits

Specify which time units to include: 
ms(90061000, { includedUnits: ['hour', 'minute'] });
// "25 hours 1 minute" (days are converted to hours)
Use includeMs: true as shorthand to add milliseconds, or includeSubMs: true to include microseconds and nanoseconds.

​
unitSeparator

Customize the separator between units: 
ms(3661000, { unitSeparator: ', ' });
// "1 hour, 1 minute, 1 second"

​
hideUnitNames

Display only the numeric values: 
ms(3661000, { hideUnitNames: true, unitSeparator: ':' });
// "1:1:1"

​
minimumDigits

Pad numbers with zeros: 
ms(3661000, { minimumDigits: 2, hideUnitNames: true, unitSeparator: ':' });
// "01:01:01"

​
Format presets

Enhanced MS includes built-in presets for common use cases (~/workspace/source/src/format/helpers/resolve-options.ts:160):

​
short

Abbreviated format with 2 units: 
ms(90061000, 'short');
// "1d 1h"
Equivalent to: 
{ useAbbreviations: true, unitLimit: 2 }

​
fullPrecision

Includes all precision levels down to nanoseconds: 
ms(1234567890, 'fullPrecision');
// "20 minutes 34 seconds 567 milliseconds 890 microseconds"
Equivalent to: 
{ includeMs: true, includeSubMs: true }

​
colonNotation

Clock-style format (HH:MM:SS): 
ms(3661000, 'colonNotation');
// "01:01:01"
Equivalent to: 
{
  hideUnitNames: true,
  unitLimit: 3,
  includeZero: true,
  includedUnits: ['hour', 'minute', 'second'],
  unitSeparator: ':',
  minimumDigits: 2
}
You can extend presets by using the extends option:
ms(3661000, { extends: 'short', unitLimit: 3 });

​
Edge cases

The formatter handles various edge cases:

​
Invalid input

Returns null for invalid durations: 
ms(0); // null (no duration)
ms(NaN); // throws TypeError
ms(Infinity); // throws TypeError
ms(-1000); // throws TypeError (negative values not allowed)

​
Empty results

If all units are filtered out, returns null: 
ms(500, { includedUnits: ['hour', 'minute'] });
// null (500ms doesn't reach these units)
  • Parsing - Convert strings back to milliseconds
  • Localization - Use different languages for formatting

Build docs developers (and LLMs) love

Get started for freeTalk to us