ms.js

A simple utility module which will help you implement time-based applications.

Table of Contents

• Installation
• Behaviour
• Input
  • Examples
  • String input Units
  • Options

Installation

$ npm install @caltrop/ms.js

Behaviour

The function will always return a Time Object.

For example:

const time = require('ms.js');
console.log(time(5200));

will return:

{
    eternity: 0,
    aeon: 0,
    century: 0,
    decade: 0,
    year: 0,
    day: 0,
    hour: 0,
    minute: 0,
    second: 5,
    millisecond: 200,
    microsecond: 0,
    nanosecond: 0,
    
    ms: 5200,
    str: '5 seconds and 200 milliseconds'
}

Invoking the toString function will always return the .str value. For example:

const time = require('ms.js');
console.log(`Shutting down in ${time(5200)}`); // => 'Shutting down in 5 seconds and 200 milliseconds'

Invoking the valueOf function will always return the .ms value. For example:

const time = require('ms.js');
time(5200) + 300; // => 5500

Input

Valid Input is always either a Number or a String!

Examples

const time = require('ms.js');

time(1000).str;                            // => '1 second'
time(1000 * 60).str;                       // => '1 minute'
time('2 hours').ms;                        // => 7200000
time('50y, 30h, 20m, 10s').str;            // => '5 decades, 1 day, 6 hours, 20 minutes and 10 seconds'
time('30 hours, 20 min10seconds5 0y').str; // => '5 decades, 1 day, 6 hours, 20 minutes and 10 seconds'
time(time('2 hours') + time(10000)).str;   // =>  '2 hours and 10 seconds'
time('-3 days').ms;                        // => -259200000
time('20').str;                            // => '20 minutes'
time(20).str;                              // => '20 milliseconds'
time(2.5).str;                             // => '2 milliseconds and 500 microseconds'
time('2.5 hours').str;                     // => '2 hours and 30 minutes'
time('minute').ms                          // => 60000
time(Infinity).str                         // => '1 eternity'

// you may also parse a Date Object
`it has been ${time(Date.now() - new Date(1567951242668))} since ms.js was released!`

(assuming that all relevant values will be shown, see: Options section)

String input Units

Unit Name | Definition | Aliases ---|---|--- Eternity | An Infinite amount of time | eternites Aeon | 3.1536e+19 ms or 1 billion years | ae,æ, aeons, eon, eons Millenium | 3.1536e+13 ms or 1,000 years | ml, milleniums, millennia Century | 3.1536e+12 ms or 100 years | l, cent, centurys, centuries Generation | 1103760000000 ms or 3 decades and 5 years | generations Decade | 3.1536e+11 ms or 10 years | dc, decades Megaminute | 60000000000 ms or 1,000,000 minutes or about 1 year and 329 days | megaminutes Year | 3.1536e+10 ms or 365 days | y, yr, yrs, years Season | 7884086400 ms or about 91 days and 6 hours | quarter, trimonth Month | 2628028800 ms or about 30 days and 10 hours | mo, mon, months Lunar Month | 2449440000 ms or about 28 days and 8 hours | lunarmonth, lunarmonths Fortnight | 1209600000 ms or 14 days | biweek, fortnights, biweeks Week | 604800000 ms or 7 days | w, weeks Day | 86400000 ms or 24 hours | d, days Hour | 3600000 ms or 60 minutes | h, hr, hrs, hours Moment | 90000 ms or 1 minute and 30 seconds | moments Minute | 60000 ms or 60 seconds | m, mn, min, mins, minutes Instant | 8000 ms or 8 seconds | in, instants Second | 1000 ms | s, sec, secs, seconds Millisecond | 1 ms | ms, msec, msecs, milliseconds Microsecond | 0.001 ms | µs, micro, micros, microsec, microsecs,microseconds Nanosecond | 0.000001 ms or 0.001 microseconds | ns, nano, nanos, nanosec, nenosecs,nanoseconds

Input is case insensitive!

If none of these are found directly, it will try to match the most similar unit instead (Assuming that strict mode is disabled, see: Options section)

Options

Options are parsed in an Object as the 2nd parameter to the function.

Option Name | Purpose | Default ---|---|--- verbose | Whether or not to show the entire Unit name or to use a shortened name | true relevant | How many relevant Units to display in the String | 2 strict | Whether or not to limit the use of incomplete input for String input | false

Examples:

const time = require('ms.js');

time(55555, {verbose: true}).str    // => '55 seconds and 555 milliseconds'
time(55555, {verbose: false}).str   // => '55s, 555ms'

time(55555555, {relevant: 2}).str   // => '15 hours and 25 minutes'
time(55555555, {relevant: 3}).str   // => '15 hours, 25 minutes and 55 seconds'
time(55555555, {relevant: 4}).str   // => '15 hours, 25 minutes, 55 seconds and 555 milliseconds'

time('minute', {strict: false}).str // => '1 minute'
time('1', {strict: false}).str      // => '1 minute'
time('1minu', {strict: false}).str  // => '1 minute'
time('minute', {strict: true}).str  //TypeError: Cannot read property 'str' of undefined
time('1', {strict: true}).str       //TypeError: Cannot read property 'str' of undefined
time('1minu', {strict: true}).str   //TypeError: Cannot read property 'str' of undefined


time('66666', {strict: false, verbose: false, relevant: 99}) // => 46d, 7h, 6m