Enhanced MS provides a simple API for converting between milliseconds and human-readable duration strings. This guide covers the basic usage patterns you’ll use most often.
The most common use case is converting milliseconds into readable duration strings. Simply pass a number to the ms function:
import ms from 'enhanced-ms';
ms(90061);
// "1 minute 30 seconds"
ms(90061000);
// "1 day 1 hour 1 minute 1 second"
null:
ms(0);
// null
ms(500);
// null (less than 1 second)
Parsing duration strings
You can also parse human-readable duration strings back into milliseconds. The parser accepts both full unit names and abbreviations:
Full unit names
Abbreviations
Mixed formats
ms('1 minute 30 seconds');
// 90000
ms('1 day 1 hour 1 minute 1 second');
// 90061000
ms('2 hours 45 minutes');
// 9900000
ms('1m 30s');
// 90000
ms('1d 1h 1m 1s');
// 90061000
ms('2h 45m');
// 9900000
ms('1 day 2h 30 minutes');
// 95400000
ms('1d 2 hours 30m');
// 95400000
ms('1 minute 30s');
// 90000
The parser is flexible and accepts mixed formats. You can combine full unit names with abbreviations in the same string.
Including milliseconds
By default, milliseconds aren’t included in formatted output. To include them, use the includeMs option:
ms(90061, { includeMs: true });
// "1 minute 30 seconds 61 milliseconds"
ms(1500, { includeMs: true });
// "1 second 500 milliseconds"
ms('1 minute 30 seconds 61 milliseconds');
// 90061
ms('1m 30s 61ms');
// 90061
ms(NaN);
// throws TypeError: Expected a finite number
ms(Infinity);
// throws TypeError: Expected a finite number
ms(-1000);
// throws TypeError: Expected a positive number
ms('invalid');
// 0
ms('no numbers here');
// 0
ms('');
// 0
When parsing fails to find valid duration units, it returns 0 instead of throwing an error. This makes it safe to use with user input.
Common use cases
Here are some practical examples of how you might use Enhanced MS in your applications:
Display uptime
const uptimeMs = process.uptime() * 1000;
const uptime = ms(uptimeMs);
console.log(`Server uptime: ${uptime}`);
// "Server uptime: 2 days 3 hours 15 minutes 42 seconds"
Parse configuration values
const config = {
timeout: '30 seconds',
cacheExpiry: '1 hour',
retryDelay: '5 minutes'
};
const timeoutMs = ms(config.timeout);
setTimeout(() => {
// Do something after timeout
}, timeoutMs);
const startTime = Date.now();
// ... do some work ...
const elapsed = Date.now() - startTime;
console.log(`Operation completed in ${ms(elapsed, { includeMs: true })}`);
// "Operation completed in 2 seconds 145 milliseconds"