JSPM – timecount@1.0.0

Package Exports

timecount

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (timecount) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

This document contains information about the installation, configuration and usage of timecount, a NodeJS module capable of counting, measuring and converting time (from the Planck time to the yobisecond). It also packages timers and stopwatches with nanosecond precision*.

* Since we're talking nanoseconds, there is an obvious overhead between the time obtained by NodeJS process and the time it takes for objects to proccess data.

Installation

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

npm install timecount --save

-or-

yarn add timecount

Make sure to install a version >= 1.0.0 for a more concise experience (timecount now has 61 time units available for conversion, instead of 10 of the previous versions).

Upgrading (from versions pre-1.0.0)

The old versions of timecount (<= 0.1.3) are now obsolete.

If you had timecount installed before version 1.0.0, you may want to refer to the API Documentation: Upgrading.

Usage

Time in timecount is internally based on nanoseconds. This is done in order to better accomodate all time unit conversions: a Planck time (smallest time unit available) fits ~5x10³⁵ times inside a nanosecond, and a nanosecond fits ~10³³ times inside a yobisecond (largest time unit available).

The main module of timecount, which can be obtained by requiring/importing "timecount", contains time and time unit-related operations, such as converting, parsing and writing.

Measuring and converting time

Timecount packages an object called time writers, which can be use in many different ways:

import { Time, TimeWriter } from "timecount";

const timeWriter = new TimeWriter();

console.log(timeWriter.write(120, "second", "minute"));
// Result: 2 min

console.log(timeWriter.write(120, "second"));
// Result: 120 s

console.log(new Time(1));
// Result: 1 ns

console.log(new Time(200000000), "second", { verboseTimeUnit: true });
// Result: 0.2 second

console.log(timeWriter.write(1954, "year", {
  customPlural: "anno",
  numericNotation: "roman"
}));
// Result: MCMLIV anno

For more examples, consult the API Documentation: time writer examples.

Translations / Localization

For now, timecount is available in 🇺🇸 English (US), 🇧🇷 Portuguese (Brazil), 🇵🇹 Portuguese (Portugal), 🇪🇸 Spanish (Spain) and 🇲🇽 Spanish (Mexico).

To localize the output of time writers, import and set the Locale:

import { TimeWriter } from "timecount";
import { Locale } from "timecount/localization";

const timeWriter = new TimeWriter({ verboseTimeUnit: true });

timeWriter.write(10.5, "day");
// Result: 10.5 days

// Changing the language to Portuguese (Brazil)
Locale.set("pt-br");

timeWriter.write(10.5, "day");
// Result: 10,5 dias

If you wish to contribute with a new translation, please see Contributing: Translating.

Timers and stopwatches

These objects were the main focus of previous versions of timecount, however now they are part of the "timecount/utils" module.

Basic timers can measure the time passed between its start and stop, timers are able to pause and resume the time counting and stopwatches can split time during the count, creating "laps".

Example 1: Timer

import { Timer } from "timecount/utils";

// True can be passed to the timer to auto-start it
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 endTime = timer.stop();

console.log(endTime.nanoseconds);
// Result: 4006232032

console.log(endTime.to("second"));
// Result 4.006232032

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

Example 2: StopWatch

import { TimeWriter } from "timecount";
import { StopWatch } from "timecount/utils";

// Stopwatches can also be auto-started
const stopwatch = new StopWatch(true);
const timeWriter = new TimeWriter({ defaultTimeUnit: "milisecond" });

for (const iterationObject of iterator) {
  // [...] Do something here that takes ~1.2 ms
  const iterationTime = stopwatch.endLap();

  console.log(timeWriter.write(iterationTime));
  // Result: 1.2 miliseconds
}

// Considering a total of 8 laps:
const totalProcessingTime = stopwatch.stop();
console.log(timeWriter.write(totalProcessingTime));
// Result: 9.6 miliseconds

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

License

MIT License (see LICENSE for more information).

timecount