> For the complete documentation index, see [llms.txt](https://docs.heisenware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heisenware.com/app-builder/build-backend/functions/utilities/timer.md). # 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. ```yaml # 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. ```yaml # 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 ```yaml # options totalSeconds: 60 min: 0 max: 100 ``` ### `delete` Deletes a timer instance. #### Parameters None. #### Output Returns `true` upon removal. {% hint style="danger" %} #### Irreversible action Deleting removes the instance configuration. {% endhint %} ### `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. ```yaml # 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 ```yaml # 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 ```yaml # callback ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.heisenware.com/app-builder/build-backend/functions/utilities/timer.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.