Timer

The Timer class provides a versatile countdown timer that can map its progress to a custom range and emit events. It also includes a static utility function for calculating human-readable relative time differences.

An instance must be created to use the countdown timer functionality.

---

Static Functions

getRelativeTime

Calculates a human-readable, relative time string between a given time and the present moment (e.g., "5 minutes ago", "in 2 hours").

Parameters

• time: The time input, either as a Unix timestamp (in milliseconds) or an ISO 8601 date string.

• options: An optional object.

  • locale: The locale to use for formatting (e.g., en, de). Defaults to en.

Example: Time in the past

# time
2025-07-12T08:00:00.000Z
# options
locale: en-US

Output: A string like "3 hours ago".

Example: Time in the future

# time
1752367200000

Output: A string like "in 2 years".

---

Instance-Based Timer

You must create an instance of the Timer to use the countdown features.

create

Creates a new timer instance with a specified duration and progress range.

Parameters

• options: An object for configuring the timer.

  • min: The value representing the start of the timer's progress. Defaults to 0.

  • max: The value representing the end of the timer's progress. Defaults to 100.

  • totalSeconds: The total duration of the countdown in seconds. Defaults to 10.

  • autoStop: If true, the timer automatically stops when it reaches zero. Defaults to true.

Example

# options
totalSeconds: 60
min: 0
max: 100

---

setTotalSeconds

Sets or changes the total duration of the timer.

Parameters

• seconds: The total number of seconds for the countdown.

---

getTotalSeconds

Retrieves the total duration of the timer in seconds.

Output

An integer representing the total seconds.

---

getSecondsLeft

Retrieves the remaining seconds on the timer.

Output

An integer representing the seconds left.

---

getProgress

Retrieves the current progress of the timer, mapped to the min and max range defined at creation.

Output

A number representing the current progress.

---

getState

Retrieves the current state of the timer.

Output

A string: stopped or started.

---

start

Starts the countdown timer. If called while a delayed stop is pending, it will cancel the stop command.

---

stop

Stops the timer.

Parameters

• waitingPeriod: An optional delay in milliseconds before the timer actually stops. If start is called during this period, the stop command is cancelled.

Example: Delayed stop

# waitingPeriod
5000

---

onTick

Registers a handler (listener) that is triggered every second while the timer is running. The listener receives two arguments: secondsLeft and currentProgress.

Parameters

• listener: The callback function to execute on each tick.

Example

# listener
<callback>

---

onTimeup

Registers a handler that is triggered once when the countdown reaches zero. The listener receives one argument: the Unix timestamp (in milliseconds) of when the time was up.

Parameters

• listener: The callback function to execute when the time is up.

Example

# listener
<callback>