Timer
The timer class introduces countdowns into your flows, maps countdown progress to a custom range, and reacts to ticks and finished countdowns. It also provides a static utility function to format human-readable relative time differences. This class requires an instance for countdown features. The code class name is Timer.
Static functions
Use these functions without creating an instance.
getRelativeTime
Calculates a human-readable, relative time string between a specified time and the current moment (for example, "3 hours ago" or "in 2 years").
Parameters
time
The time input, either as a Unix timestamp in milliseconds or an ISO 8601 date string.
any
options
locale
The locale code to use for formatting (for example, en or de). Default en.
string
Output
Returns the relative time as a string.
Examples
Past time
Formats an ISO date string.
# time
2025-07-12T08:00:00.000Z
# options
locale: enThe output depends on the current time, for example 3 hours ago.
Future time
Formats a Unix timestamp in milliseconds.
The output depends on the current time, for example in 2 years.
Instance functions
You must create an instance to use these functions.
create
Creates a new timer instance with a configured duration and progress range.
Parameters
options
min
The value representing the start of the timer progress. Default 0.
integer
max
The value representing the end of the timer progress. Default 100.
integer
totalSeconds
The total duration of the countdown in seconds. Default 10.
integer
autoStop
Automatically stops the timer when it reaches zero. If false, the timer keeps running and its state becomes overdue. Default true.
boolean
Output
Returns the name of the created instance.
Example
delete
Deletes a timer instance.
Parameters
None.
Output
Returns true upon removal.
setTotalSeconds
Sets the total duration of the timer.
Parameters
seconds
The total number of seconds for the countdown.
integer
Output
Returns nothing.
getTotalSeconds
Returns the total duration of the timer in seconds.
Parameters
None.
Output
Returns the total seconds as an integer.
getSecondsLeft
Returns the remaining seconds on the timer. When the timer is stopped, this returns the total seconds configuration.
Parameters
None.
Output
Returns the seconds left as an integer.
getProgress
Returns the current progress of the timer, mapped to the defined min and max range. When the timer is stopped, this returns the min value.
Parameters
None.
Output
Returns the progress value as an integer.
getState
Returns the current state of the timer.
Parameters
None.
Output
Returns a string representing the state: stopped, started, or overdue.
start
Starts the countdown timer and sets the remaining time to the configured total. If called while a delayed stop is pending, this action only cancels the stop command.
Parameters
None.
Output
Returns nothing. If the timer is already started, the function returns the difference between remaining and total seconds.
stop
Stops the timer.
Parameters
waitingPeriod
An optional delay in milliseconds before the timer stops. If you call start during this period, the stop command is cancelled. Subsequent stop calls during this period are ignored. Default 0.
integer
Output
Returns nothing.
Example
Delayed stop
Stops the timer after a 5-second delay.
Event listeners
These functions let you subscribe callbacks to the timer instance events.
onTick
Subscribes to the tick event. The callback runs every second while the timer is running.
Parameters
callback
The callback function.
Payload: secondsLeft (integer) and currentProgress (integer).
callback
Output
Returns the string subscribed.
Example
onTimeup
Subscribes to the timeup event. The callback runs once when the countdown reaches zero.
Parameters
callback
The callback function. Payload: the Unix timestamp in milliseconds when the countdown finished.
callback
Output
Returns the string subscribed.
Example
Last updated
Was this helpful?