1.0.2 • Published 6 years ago
@caltrop/ms.js v1.0.2
ms.js
A simple utility module which will help you implement time-based applications.
Table of Contents
Installation
$ npm install @caltrop/ms.jsBehaviour
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; // => 5500Input
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