🤔 About

enhanced-ms is a simple, zero dependencies, module that lets you easily convert milliseconds to a readable format and vice versa. It is an enhanced version of the original ms module, with support for mutliple time-frames, localisation and operators!

Features

• Localisation support
• Convert from milliseconds to time-frame
• Convert from time-frame to milliseconds
• Operator in time-frame support
• Customisable outputs

📩 Installation

1npm install enhanced-ms
2yarn add enhanced-ms
3pnpm add enhanced-ms

1const ms = require('enhanced-ms');
2// OR
3import ms from 'enhanced-ms';

🧭 Comparison

As mentioned previously, enhanced-ms is inspired by the original ms module, so how does it compare to it?

pretty-ms is another conversion module.

1import oms from 'ms';
2import pms from 'pretty-ms';
3import ems from 'enhanced-ms';
4
5// Convert a single written time-frame to milliseconds
6oms('1m'); // -> 60000
7pms('1m'); // -> TypeError: Expected a finite number
8ems('1m'); // -> 60000
9
10// Convert multiple written time-frame measurements to milliseconds
11oms('1m 30s'); // -> undefined
12pms('1m 30s'); // -> TypeError: Expected a finite number
13ems('1m 30s'); // -> 90000
14
15// Convert milliseconds to time-frame with long option
16oms(198349884, { long: true }); // -> '2 days'
17pms(198349884, { verbose: true }); // -> '2 days 7 hours 5 minutes 49.8 seconds'
18ems(198349884); // -> '2 days 7 hours 5 minutes and 49 seconds'
19
20// Convert milliseconds to time-frame
21oms(3456787654); // -> '40d'
22pms(3456787654); // -> '40d 13m 7.6s'
23ems(3456787654, { shortFormat: true }); // -> '40d 13m 7s'

🌐 Languages

The currently supported languages include:

Language	Key
English	en
German	de
Māori	mi

You can help by adding support for more languages.

Make a pull request here.

🍕 API

Conversion

When the first parameter is a string, the module will parse it and convert it into a time-frame in milliseconds.

If no time units were found within the string, null will be returned.

1function ms(input: string, value2?: LanguageKey | Options, options?: Options): number | null;

However when the first parameter is a number it will be converted into a time-frame string.

If no time units were outputted (for example then the inputted number is less than 1000 and includeMs is false), null will be returned.

1function ms(input: number, value2?: LanguageKey | Options, options?: Options): string | null;

For both of the above overloads, the second parameter can either be the language key, or the options object. The third and final parameter is only ever used if a language key is supplied.

Globals

If you prefer that the results always include in a different language, or if you want milliseconds to always be included, this is for you.

The following will overwrite the modules defaults, you can find some examples further down.

1function ms(language: LanguageKey): typeof ms;

1function ms(options: Options): typeof ms;

Both of these will return the ms function, which will allow you to do:

1const ms = require('enhanced-ms')('en')({ roundUp: true });

TypeScript Interfaces

For LanguageKey, navigate to 🌐 Languages.

1interface Options {
2    /** Include input in the output. */
3    includeMs?: boolean;
4    /** Include sub input in the output. */
5    includeSubMs?: boolean;
6    /** Insert commas inbetween each unit. */
7    insertCommas?: boolean;
8    /** Round the result to the highest unit. */
9    roundUp?: boolean;
10    /** Use the short names of measurements. */
11    shortFormat?: boolean;
12}

🌀 Examples

Time-frame to Milliseconds

1ms('1 day') === 86400000;
2ms('3m 34s') === 214000;
3ms(ms('1d - 4h')) === '20 hours';
4ms(ms('7d / 7')) === '1 day';
5ms('1 meneti', 'mi') === 60000;

Milliseconds to Time-frame

1ms(123456) === '2 minutes and 3 seconds';
2
3ms(123456, { shortFormat: true }) === '2m 3s';
4ms(123456, { roundUp: true }) === '2 minutes';
5ms(123456, { includeMs: true }) === '2 minutes 3 seconds and 456 milliseconds';
6ms(123.456, { includeSubMs: true }) === '123 milliseconds and 456 microseconds';
7
8ms(123456, 'mi') === '2 meneti me te 3 hēkona';
9ms(123456, 'mi', { roundUp: true }) === '2 meneti';
10ms(123.456, 'mi', { includeSubMs: true }) === '123 manomano hēkona me te 456 moroiti hēkona';

Set Global Options

1ms(1234567) === '20 minutes and 34 seconds';
2ms({ roundUp: true }) instanceof Function;
3ms(1234567) === '21 minutes';

Set Global Language

1ms(1000) === '1 second';
2ms('mi') instanceof Function;
3ms(1000) === '1 hēkona';