Contents

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.

ParameterTypeDescription
callback() => voidThe function to run.
timenumber | DateThe 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.

ParameterTypeDescription
callback(info: { missed: number }) => voidThe 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.
intervalnumberThe 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)