timecount
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.1 • Public • Published

    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

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

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

    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

    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:

    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:

    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", "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: 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 | 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:

    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.

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

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

    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.

    // 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").

    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("millisecond");
        // 1.234058872109
    }
    
    // Considering a total of 8 "laps":
    const totalProcessingTime = stopwatch.stop();
    
    totalProcessingTime.to("millisecond");
    // 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).

    Install

    npm i timecount

    DownloadsWeekly Downloads

    237

    Version

    1.1.1

    License

    MIT

    Unpacked Size

    497 kB

    Total Files

    21

    Last publish

    Collaborators

    • pjbatista