Measures, converts and writes time using different units. Includes timers and stopwatches with nanosecond precision.


Keywords
nanosecond, stopwatch, time, time conversion, time counting, timer, count, nodejs
License
MIT
Install
npm install timecount@1.1.0

Documentation

Measures, converts and writes time using different units. Includes timers and stopwatches with nanosecond precision.

Features

Summary

Installation

This module can be installed with the node package manager of your choice:

  1. Using NPM:
    # As a dependency:
    npm install timecount --save
    
    # As a development dependency:
    npm install timecount --save-dev
  2. Using Yarn:
    # As a dependency:
    yarn add timecount
    
    # As a development dependency:
    yarn add timecount -D

Or download a release ready to be used on browsers:


Back to top | Skip to usage

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:

  1. EcmaScript 6:
    // --- 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"));
  2. Older EcmaScripts:
    // --- 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"));

Please consult the Full Upgrading Documentation for more information.


Back to top

Usage

Navigate: Time object | Writting 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:
    import { Time, TimeWriter } from "timecount";
    import { Locale } from "timecount/localization";
    import { BasicTimer, StopWatch, Timer } from "timecount/utils";
  • Older EcmaScripts:
    var timecount = require("timecount");
    
    // Sub-modules can be accessed directly through the main module
    timecount.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« | Writting 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.

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:

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:

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):

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

Writting time

Usage | Time object | »Writting 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:

const timeWriter = new TimeWriter();
const time = new Time(1000000000);

timeWriter.write(time);               // "1000000000 ns"
timeWriter.write(time, "second");     // "1 s"
timeWriter.write(time, "milisecond"); // "1000 ms"

It can also convert/write time values directly:

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:

let timeWriter = new TimeWriter({ verbose: true });

timeWriter.write(10, "second", "milisecond");
// "10000 miliseconds"

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: true
});

timeWriter.write(1, "second", "siderealSecond");
// "more or less 1.0027 sidereal seconds"

timeWriter.write(1, "second", "siderealSecond", { hideTimeUnit: true });
// "more or less 1.0027"

timeWriter.write(Infinity);
// "eternal nanoseconds"

timeWriter.write(NaN);
// "inexistent nanosecond"

// Method options override instance options:

timeWriter.write(1998, "year", { numericNotation: "roman" });
// "MCMXCVIII years"

timeWriter.write(1998.5, "year", { numericNotation: "roman-fractions" });
// "MCMXCVIIIS years"

There are many configurations available!. Oh, and in case it isn't clear by now, time units with no symbol will always be verbose:

timeWriter.write(new Time(1000000000), "shake");           // "100000000 shakes"
timeWriter.write(new Time(1000000000), "siderealSecond");  // "≈1.0027379155283682 sidereal seconds"

Back to usage | Back to top

Countdown

Usage | Time object | Writting time | »Countdown« | Translations | Timers | Stopwatches


The countdown method of time writers expands upon their writting 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:

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", "milisecond" or the constant TimeSegments.common.

// 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 | Writting time | Countdown | »Translations« | Timers | Stopwatches


For now, timecount is available in:

  • 🇺🇸 English (US)
  • 🇧🇷 Portuguese (Brazil)
  • 🇵🇹 Portuguese (Portugal)
  • 🇲🇽 Spanish (Mexico)
  • 🇪🇸 Spanish (Spain)

To translate the output of time writers, import the Locale class from "localization". It is a static class able to load settings from translation files.

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 | Writting 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...

const timer = new BasicTimer();

timer.start();

// [...] Operation that costs 100 miliseconds

const totalTime = timer.stop();

totalTime.to("milisecond");
// 101.0200193704

...and timers which do everything a basic timer does plus pausing.

// 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 | Writting time | Countdown | Translations | Timers | »Stopwatches«


Stopwatches do everything a timer do plus segment time (creating what is called a "lap").

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 ms

    const iterationTime = stopwatch.endLap();

    iterationTime.to("milisecond");
    // 1.234058872109
}

// Considering a total of 8 "laps":
const totalProcessingTime = stopwatch.stop();

totalProcessingTime.to("milisecond");
// 10.09183728197809584

For more examples, consult the API Documentation: stopwatch examples.


Back to usage | Back to top

Links


Back to top

License

Copyright © 2017-2018 Pedro José Batista

MIT License (see LICENSE for more information).