durable-objects

Extend the DurableObject class from cloudflare:workers and configure wrangler migrations with new_sqlite_classes. Initialize tables in the constructor using ctx.blockConcurrencyWhile and run synchronous queries via this.ctx.storage.sql.exec.

Use @cloudflare/vitest-pool-workers with defineWorkersConfig pointing at your wrangler config. Access stubs via env from cloudflare:test, inspect internals with runInDurableObject, and trigger alarms instantly with runDurableObjectAlarm.

Use RPC methods with compatibility date 2024-04-03 or later. Public class methods become typed RPC endpoints callable directly on the stub, avoiding manual request parsing and response serialization in fetch handlers.

Avoid Durable Objects for stateless request handling, workloads needing maximum global distribution, or high fan-out independent requests. Plain Workers fit stateless tasks better since DOs add coordination overhead and single-location placement.

blockConcurrencyWhile blocks all concurrency in the instance, so using it per request caps throughput around 200 requests per second. Reserve it for one-time constructor initialization and never hold it across fetch or external I/O.

Each DO supports one alarm; calling setAlarm replaces any existing alarm. The alarm handler runs at the scheduled time with automatic retries on failure, so handlers must be idempotent and can reschedule by calling setAlarm again.