WallClock
Timers for long delays that follow the system clock. A deadline that passes while the system is asleep fires right after it resumes.
The global setTimeout and setInterval count elapsed time. On Linux, that
doesn’t include the time the system spends asleep, so a long timer can fire
late by that much. They also can’t wait longer than about 24.8 days
(2^31 - 1 ms): a longer delay runs after 1 ms.
These timers are due at a moment on the system clock instead, accept delays of up to one year, and tell an interval’s callback how many ticks it missed. For short delays, the global timers are fine.
Catching up after sleep relies on the same resume signal as the
systemResumed app event, so on Linux it requires systemd-logind. On
macOS, a deadline that passes during sleep waits for a full wake, not
a brief background one.
import { wallClock } from '@mobrowser/api';
Example
import { wallClock } from '@mobrowser/api';
const reminder = wallClock.setTimeout(() => {
console.log('Time is over')
}, new Date('2026-12-01T09:00:00'))
Methods
setTimeout()
setTimeout(callback: () => void, time: number | Date): WallClockTimer;
Runs callback once, after a delay or at a specific moment. The timer
stops when the time is over.
@throws TypeError if callback isn’t a function, or time is invalid or
more than one year ahead.
| Parameter | Type | Description |
|---|---|---|
callback | () => void | The function to run. |
time | number | Date | The delay in milliseconds, or the Date to run at, up to one year ahead. A delay below 1 is treated as 1, and a Date in the past fires right away. |
Return value
The timer. See WallClockTimer.
Example
import { wallClock } from '@mobrowser/api';
const HOUR = 60 * 60 * 1000
const delayed = wallClock.setTimeout(() => {
console.log('Two hours have passed')
}, 2 * HOUR)
const reminder = wallClock.setTimeout(() => {
console.log('Time is over')
}, new Date('2026-12-01T09:00:00'))
setInterval()
setInterval(callback: (info: { missed: number }) => void, interval: number): WallClockTimer;
Runs callback every interval milliseconds.
Ticks missed during sleep are combined into one call. The next tick is counted from that call.
@throws TypeError if callback isn’t a function, or interval isn’t
finite or exceeds one year.
| Parameter | Type | Description |
|---|---|---|
callback | (info: { missed: number }) => void | The function to run. missed is the number of ticks skipped since the previous call. It’s normally 0, and grows when the system sleeps, the main thread is blocked, or the system clock moves forward. |
interval | number | The interval in milliseconds, from 1 up to one year. Smaller values are treated as 1. |
Return value
The timer. See WallClockTimer.
Example
import { wallClock } from '@mobrowser/api';
const HOUR = 60 * 60 * 1000
const interval = wallClock.setInterval(({ missed }) => {
console.log(`Tick. Missed ticks: ${missed}`)
}, 6 * HOUR)