Stopwatch

The Stopwatch class provides a high-resolution timer for accurately measuring time intervals. You can create an instance of a stopwatch to start, stop, pause, and reset it. This is useful for timing operations, tracking user activity, or managing any time-based logic.

A key feature of the stopwatch is its ability to record "laps," which are snapshots of the elapsed time at a specific moment without stopping the main timer.

The stopwatch also emits events (like start, stop, lap, and tick) that other parts of your application can listen to. This allows you to trigger other functions or flows automatically—for example, updating a display every second the stopwatch is running.

Static Functions

formatTime

Converts a duration in milliseconds into a human-readable, formatted string.

This is a static function, so you can use it directly without creating a Stopwatch instance first. It's helpful for displaying the output of getElapsedTime() or getLaps() in a friendly format.

The format argument uses special tokens that are replaced by time values:

HH: Hours, padded with a zero (e.g., 08)
H: Hours, not padded (e.g., 8)
mm: Minutes, padded with a zero (e.g., 05)
m: Minutes, not padded (e.g., 5)
ss: Seconds, padded with a zero (e.g., 01)
s: Seconds, not padded (e.g., 1)
ms: Milliseconds, padded to 3 digits (e.g., 045)

Parameters

milliseconds: The number of milliseconds you want to format.
format (Optional): A string defining the output format. If you don't provide one, the default format is HH:mm:ss.ms.

Example 1: Default Format

This example formats 125,500 milliseconds (2 minutes, 5 seconds, 500 ms) using the default format.

# milliseconds
125500
# format (optional, default is 'HH:mm:ss.ms')

Output

"00:02:05.500"

Example 2: Custom Format

This example formats 3,601,000 milliseconds (1 hour, 1 second) using a custom, descriptive string.

# milliseconds
3601000
# format
"H hour, m minutes, and s seconds"

Output

"1 hour, 0 minutes, and 1 seconds"

Constructor and Member Functions

create

This is the constructor. It creates a new, blank Stopwatch instance. The new stopwatch is initialized in a 'stopped' state with an elapsed time of 0.

Output

Returns a new Stopwatch instance. You must use this instance to call all the member functions listed below (like start, stop, etc.).

start

Starts or resumes the stopwatch. If the stopwatch is already running, this function does nothing. This function also triggers the onStart event.

stop

Stops (pauses) the stopwatch. The current elapsed time is saved and will be held until start is called again. If the stopwatch is already stopped, this function does nothing. This function also triggers the onStop event.

reset

Stops the stopwatch (if it's running) and resets its elapsed time and all recorded laps back to zero. This function also triggers the onReset event.

lap

Records the current elapsed time as a "lap" without stopping the timer. If the stopwatch is not running, this function does nothing. This function also triggers the onLap event.

getElapsedTime

Returns the total elapsed time in milliseconds (as a number). This works whether the stopwatch is currently running or stopped.

Output

15320.5

getLaps

Returns a list (an array) of all lap times that have been recorded using the lap() function.

Output

[
  5012.3,
  10050.1,
  15320.5
]

clearLaps

Clears all recorded laps from the stopwatch's memory. This does not stop or reset the main timer.

isRunning

Checks if the stopwatch is currently running.

Output

The output will be true if running, false if stopped

getState

Returns the current state of the stopwatch as a text string.

Output

The output will be "running" or "stopped"

setTickInterval

Sets the update interval (in milliseconds) for the 'tick' event. By default, the interval is 1000 (1 second). If the stopwatch is already running, the new interval will be applied immediately.

Parameters

intervalMs: The new update interval in milliseconds.

Example

This example sets the stopwatch to emit a 'tick' event every half-second.

# intervalMs
500

onStart

Subscribes to the 'start' event. The listener flow you provide will be executed every time this stopwatch instance is started.

onStop

Subscribes to the 'stop' event. The listener flow you provide will be executed every time this stopwatch instance is stopped.

onReset

Subscribes to the 'reset' event. The listener flow you provide will be executed every time this stopwatch instance is reset.

onTick

Subscribes to the 'tick' event. This event fires repeatedly while the stopwatch is running, at the interval set by setTickInterval.

onLap

Subscribes to the 'lap' event. This event fires every time the lap() function is successfully called.

Parameters

listener: The flow to execute when the event fires. This flow will be triggered with an object containing the lap data.

Input to your Listener Flow: When this event fires, your listener flow will receive an object with two keys:
lapTime: The time of the lap that was just recorded (e.g., 5012.3).
allLaps: A list of all laps recorded so far, including the new one (e.g., [5012.3, 10050.1]).

removeAllListeners

Unsubscribes all listeners (like onStart, onStop, onTick, etc.) that are currently attached to this specific stopwatch instance.

Output

"unsubscribed"

Last updated 10 hours ago