app.timer - Timer API

Provides delayed execution and repeated execution functionality.

Permission: L1 Standard — must be declared in permissions ("timer")

Methods

app.timer.after(seconds, callback)

Creates a one-shot delayed timer.

Parameters:

• seconds (number) - Delay time in seconds, minimum 0.01
• callback (function) - Callback function to execute after the delay

Returns: timerHandle - The timer handle; nil, error on failure

This is a handle table, not a string id. Concatenating it raises attempt to concatenate a table value. Its methods: stop().

-- Execute after 3 seconds
local t, err = app.timer.after(3, function()
    app.notification.show("Reminder", "3 seconds are up!")
end)

-- Execute after 0.5 seconds
app.timer.after(0.5, function()
    app.log.info("Executed after a short delay")
end)

app.timer.start(seconds, callback)

Creates a repeating timer.

Parameters:

• seconds (number) - Execution interval in seconds, minimum 0.1
• callback (function) - Callback function to execute on each trigger

Returns: timerHandle - The timer handle; nil, error on failure

This is a handle table, not a string id. Stop it with t:stop(); app.timer.stopAll() stops every timer this plugin created.

-- Execute every 5 seconds
local t = app.timer.start(5, function()
    app.log.info("Heartbeat: " .. os.date())
end)

-- Stop when needed
t:stop()

handle:stop()

Cancels the specified timer.

Returns: boolean, error

local ok, err = t:stop()

app.timer.stopAll()

Cancels all timers for the current plugin.

Returns: boolean

app.timer.stopAll()

app.timer.list()

Lists all active timers for the current plugin.

Returns: array<table> - Each item contains:

• id (string) - Timer ID
• type (string) - Type: "once" or "repeating"
• interval (number) - Interval/delay in seconds
• repeats (boolean) - Whether it repeats
• remaining (number, one-shot only) - Remaining time in seconds

local timers = app.timer.list()
for _, tmr in ipairs(timers) do
    app.log.info(tmr.id .. ": " .. tmr.type .. " interval=" .. tmr.interval)
end

Description

• Each plugin can have up to 100 timers
• One-shot timers are automatically removed after execution
• Timers are automatically cancelled when the plugin is unloaded
• Callbacks are invoked on the plugin execution queue (thread-safe)
• after() minimum delay is 0.01 seconds, every() minimum interval is 0.1 seconds

Examples

Periodically check for file changes

local checkTimer = nil

function MyPlugin:handleStartMonitor(context)
    local dir = context.currentDirectory
    local lastCount = 0

    checkTimer = app.timer.start(10, function()
        local files = app.file.list(dir)
        if files and #files ~= lastCount then
            local diff = #files - lastCount
            if diff > 0 then
                app.notification.show("New Files", "Found " .. diff .. " new file(s)")
            end
            lastCount = #files
        end
    end)

    app.notification.show("Monitor", "Started monitoring: " .. dir)
end

function MyPlugin:handleStopMonitor(context)
    if checkTimer then
        checkTimer:stop()
        checkTimer = nil
        app.notification.show("Monitor", "Monitoring stopped")
    end
end

Auto-close progress bar after delay

function MyPlugin:handleProcess(context)
    local p = app.progress.create({title = "Processing", message = "Processing..."})

    -- Simulate processing
    for i = 1, 100 do
        p:update(i, "Step " .. i .. "/100")
        app.thread.sleep(0.05)
    end

    p:update(100, "Done!")

    -- Auto-close progress bar after 1 second
    app.timer.after(1, function()
        p:close()
    end)
end