Class: ClockSmith¶

Manager for multiple named timers.

Each timer is identified by a string label. Timers can run concurrently and are stored internally until cleared.

Examples¶

Basic usage with two concurrent timers:

TypeScript

const smith = new ClockSmith();
smith.start("fetchData");
smith.start("parseData");
smith.stop("fetchData");
console.log(`fetchData: ${smith.elapsed("fetchData")}ms`);
smith.stop("parseData");
console.log(`parseData: ${smith.elapsed("parseData")}ms`);

Export all results as a Map:

TypeScript

const smith = new ClockSmith();
smith.start("step1");
smith.stop("step1");
const data = smith.toMap();
// Map { "label" => ["step1"], "started" => [...], "stopped" => [...], "elapsed_ms" => [42] }

Since¶

1.0.0

Constructors¶

Constructor¶

new ClockSmith(options?): ClockSmith

Create a new timer manager.

Parameters¶

options?¶

ClockSmithOptions = {}

Optional configuration

Returns¶

ClockSmith

New ClockSmith instance

Example¶

TypeScript

const smith = new ClockSmith();
const smith = new ClockSmith({ name: "myApp" });

Since¶

1.0.0

Gears¶

startWithLog()¶

startWithLog(label, externalLogger?, logStart?): void

Start a named timer and optionally log the start event.

Pass any logger object with an info(message) method as externalLogger. The start message is only logged when logStart is true.

Parameters¶

label¶

string

Timer label

externalLogger?¶

any

Optional logger with an info method

logStart?¶

boolean = false

Whether to log "Timer started: <label>" (default: false)

Returns¶

void

Example¶

TypeScript

const smith = new ClockSmith();

smith.startWithLog("api-call", console, true);
// console.info: "Timer started: api-call"

// ... perform operation ...
smith.stopWithLog("api-call", console);
// console.info: "api-call: 523ms"

Since¶

0.20.0

stopWithLog()¶

stopWithLog(label, externalLogger?): void

Stop a named timer and log the elapsed time.

Calls stop() and elapsed(), then logs "<label>: <ms>ms" via the provided logger's info method. If the timer does not exist, logs a warning via the warn method instead. No output is produced when externalLogger is omitted.

Parameters¶

label¶

string

Timer label

externalLogger?¶

any

Optional logger with info and warn methods

Returns¶

void

Example¶

TypeScript

const smith = new ClockSmith();

smith.start("database-query");
// ... perform database operation ...
smith.stopWithLog("database-query", console);
// console.info: "database-query: 1234ms"

Since¶

0.20.0

timeFunction()¶

timeFunction\<T>(label, fn, externalLogger?): T | Promise\<T>

Execute a function and measure its elapsed time.

Starts a timer before calling fn and stops it when fn returns or throws. Works with both synchronous and async functions. Elapsed time is logged via stopWithLog if externalLogger is provided.

Type Parameters¶

T¶

T

Parameters¶

label¶

string

Label for the timer

fn¶

() => T | Promise\<T>

Synchronous or async function to execute

externalLogger?¶

any

Optional logger with info and warn methods

Returns¶

T | Promise\<T>

The return value of fn

Examples¶

Synchronous function:

TypeScript

const smith = new ClockSmith();

const result = smith.timeFunction("processData", () => {
  return processLargeDataset();
}, console);
// console.info: "processData: 2341ms"

Async function:

TypeScript

const smith = new ClockSmith();

const data = await smith.timeFunction("apiFetch", async () => {
  const res = await fetch("https://example.com/api");
  return res.json();
}, console);
// console.info: "apiFetch: 856ms"

Since¶

0.20.0

start()¶

start(name): void

Create and start a new timer with the given name.

If a timer with the same name already exists, it is replaced.

Parameters¶

name¶

string

Unique label for the timer

Returns¶

void

Example¶

TypeScript

const smith = new ClockSmith();
smith.start("step1");

Since¶

1.0.0

stop()¶

stop(name): void

Stop a named timer and record its stop timestamp.

Parameters¶

name¶

string

Timer label

Returns¶

void

Throws¶

Error if no timer with the given name exists

Example¶

TypeScript

const smith = new ClockSmith();
smith.start("step1");
smith.stop("step1");

Since¶

1.0.0

elapsed()¶

elapsed(name): number

Return the elapsed time of a named timer in milliseconds.

If the timer has not been stopped, returns the time since it was started.

Parameters¶

name¶

string

Timer label

Returns¶

number

Elapsed time in milliseconds

Throws¶

Error if no timer with the given name exists

Example¶

TypeScript

const smith = new ClockSmith();
smith.start("step1");
smith.stop("step1");
console.log(`step1: ${smith.elapsed("step1")}ms`);

Since¶

1.0.0

reset()¶

reset(name): void

Reset a named timer to its initial state.

Clears both the start and stop timestamps of the timer. The timer remains in the manager and can be started again.

Parameters¶

name¶

string

Timer label

Returns¶

void

Throws¶

Error if no timer with the given name exists

Example¶

TypeScript

const smith = new ClockSmith();
smith.start("step1");
smith.stop("step1");
smith.reset("step1");
smith.start("step1"); // reuse the same label

Since¶

1.0.0

get()¶

get(name): Clock | undefined

Return the Clock instance for the given name, or undefined if not found.

Parameters¶

name¶

string

Timer label

Returns¶

Clock | undefined

The Clock instance, or undefined

Example¶

TypeScript

const smith = new ClockSmith();
smith.start("step1");
const clock = smith.get("step1");
console.log(clock?.isRunning()); // true

Since¶

1.0.0

clear()¶

clear(name): boolean

Remove a named timer from the manager.

Parameters¶

name¶

string

Timer label

Returns¶

boolean

true if the timer existed and was removed, false otherwise

Example¶

TypeScript

const smith = new ClockSmith();
smith.start("step1");
smith.clear("step1");
console.log(smith.get("step1")); // undefined

Since¶

1.0.0

clearAll()¶

clearAll(): void

Remove all timers from the manager.

Returns¶

void

Example¶

TypeScript

const smith = new ClockSmith();
smith.start("step1");
smith.start("step2");
smith.clearAll();
console.log(smith.keys()); // []

Since¶

1.0.0

keys()¶

keys(): string[]

Return the labels of all registered timers.

Returns¶

string[]

Array of timer labels in insertion order

Example¶

TypeScript

const smith = new ClockSmith();
smith.start("step1");
smith.start("step2");
console.log(smith.keys()); // ["step1", "step2"]

Since¶

1.0.0

toMap()¶

toMap(): Map\<string, (string | number | null)[]>

Export all timer data as a columnar Map.

Returns a Map with four keys: "label", "started", "stopped", and "elapsed_ms". Each value is an array with one entry per timer, in insertion order. Timestamps are ISO 8601 strings; elapsed time is in milliseconds. Running timers have null for "stopped".

Returns¶

Map\<string, (string | number | null)[]>

Columnar Map of timer data

Example¶

TypeScript

const smith = new ClockSmith();
smith.start("step1");
smith.stop("step1");
const data = smith.toMap();
// Map {
//   "label"      => ["step1"],
//   "started"    => ["2024-01-01T00:00:00.000Z"],
//   "stopped"    => ["2024-01-01T00:00:00.042Z"],
//   "elapsed_ms" => [42]
// }

Since¶

1.0.0

Other¶

defaultName¶

readonly static defaultName: "ClockSmith" = "ClockSmith"