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

Input	Key	Description	Type
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: en

The output depends on the current time, for example 3 hours ago.

Future time

Formats a Unix timestamp in milliseconds.

# time
1783903200000

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

Input	Key	Description	Type
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

# options
totalSeconds: 60
min: 0
max: 100

delete

Deletes a timer instance.

Parameters

None.

Output

Returns true upon removal.

Irreversible action

Deleting removes the instance configuration.

setTotalSeconds

Sets the total duration of the timer.

Parameters

Input	Description	Type
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

Input	Description	Type
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.

# waitingPeriod
5000

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

Input	Description	Type
callback	The callback function. Payload: secondsLeft (integer) and currentProgress (integer).	callback

Output

Returns the string subscribed.

Example

# callback
<callback>

onTimeup

Subscribes to the timeup event. The callback runs once when the countdown reaches zero.

Parameters

Input	Description	Type
callback	The callback function. Payload: the Unix timestamp in milliseconds when the countdown finished.	callback

Output

Returns the string subscribed.

Example

# callback
<callback>