connect.alarms

Schedule timers that live in the main process, so they survive a suspended background and wake it — the right tool for periodic work in a suspendable extension.

• Capability: alarms
• Namespace: connect.alarms

Walkthrough

Run a sync every 30 minutes, even if the background sleeps.

1. Declare alarms:

   { "capabilities": ["alarms"] }

2. Create a periodic alarm at boot:

   await connect.alarms.create('sync', { delayInMinutes: 1, periodInMinutes: 30 });

3. Handle it — the fire wakes a suspended background:

   connect.alarms.onAlarm(({ name }) => name === 'sync' && doSync());

4. Re-create at boot — v1 alarms reset on app restart.

Methods

alarms.create(name, options)

Create (or re-arm) a named alarm.

How to use it

1. Pass a name and either when (absolute) or delayInMinutes (relative).
2. Add periodInMinutes for a repeating alarm.
3. Reuse a name to replace an existing alarm.

Signature — connect.alarms.create(name, { when?, delayInMinutes?, periodInMinutes? })

Parameters

Returns — Promise<void>.

await connect.alarms.create('sync', { delayInMinutes: 1, periodInMinutes: 30 });

alarms.get(name) · alarms.getAll()

Inspect alarms.

How to use it

1. get(name) to check one; getAll() to list them (e.g. to avoid duplicating).

Returns — Promise<Alarm | null> / Promise<Alarm[]>.

alarms.clear(name) · alarms.clearAll()

Cancel one alarm or all of them.

How to use it

1. clear(name) to cancel one; clearAll() to cancel every alarm you set.

Returns — Promise<boolean> / Promise<void>.

Events

alarms.onAlarm(cb)

Fires when an alarm elapses. Sticky, and wakes a suspended background.

How to use it

1. Subscribe in the background.
2. Branch on name; the fire itself wakes a suspended background.

Payload — { name, scheduledTime }.

connect.alarms.onAlarm(({ name }) => {
  if (name === 'sync') doSync();
});

Notes

• v1 alarms are in-memory: they survive suspension but reset on app restart, and are cleared on uninstall. Re-create them from runtime.onInstalled / at boot if you need them after a restart.
• Prefer an alarm over setInterval in a suspendable background — the interval dies with the background; the alarm wakes it.