enhanced-ms

Convert human readable time-frame strings to milliseconds and back to strings
npm install enhanced-ms

🤔 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

npm install enhanced-ms
yarn add enhanced-ms
pnpm add enhanced-ms

const ms = require('enhanced-ms');
// OR
import 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.

import oms from 'ms';
import pms from 'pretty-ms';
import ems from 'enhanced-ms';

// Convert a single written time-frame to milliseconds
oms('1m'); // -> 60000
pms('1m'); // -> TypeError: Expected a finite number
ems('1m'); // -> 60000

// Convert multiple written time-frame measurements to milliseconds
oms('1m 30s'); // -> undefined
pms('1m 30s'); // -> TypeError: Expected a finite number
ems('1m 30s'); // -> 90000

// Convert milliseconds to time-frame with long option
oms(198349884, { long: true }); // -> '2 days'
pms(198349884, { verbose: true }); // -> '2 days 7 hours 5 minutes 49.8 seconds'
ems(198349884); // -> '2 days 7 hours 5 minutes and 49 seconds'

// Convert milliseconds to time-frame
oms(3456787654); // -> '40d'
pms(3456787654); // -> '40d 13m 7.6s'
ems(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.

function 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.

function 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.

function ms(language: LanguageKey): typeof ms;

function ms(options: Options): typeof ms;

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

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

TypeScript Interfaces

For LanguageKey, navigate to 🌐 Languages.

interface Options {
    /** Include input in the output. */
    includeMs?: boolean;
    /** Include sub input in the output. */
    includeSubMs?: boolean;
    /** Insert commas inbetween each unit. */
    insertCommas?: boolean;
    /** Round the result to the highest unit. */
    roundUp?: boolean;
    /** Use the short names of measurements. */
    shortFormat?: boolean;
}

🌀 Examples

Time-frame to Milliseconds

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

Milliseconds to Time-frame

ms(123456) === '2 minutes and 3 seconds';

ms(123456, { shortFormat: true }) === '2m 3s';
ms(123456, { roundUp: true }) === '2 minutes';
ms(123456, { includeMs: true }) === '2 minutes 3 seconds and 456 milliseconds';
ms(123.456, { includeSubMs: true }) === '123 milliseconds and 456 microseconds';

ms(123456, 'mi') === '2 meneti me te 3 hēkona';
ms(123456, 'mi', { roundUp: true }) === '2 meneti';
ms(123.456, 'mi', { includeSubMs: true }) === '123 manomano hēkona me te 456 moroiti hēkona';

Set Global Options

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

Set Global Language

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