to-time

Utility for converting textual time periods to time units (milliseconds, seconds, minutes, hours, etc..).

Due to the lack of precision in floating point numbers arithmetic and the need of keeping the results precise the utility is using the bignumber.js library for arithmetic operations on numbers.

Install

npm install to-time

Node.js 20.19+ is required (see engines in package.json).

Importing

The package is built as dual ESM / CommonJS and defines an exports map in package.json. Use the package name to-time only—tools resolve it to dist/index.mjs (ESM) or dist/index.cjs (CJS). TypeScript types are exposed through the same entry.

Node.js and bundlers (ESM)

import toTime from 'to-time';

Use this in projects with "type": "module" in package.json, in .mjs files, or when your bundler targets ESM.

Node.js and bundlers (CommonJS)

const toTime = require('to-time');

TypeScript

import toTime from 'to-time';

The same import works with moduleResolution set to node16, nodenext, or bundler (recommended for modern tooling).

Browser (UMD)

For a plain script tag without a bundler, use the UMD build under lib/. BigNumber.js is bundled into these files; you do not need a separate script for it.

<script src="node_modules/to-time/lib/to-time.min.js"></script>
<!-- exposes global: window.toTime -->

A non-minified file is also published: node_modules/to-time/lib/to-time.js.

Usage

Converting from textual time period to time units

toTime('1 hour').seconds(); //3600
//same as:
toTime('1h').seconds(); //3600

toTime('1 Year 365 Days 4 Hours').hours(); //17524
//same as:
toTime('1y 365d 4h').hours(); //17524

Useful for usage in methods such as setInterval and setTimeout which consume the second argument in milliseconds, it is much clearer for someone who will read the code.

//Instead of using 43200000 milliseconds (equivalent to 12 hours) we can do the following
setInterval(() => {
  //Do something here
}, toTime('12h').ms());

//Instead of using 5400000 milliseconds (equivalent to 1.5 hour)
setTimeout(() => {
  //Do something here
}, toTime.fromHours(1.5).ms());

Allowed suffixes (all case-insensetive)

• Year, Years, Y
• Week, Weeks, W
• Day, Days, D
• Hour, Hours, H
• Minute, Minutes, M
• Second, Seconds, S
• Millisecond, Milliseconds, MS

Initializing using factory methods

It is also possible to create a TimeFrame instance by calling the static factory methods. The result will be a TimeFrame object similar to the one that is created by invoking the function with a textual time period.

toTime.fromHours(4).addMinutes(30).hours(); //4.5
toTime.fromYears(4).addWeeks(4).days(); //1488

Available factory methods

• fromMilliseconds
• fromSeconds
• fromMinutes
• fromHours
• fromDays
• fromWeeks
• fromYears

Appenders methods

It is possible to add additional units to the TimeFrame object by invoking one of the appender methods on the returned instance:

toTime('0.5 hour').addMinutes(30).seconds(); //3600
toTime.fromHours(2).addMinutes(30).minutes(); //150

Available appenders:

• addMilliseconds
• addSeconds
• addMinutes
• addHours
• addDays
• addWeeks
• addYears

Getters methods

The getter methods are used to get the value of the TimeFrame object in a specific time unit.

• milliseconds : Number
• ms (alias to milliseconds)
• minutes : Number
• hours : Number
• days : Number
• weeks : Number
• years : Number
• humanize : String

Converting the TimeFrame object to human readable format

It is also possible to use to-time in order to convert time units into human readable format. Example:

const frame = toTime.fromMilliseconds(500005050505005);
frame.humanize(); //15855 Years, 2 Weeks, 6 Days, 11 Hours, 48 Minutes, 25 Seconds, 5 Milliseconds

Contributing

Running tests

• Make sure to write tests, run new & existing tests using:

  npm run test

• Check for source code & tests code styling by running eslint:

  npm run lint

• If tests are passing and eslint doesn't return any error -> Create pull request

License

MIT