Timer.restart
luastra/timerTimer.restart(options: StartOptions): RequestId
Replaces the pending one-shot timer with the same ID and schedules a fresh delay and value. This makes repeated input postpone one logical deadline instead of allowing several expiries to race.
Before you use it
Add luastra/timer to this module's dependencies in luastra.json, then import it with require("luastra/timer"). Declare timer.control in luastra.json and implement app.handle for timer events. The maximum delay is 60,000 ms.
How it fits
start, restart, and cancel return an acknowledgement RequestId, but timer.control completions are intentionally not delivered to app.resolve. A one-shot expiry arrives later as app.handle("timer", timerId, value).
When to use it
Use Timer.restart for inactivity deadlines, search debounce, and any timeout whose countdown must begin again after a new event. Use start for a new logical timer and cancel when the pending work is no longer relevant.
Parameters
| Parameter | Type / values | Description |
|---|---|---|
| options | StartOptions | Replacement delay and value for the pending timer with the same stable ID. |
| options.id | string | Existing or new stable timer ID to replace atomically. |
| options.delayMs | integer (0..60000) | Fresh delay before the replacement timer fires. |
| options.value | string? | Optional bounded value delivered with the replacement event. |
Returns
RequestId — an opaque acknowledgement token for the timer control request. Timer acknowledgements do not enter app.resolve; an uncancelled expiry arrives through app.handle.
What happens next
The requested timer operation is acknowledged; an uncancelled start or restart later emits one timer event.
Failures and fixes
Missing timer.control, an invalid lowercase timer id, a delay outside 0..60000, or an oversized value fails before a timer event is scheduled. Treat late events as stale if the owning state has already changed.
Availability
Public-source alpha API in 0.5.0-alpha; exact background timing remains host-dependent.
Focused example
local Timer = require("luastra/timer")
Timer.restart { id = "game/next-card", delayMs = 1500, value = "advance" }