@dbpiper/timer
Simple module to time your code JavaScript or TypeScript code, to see how long
it took to run.
Installation Instructions
npm install @dbpiper/timer
Usage Instructions
import Timer, { FormattedDuration } from '@dbpiper/timer';
const timer = new Timer();
timer.start();
const formattedDuration = timer.stop();
console.log(formattedDuration);
API
Timer
The actual instance object that is used to access and use the timer.
The timer will be started automatically when an instance is created.
timer.start()
An alternative, more explicit, way to start the timer. This is automatically
called by the constructor, however if you want to do some tasks after creating
the Timer instance, but before starting the measurement then this can be used.
timer.stop()
return type: FormattedDuration
This stops the timer, and returns the amount of time that passed as a
FormattedDuration instance object.
FormattedDuration
The duration that passed, it is meant for easy displaying in scripts as the
main purpose of the module is to measure how much time a script took to run.
Thus, you would start the timer right before running it and then stop it when
done, printing the result to the screen or a log file or a message to an
external service.
formattedDuration.hours
return type: number
The amount of hours in the duration, note that since the largest unit supported
is hours everything larger will be here. So for example 2 days would be here
as 48 hours, since there is no "days" unit. The reason for this being the
largest unit supported is the fact that this module is intended to be used for
timing code.
If your code is running for days or weeks, this probably isn't the right module
to use, rather it is intended to be used for modules that run on the order
of minutes or maybe a few hours.
formattedDuration.minutes
return type: number
The amount of minutes in the duration.
formattedDuration.seconds
return type: number
The amount of seconds in the duration.
formattedDuration.milliseconds
return type: number
The smallest unit that @dbpiper/timer supports.
formattedDuration.toString()
Converts the duration to a human-readable string, it is usually used
implicitly like this:
console.log(formattedDuration);
const durationString = `${formattedDuration}`;
It will print each of the usual units described above, starting from
the largest one that is non-zero. Each unit will be joined with a comma and
space, except for the last one which will have "and" instead.
For example:
30 hours, 31 minutes and 26.4 seconds
No Milliseconds in output
You can observe from this example that there are no milliseconds in the
string! This is because I feel that adding them would not help to serve
the purpose of this module, which is to measure the amount of time that
code took to run and report it to a log or script.
This alterative with milliseconds:
30 hours, 31 minutes, 26 seconds and 400 milliseconds
Is about 40% longer, and contributes almost no useful information. People
still look at something like: 400 milliseconds
and say "hmm that's about
half a second". In other words, leaving the milliseconds out and making them
part of the seconds is not only shorter in your log, its actually easier for
you to read!
Some Milliseconds in output
You might be thinking, "I noticed earlier that I can access the milliseconds
explicitly with formattedDuration.milliseconds, why would you put that in there
if it isn't used?". The answer to this question is simple: it is used, but
only if the duration is exceptionally short. Specifically, if it is less than
a second.
For example a duration of 0.4 seconds or 400 milliseconds would not be
printed as 0.4 seconds
. This has the reverse problem from above.
That is, it is too terse making it harder to read and understand. It is much
easier to understand 400 milliseconds
rather than 0.4 seconds
, simply because
when you get to such a short time-frame it makes more sense to think in terms of
explicit milliseconds.
This is likely not going to come up too often, unless you are timing very short
segments of code. However, just note that in these cases you will get
milliseconds. In other words, you have them when you need them!
License
MIT Copyright
© David Piper