Homo Sapiens Time

A simple time utility for Node.js

Human-style time descriptions to milliseconds and vice versa.

Quite a Simple One

Installation

npm install homo-sapiens-time
#or
yarn add homo-sapiens-time

Usage

Node

const hst = require("homo-sapiens-time")

HTML/JS

<script type="text/javascript" src="homo-sapiens-time.js"> </script>
<div id="message"> </div>
<script> 
    var x = msToTimeString(31557601000, {auto: false, units: ['seconds', 'year'], sortUnits: true}); 
    document.getElementById("message").innerHTML=x;
</script>

Description

There are three main functions.

msToTimeString
timeStringToMs
impreciseDurationAddedToNow

Defined time units are not as precise as calendar.

Unit	Milliseconds	Equivalent To
1 year	31557600000	365.25 days
1 month	2629800000	30.4375 days
1 week	604800000	7 days
1 day	86400000	24 hours
1 hour	3600000	60 minutes
1 minute	60000	60 seconds
1 seconds	1000	1000 ms
1 millisecond	1	1 ms

Time String Format

A single time part consists of the following format:

Positive or Negative Integer
Time Unit

There can only be one or zero spaces between each part. Time part can repeat as much as needed.

All available time units are:

Plural	Singular	Short	Maps To
years	year	y	'y'
months	month	mo	'mo'
weeks	week	w	'w'
days	day	d	'd'
hours	hour	h	'h'
minutes	minute	m	'm'
seconds	second	s	's'
milliseconds	millisecond	ms	'ms'

Plural, singular or short version of unit doesn't affect calculation, it just affects printed text. Integer value is not checked for plural or singular units either.

Example

"1year" = "1 year" = "1 y"
"2 year 3 months"
"31557601000 milliseconds"
"1year -6 month" = "6 months"

1. msToTimeString

Summary

This function takes ms and converts it to string that consists of given units.

This method has FIFO execution for units which means order of units matter. For example, if ms is given as the first value of units array then result will be same as ms parameter's value since ms in units will consume all value.

This function will detect any unit type typos given and will suggestions. For example: msToTimeString(31557601000, {auto: false, units: ['seconds', 'yeer']}) will produce

Error! Given unit `yeer` is not valid.
           Did you mean `year`?

String similarity function is taken from David from StackOverflow. Thanks David. 👍

Parameters

1.1 `ms`

Number containing time in milliseconds.

1.2 `opts`

opts = {
    auto: boolean,
    units: array of string,
    showEmpty: boolean,
    sortUnits: boolean
}

1.2.1 `opts.auto`

when set to true units will be overwritten as ['year','month','week','day','hour','minute','seconds','ms']

1.2.2 `opts.units`

any valid set of time units. Following are the available units:

const units = {
    years : 'y',
    year : 'y',
    y : 'y',

    months : 'mo',
    month : 'mo',
    mo : 'mo',

    weeks: 'w',
    week: 'w',
    w: 'w',

    days: 'd',
    day: 'd',
    d: 'd',

    hours: 'h',
    hour: 'h',
    h: 'h',

    minutes: 'm',
    minute: 'm',
    m: 'm',

    seconds : 's',
    second : 's',
    s : 's',

    milliseconds : 'ms',
    millisecond : 'ms',
    ms : 'ms'
}

Default value is ['year','month','week','day','hour','minute','second','ms'] if auto is true else ['hour','minute','second'].

1.2.3 `opts.showEmpty`

when set to true, if a unit with no value exists in the result, it will be written regardless.

Default value is false.

1.2.4 `opts.sortUnits`

Since order of opts.units matters, you can sort units to make longer time units (like year being longer than month) to have higher priority. Priority: y > mo > w > d > h > m > s > ms Units with higher priority will be closer to beginning of array.

Default value is false.

Return

Returns time string in Time String Format or null if any error occurred.

Examples

msToTimeString(31557601000, {auto: false, units: ['seconds', 'year'], sortUnits: true}) == '1 year 1 seconds'
msToTimeString(31557601001, {auto : true, units: [ 'year', 'month' ], showEmpty: false}) == '1 year 1 seconds 1 ms'
msToTimeString(74580249002, {auto: true}) == '2 year 4 month 1 week 3 day 22 hour 44 minute 9 second 2 ms'

2. timeStringToMs

Summary

Takes a time string similar to ones produced in msToTimeString and converts it to milliseconds.

Parameters

1. `str`:

String containing time in Time String Format.

Return

Returns ms converted from str.

Examples

timeStringToMs("1 year -6 month") == timeStringToMs("6 month")
timeStringToMs("2 years 4 months 10 days 22 hours 44 minutes 9 seconds 2 ms") == 74580249002
timeStringToMs("1 year 1 month 1 week 1 day 1 hour -1 hour -1 day -1mo -1y") == timeStringToMs("1 week")
timeStringToMs("1 week") == timeStringToMs("7 days")

3. impreciseDurationAddedToNow

Summary

This method adds given time string str to Date.now() value. Time string must be in Time String Format.

Internally calls timeStringToMs to convert str to ms.

Parameters

1. `str`:

String containing time in Time String Format.

Return

Millisecond value of Date.now() + timeStringToMs(str).

Notes

This library is perfect for durations. Since it is not precise I highly recommend being careful about using it for precise calendar operations.