Stopwatch

Stopwatch provides simple performance timing — measure elapsed time for operations, benchmark code blocks, and format timing results.

Package: io-oidis-commons

import { Stopwatch } from "@io-oidis-commons/.../Utils/Stopwatch.js";

Instance methods

Unlike most Oidis utilities, Stopwatch uses instance methods (not static). Create an instance with new Stopwatch().

Basic Usage

const sw = new Stopwatch();

sw.Start();
await someExpensiveOperation();
const elapsed = sw.Stop();

LogIt.Info(`Operation took ${elapsed} ms`);

Methods

Start / Stop / Restart / Reset

sw.Start() : void         // Start timing
sw.Stop() : number         // Stop and return elapsed milliseconds
sw.Restart() : number      // Stop, return elapsed time, and immediately start again
sw.Reset() : void          // Reset to initial state

Restart is useful for measuring sequential phases:

const sw = new Stopwatch();

sw.Start();
await phase1();
const phase1Time = sw.Restart();  // Returns phase 1 time, starts phase 2

await phase2();
const phase2Time = sw.Restart();  // Returns phase 2 time, starts phase 3

await phase3();
const phase3Time = sw.Stop();     // Returns phase 3 time

LogIt.Info(`Phase 1: ${phase1Time}ms, Phase 2: ${phase2Time}ms, Phase 3: ${phase3Time}ms`);

Elapsed Time

sw.ElapsedTime() : number   // Elapsed time in milliseconds (can be called while running)
sw.Elapsed() : Date          // Elapsed time as Date object

sw.Start();
// ... some work ...

// Check elapsed time without stopping
const soFar = sw.ElapsedTime();
LogIt.Info(`Still running, ${soFar}ms so far`);

// Continue running...
const total = sw.Stop();

Block Timing

sw.Block($block : () => void) : number

Execute a synchronous block and return its elapsed time:

const sw = new Stopwatch();

const elapsed = sw.Block(() => {
    // Synchronous code to measure
    const sorted = largeArray.sort();
    const filtered = sorted.filter(($item) => $item.IsActive);
});

LogIt.Info(`Sort + filter took ${elapsed}ms`);

Known issue

Block() has an inverted guard condition — it checks !ObjectValidator.IsFunction($block) before executing the block. In practice this means the block always executes (the guard is inverted), but the method works as expected for its intended use case. This is a known minor bug.

ToString

sw.ToString($prefix? : string, $htmlTag? : boolean) : string

Returns a formatted elapsed time string:

sw.Start();
await someOperation();
sw.Stop();

Echo.Println(sw.ToString());
// → "Elapsed time: 1234 ms"

Integration with Convert

For human-readable duration formatting, combine Stopwatch with Convert.TimeToLongString:

import { Convert } from "@io-oidis-commons/.../Utils/Convert.js";

const sw = new Stopwatch();
sw.Start();
await longRunningTask();
const elapsed = sw.Stop();

// Short format
LogIt.Info(`Completed in ${elapsed}ms`);

// Long format for display
const display = Convert.TimeToLongString(elapsed);
LogIt.Info(`Completed in ${display}`);
// → "Completed in 2 minutes, 15 seconds"

Complete Method Reference

Method	Description
Start()	Start the stopwatch
Stop()	Stop and return elapsed milliseconds
Restart()	Stop, return elapsed, restart
Reset()	Reset to initial state
ElapsedTime()	Current elapsed time in milliseconds
Elapsed()	Current elapsed time as Date
Block($fn)	Execute sync block and return elapsed time
ToString($prefix?, $htmlTag?)	Formatted "Elapsed time: X ms" string

---

See also: Utilities Overview | Convert | Echo | Logging