1# Durable Objects API
2 
3## Class Structure
4 
5```typescript
6import { DurableObject } from "cloudflare:workers";
7 
8export class MyDO extends DurableObject<Env> {
9  constructor(ctx: DurableObjectState, env: Env) {
10    super(ctx, env);
11    // Runs on EVERY wake - keep light!
12  }
13  
14  // RPC methods (called directly from worker)
15  async myMethod(arg: string): Promise<string> { return arg; }
16  
17  // fetch handler (legacy/HTTP semantics)
18  async fetch(req: Request): Promise<Response> { /* ... */ }
19  
20  // Lifecycle handlers
21  async alarm() { /* alarm fired */ }
22  async webSocketMessage(ws: WebSocket, msg: string | ArrayBuffer) { /* ... */ }
23  async webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean) { /* ... */ }
24  async webSocketError(ws: WebSocket, error: unknown) { /* ... */ }
25}
26```
27 
28## DurableObjectState Context Methods
29 
30### Concurrency Control
31 
32```typescript
33// Complete work after response sent (e.g., cleanup, logging)
34this.ctx.waitUntil(promise: Promise<any>): void
35 
36// Critical section - blocks all other requests until complete
37await this.ctx.blockConcurrencyWhile(async () => {
38  // No other requests processed during this block
39  // Use for initialization or critical operations
40})
41```
42 
43**When to use:**
44- `waitUntil()`: Background cleanup, logging, non-critical work after response
45- `blockConcurrencyWhile()`: First-time init, schema migration, critical state setup
46 
47### Lifecycle
48 
49```typescript
50this.ctx.id              // DurableObjectId of this instance
51this.ctx.abort()         // Force eviction (use after PITR restore to reload state)
52```
53 
54### Storage Access
55 
56```typescript
57this.ctx.storage.sql     // SQLite API (recommended)
58this.ctx.storage.kv      // Sync KV API (SQLite DOs only)
59this.ctx.storage         // Async KV API (legacy/KV-only DOs)
60```
61 
62See **[DO Storage](../do-storage/README.md)** for complete storage API reference.
63 
64### WebSocket Management
65 
66```typescript
67this.ctx.acceptWebSocket(ws: WebSocket, tags?: string[])  // Enable hibernation
68this.ctx.getWebSockets(tag?: string): WebSocket[]         // Get by tag or all
69this.ctx.getTags(ws: WebSocket): string[]                 // Get tags for connection
70```
71 
72### Alarms
73 
74```typescript
75await this.ctx.storage.setAlarm(timestamp: number | Date)  // Schedule (overwrites existing)
76await this.ctx.storage.getAlarm(): number | null           // Get next alarm time
77await this.ctx.storage.deleteAlarm(): void                 // Cancel alarm
78```
79 
80**Limit:** 1 alarm per DO. Use queue pattern for multiple events (see [Patterns](./patterns.md)).
81 
82## Storage APIs
83 
84For detailed storage documentation including SQLite queries, KV operations, transactions, and Point-in-Time Recovery, see **[DO Storage](../do-storage/README.md)**.
85 
86Quick reference:
87 
88```typescript
89// SQLite (recommended)
90this.ctx.storage.sql.exec("SELECT * FROM users WHERE id = ?", userId).one()
91 
92// Sync KV (SQLite DOs only)
93this.ctx.storage.kv.get("key")
94 
95// Async KV (legacy)
96await this.ctx.storage.get("key")
97```
98 
99## Alarms
100 
101Schedule future work that survives eviction:
102 
103```typescript
104// Set alarm (overwrites any existing alarm)
105await this.ctx.storage.setAlarm(Date.now() + 3600000)  // 1 hour from now
106await this.ctx.storage.setAlarm(new Date("2026-02-01"))  // Absolute time
107 
108// Check next alarm
109const nextRun = await this.ctx.storage.getAlarm()  // null if none
110 
111// Cancel alarm
112await this.ctx.storage.deleteAlarm()
113 
114// Handler called when alarm fires
115async alarm() {
116  // Runs once alarm triggers
117  // DO wakes from hibernation if needed
118  // Use for cleanup, notifications, scheduled tasks
119}
120```
121 
122**Limitations:**
123- 1 alarm per DO maximum
124- Overwrites previous alarm when set
125- Use queue pattern for multiple scheduled events (see [Patterns](./patterns.md))
126 
127**Reliability:**
128- Alarms survive DO eviction/restart
129- Cloudflare retries failed alarms automatically
130- Not guaranteed exactly-once (handle idempotently)
131 
132## WebSocket Hibernation
133 
134Hibernation allows DOs with open WebSocket connections to consume zero compute/memory until message arrives.
135 
136```typescript
137async fetch(req: Request): Promise<Response> {
138  const [client, server] = Object.values(new WebSocketPair());
139  this.ctx.acceptWebSocket(server, ["room:123"]);  // Tags for filtering
140  server.serializeAttachment({ userId: "abc" });    // Persisted metadata
141  return new Response(null, { status: 101, webSocket: client });
142}
143 
144// Called when message arrives (DO wakes from hibernation)
145async webSocketMessage(ws: WebSocket, msg: string | ArrayBuffer) {
146  const data = ws.deserializeAttachment();          // Retrieve metadata
147  for (const c of this.ctx.getWebSockets("room:123")) c.send(msg);
148}
149 
150// Called on close (optional handler)
151async webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean) {
152  // Cleanup logic, remove from lists, etc.
153}
154 
155// Called on error (optional handler)
156async webSocketError(ws: WebSocket, error: unknown) {
157  console.error("WebSocket error:", error);
158  // Handle error, close connection, etc.
159}
160```
161 
162**Key concepts:**
163- **Auto-hibernation:** DO hibernates when no active requests/alarms
164- **Zero cost:** Hibernated DOs incur no charges while preserving connections
165- **Memory cleared:** All in-memory state lost on hibernation
166- **Attachment persistence:** Use `serializeAttachment()` for per-connection metadata that survives hibernation
167- **Tags for filtering:** Group connections by room/channel/user for targeted broadcasts
168 
169**Handler lifecycle:**
170- `webSocketMessage`: DO wakes, processes message, may hibernate after
171- `webSocketClose`: Called when client closes (optional - implement for cleanup)
172- `webSocketError`: Called on connection error (optional - implement for error handling)
173 
174**Metadata persistence:**
175```typescript
176// Store connection metadata (survives hibernation)
177ws.serializeAttachment({ userId: "abc", room: "lobby" })
178 
179// Retrieve after hibernation
180const { userId, room } = ws.deserializeAttachment()
181```
182 
183## See Also
184 
185- **[DO Storage](../do-storage/README.md)** - Complete storage API reference
186- **[Patterns](./patterns.md)** - Real-world usage patterns
187- **[Gotchas](./gotchas.md)** - Hibernation caveats and limits
188