do: docs feedback on alarms + waituntil (#27145)

elithrar · web-flow · commit 3d4a54b1b412 · 2025-12-18T18:32:26.000Z
diff --git a/src/content/docs/durable-objects/api/alarms.mdx b/src/content/docs/durable-objects/api/alarms.mdx
@@ -27,6 +27,53 @@ Alarms are directly scheduled from within your Durable Object. Cron Triggers, on
 
 Alarms can be used to build distributed primitives, like queues or batching of work atop Durable Objects. Alarms also provide a mechanism to guarantee that operations within a Durable Object will complete without relying on incoming requests to keep the Durable Object alive. For a complete example, refer to [Use the Alarms API](/durable-objects/examples/alarms-api/).
 
+## Scheduling multiple events with a single alarm
+
+Although each Durable Object can only have one alarm set at a time, you can manage many scheduled and recurring events by storing your event schedule in storage and having the `alarm()` handler process due events, then reschedule itself for the next one.
+
+```js
+import { DurableObject } from "cloudflare:workers";
+
+export class AgentServer extends DurableObject {
+  // Schedule a one-time or recurring event
+  async scheduleEvent(id, runAt, repeatMs = null) {
+    await this.ctx.storage.put(`event:${id}`, { id, runAt, repeatMs });
+    const currentAlarm = await this.ctx.storage.getAlarm();
+    if (!currentAlarm || runAt < currentAlarm) {
+      await this.ctx.storage.setAlarm(runAt);
+    }
+  }
+
+  async alarm() {
+    const now = Date.now();
+    const events = await this.ctx.storage.list({ prefix: "event:" });
+    let nextAlarm = null;
+
+    for (const [key, event] of events) {
+      if (event.runAt <= now) {
+        await this.processEvent(event);
+        if (event.repeatMs) {
+          event.runAt = now + event.repeatMs;
+          await this.ctx.storage.put(key, event);
+        } else {
+          await this.ctx.storage.delete(key);
+        }
+      }
+      // Track the next event time
+      if (event.runAt > now && (!nextAlarm || event.runAt < nextAlarm)) {
+        nextAlarm = event.runAt;
+      }
+    }
+
+    if (nextAlarm) await this.ctx.storage.setAlarm(nextAlarm);
+  }
+
+  async processEvent(event) {
+    // Your event handling logic here
+  }
+}
+```
+
 ## Storage methods
 
 ### `getAlarm`
diff --git a/src/content/docs/durable-objects/api/state.mdx b/src/content/docs/durable-objects/api/state.mdx
@@ -76,11 +76,11 @@ Contains loopback bindings to the Worker's own top-level exports. This has exact
 
 `waitUntil` waits until the promise which is passed as a parameter resolves, and can extend a request context even after the last client disconnects. Refer to [Lifecycle of a Durable Object](/durable-objects/concepts/durable-object-lifecycle/) for more information.
 
-:::note[`waitUntil` is not necessary]
+:::note[`waitUntil` has no effect in Durable Objects]
 
-If a Durable Object is still waiting on any ongoing work or outbound I/O, it will remain active for a period of time. Therefore, `waitUntil` is not necessary. It remains part of the `DurableObjectState` interface to remain compatible with [Workers Runtime APIs](/workers/runtime-apis/context/#waituntil).
+Unlike in Workers, `waitUntil` has no effect in Durable Objects. It exists only for API compatibility with the [Workers Runtime APIs](/workers/runtime-apis/context/#waituntil).
 
-Refer to [Lifecycle of a Durable Object](/durable-objects/concepts/durable-object-lifecycle/) for more information.
+Durable Objects automatically remain active as long as there is ongoing work or pending I/O, so `waitUntil` is not needed. Refer to [Lifecycle of a Durable Object](/durable-objects/concepts/durable-object-lifecycle/) for more information.
 :::
 
 #### Parameters
