Measures, converts and writes time using different units. Includes timers and stopwatches with nanosecond precision.
Coming soon (version 2)
- 🏗 Built from scratch
- 👀 Simpler codebase
- 📚 Improved documentation
- ⏳ 101 units of time
- ⚡ Much faster than v1
Features
- Encapsulated time objects
- 71 time units available for conversion (from the Planck time to the yobisecond)
- Timers and stopwatches with nanosecond precision (and the minimum possible overhead)
Summary
- [Time object](#time-object)- [Writing time](#writing-time)- [Countdown](#writing-time)- [Translations](#translations)- [Timers](#timers)- [StopWatches](#stopwatches)Installation
This module can be installed with the node package manager of your choice:- Using NPM:
```bash# As a dependency:npm install timecount --save# As a development dependency:npm install timecount --save-dev```- Using Yarn:
```bash# As a dependency:yarn add timecount# As a development dependency:yarn add timecount -D```- Latest Release: timecount-1.1.1
- All releases: https://github.com/pjbatista/timecount/releases
Upgrading
Old versions of timecount (<= 0.1.3) are now obsolete. The code is much less cluttered now, which means less overhead, which means more precise timers and stopwatches. Here is a simple example on how to upgrade:- EcmaScript 6
```javascript// --- OLD ---import { Timer } from "timecount";const timer = new Timer({ autoStart: true });// Do your stuff...const time = timer.end();console.log(time.toSeconds());// --- NEW ---import { Timer } from "timecount/utils";const timer = new Timer(true);// Do your stuff...const time = timer.stop();console.log(time.to("second"));```- Older EcmaScripts:
```javascript// --- OLD ---var timecount = require("timecount");var timer = new timecount.Timer({ autoStart: true });// Do your stuff...var time = timer.end();console.log(time.toSeconds());// --- NEW ---var timecount = require("timecount");var timer = new timecount.utils.Timer(true);// Do your stuff...var time = timer.stop();console.log(time.to("second"));```Usage
Navigate:Time object | Writing time | Countdown | Translations | Timers | Stopwatches
---
Time in timecount is internally based on nanoseconds, in order to better accomodate the precision on most orders of magnitude.
💡 A Planck time (smallest unit available) fits ~5x10³⁵ times inside a nanosecond and a nanosecond fits ~10³³ times inside a yobisecond (largest unit available).After installing, it will be readily available to be imported:
- EcmaScript 6:
```javascriptimport { Time, TimeWriter } from "timecount";import { Locale } from "timecount/localization";import { BasicTimer, StopWatch, Timer } from "timecount/utils";```- Older EcmaScripts:
```javascriptvar timecount = require("timecount");// Sub-modules can be accessed directly through the main moduletimecount.Locale.set("pt");var stopwatch = new timecount.utils.StopWatch();```⚠ From now on, unless stated otherwise, examples on this document will assume the use of EcmaScript 6 or equivalent.
Time object
Usage | »Time object« | Writing time | Countdown | Translations | Timers | Stopwatches
---
Time objects are nanosecond-based encapsulations of time values used throughout most of timecount.
More examples, including all time units available can be found at API Documentation: Time.
```javascript
let time = new Time(1);
// Represents 1 nanosecond
time.value; // 1 (number)
time.bigValue; // 1 (big decimal)
```
Time constructors are versatile and accept numbers, strings (with numeric values), other time objects and big decimals:
```javascript
time = new Time(50); // 50 ns
time = new Time("5.425e+4"); // 54250 ns
time = new Time(time.subtract(1, "microsecond")); // 53250 ns
time = new Time(new Decimal(150)); // 150 ns
// Times are always absolute (no negatives):
time = new Time(-50); // 50 ns
time = new Time("-1.5e+10"); // 15009000000 ns
```
To convert to or from any of the available time units:
```javascript
const time = Time.from(1, "second");
// 1 second = 1000000000 nanoseconds
time.to("minute"); // 0.01666666666666666667
time.to("second"); // 1
time.to("microsecond"); // 1000000
time.to({ factor: 2 }); // 500000000
time.value; // 1000000000
Time.from(time.to("second"), "second"); // 1000000000
```
Basic arithmetics (including conversions):
```javascript
let time = new Time(10); // 10 ns
time.add(10); // 20 ns
time.add(10, "second"); // 1000000000010 ns
time.add(Time.from(1, "second")); // 1000000000010 ns
time = new Time(0.3); // 0.3 ns
time.subtract(0.1); // 0.2 ns
time.subtract("0.1"); // 0.2 ns
time.subtract(1, "second"); // 999999999.7 ns
time.subtract(new Time(1)); // 0.7 ns
```
---
Back to usage | Back to top
Writing time
Usage | Time object | »Writing time« | Countdown | Translations | Timers | Stopwatches
Time writers are able to synthesize strings describing time values using SI symbols, human-readable names, translations, different numeric notations and much more.
More examples, including all syntaxes of countdown and write are available at API Documentation: TimeWriter and all possible configurations at API Documentation: TimeWriterSettings.
---
First, there are many "overloads" to the write method:
```javascript
const timeWriter = new TimeWriter();
const time = new Time(1000000000);
timeWriter.write(time); // "1000000000 ns"
timeWriter.write(time, "second"); // "1 s"
timeWriter.write(time, "millisecond"); // "1000 ms"
```
It can also convert/write time values directly:
```javascript
timeWriter.write(1); // "1 ns"
timeWriter.write("1"); // "1 ns"
timeWriter.write("1e+0"); // "1 ns"
timeWriter.write(1, "second"); // "1 s"
timeWriter.write(1e0, "second", "nanosecond"); // "1000000000 ns"
timeWriter.write(1, "second", "minute"); // "0.01666666666666666667 min"
timeWriter.write("100", "svedberg"); // "100 Sv"
timeWriter.write("1e2", "year", "year"); // "100 y"
```
And there also many ways to configure it:
```javascript
let timeWriter = new TimeWriter({ verbose: true });
timeWriter.write(10, "second", "millisecond");
// "10000 milliseconds"
timeWriter.write("10", "second", "kibisecond", { numericNotation: "scientific" });
// "1.024e+7 kibiseconds"
timeWriter.write(10, "second", "nanosecond", { thousandsSeparator: "," });
// "1,000,000,000 ns"
timeWriter = new TimeWriter({
decimalDigits: 4,termApproximately: "more or less",termInfinite: "eternal",termNaN: "inexistent",verbose: trueCountdown
Usage | Time object | Writing time | »Countdown« | Translations | Timers | Stopwatches
---
The countdown method of time writers expands upon their writing abilities, creating an interface to represent a time segmenting its remaining fractions in various orders of magnitude (time units).
This helps the expression of a more comprehensible information, i.e. help a human user understand a time length using common time unit divisions:
```javascript
const time = Time.from(5623098, "second");
// What does 5623098 seconds reaaaally mean?
timeWriter.countdown(time, { verbose: true });
// 2 months, 4 days, 5 hours, 58 minutes, 18 seconds
```
By default, the segments are: "year", "month", "day", "hour", "minute", "second", "millisecond" or the constant TimeSegments.common.
```javascript
// There are a few constants aimed at common operations
import { TimeSegments } from "timecount";
const time = Time.from(5623098, "second");
timeWriter.countdown(time);
// 2 m, 4 d, 5 h, 58 min, 18 s
timeWriter.countdown(time, TimeSegments.common);
// 2 m, 4 d, 5 h, 58 min, 18 s
timeWriter.countdown(time, { hideZeroSegments: false }, TimeSegments.common);
// 0 y, 2 m, 4 d, 5 h, 58 min, 18 s
timeWriter.countdown(time, TimeSegments.baseTen);
// 5 Ms, 623 Ks, 98 s
timeWriter.countdown(time, TimeSegments.binary);
// 5 Mis, 371 Kis, 314 s
timeWriter.countdown(Time.from(10, "planckTime").add(10, "yobisecond"), TimeSegments.extremes);
// 10 Yis, 10 tₚ
timeWriter.countdown(Time.from(10, "planckTime").add(10, "yobisecond"), { hideZeroSegments: false }, TimeSegments.extremes);
// 10 Yis, 0 ns, 10 tₚ
```
Also, there are some configurations specific to countdowns.
---
Back to usage | Back to top
Translations
Usage | Time object | Writing time | Countdown | »Translations« | Timers | Stopwatches
---
For now, timecount is available in:
- 🇺🇸 English (US)
- 🇧🇷 Portuguese (Brazil)
- 🇵🇹 Portuguese (Portugal)
- 🇲🇽 Spanish (Mexico)
- 🇪🇸 Spanish (Spain)
"localization". It is a static class able to load settings from translation files.
```javascript
import { TimeWriter } from "timecount";
import { Locale } from "timecount/localization";
const timeWriter = new TimeWriter({ verbose: true });
timeWriter.write(10.5, "biennium");
// "10.5 biennia"
timeWriter.write(Infinity, "tropicalYear");
// "approximately infinite tropical years"
// Changing the language to Portuguese, without setting the region
// Timecount will choose the most populated region variation (in this case Brazilian Portuguese)
Locale.set("pt");
timeWriter.write(10.5, "biennium");
// "10,5 biênios"
timeWriter.write(Infinity, "tropicalYear");
// "aproximadamente infinitos anos tropicais"
// Changing the language to a regionalized Portuguese
// In this case, Portuguese (Portugal)
Locale.set("pt-pt");
timeWriter.write(10.5, "biennium");
// "10,5 biénios"
timeWriter.write(Infinity, "tropicalYear");
// "cerca de infinitos anos tropicais"
```
---
Back to usage | Back to top
Timecount needs your help! Please contribute with a translation: see Contributing: Translating.
Timers
Usage | Time object | Writing time | Countdown | Translations | »Timers« | Stopwatches
---
These objects were the main focus of previous versions of timecount, however now they are part of the "timecount/utils" module.
There are the basic timers — capable of counting time during runtime...
```javascript
const timer = new BasicTimer();
timer.start();
// ... Operation that costs 100 milliseconds
const totalTime = timer.stop();
totalTime.to("millisecond");
// 101.0200193704
```
...and timers which do everything a basic timer does plus pausing.
```javascript
// True can be passed to any type of timer to auto-start
const timer = new Timer(true);
// ... Operation that costs ~1.5 seconds (total 1.5 s)
timer.pause();
// ... Another operation that costs ~2 seconds (not counted)
timer.resume();
// ... Another operation that costs ~2.5 seconds (total 4 s)
const totalTime = timer.stop();
totalTime.value;
// 4006232032
totalTime.to("second");
// 4.006232032
```
For more examples, consult the API Documentation: timer examples.
---
Back to usage | Back to top
StopWatches
Usage | Time object | Writing time | Countdown | Translations | Timers | »Stopwatches«
---
Stopwatches do everything a timer do plus segment time (creating what is called a "lap").
```javascript
import { StopWatch } from "timecount/utils";
// Stopwatches can also be auto-started
const stopwatch = new StopWatch(true);
for (const iterationObject of iterator) {
// [...] Do something that takes ~1.2 msconst iterationTime = stopwatch.endLap();iterationTime.to("millisecond");// 1.234058872109