durable-objects

# Butterbase Durable Objects Durable Objects (DOs) are **stateful per-key actors** running on Cloudflare Workers. Each instance has its own in-memory state and a built-in transactional KV store. Use one when state must survive across requests for a single room/user/agent. For stateless work, use a serverless function instead (`butterbase-skills:function-dev`). One tool: **`manage_durable_objects`**. --- ## 1. The mental model ``` Class: ChatRoom (deployed once) │ ├── instance "lobby" ─► in-memory state + state.storage + WebSockets ├── instance "general" ─► separate state, separate sockets └── instance "user-123" ─► separate again Each URL https://<app>.butterbase.dev/_do/chat-room/<instance-id> gets routed to the instance with that id. State is isolated per id. ``` A class is shared code; an **instance** is a unique key (`/lobby`, `/general`, `/user-123`). Different ids = different state. There is no shared cross-instance state. --- ## 2. Constraints (read these first) - **One TypeScript file per class.** No npm imports. Only `import { ... } from 'cloudflare:workers'` is allowed. - **Exactly one exported class.** `export class Foo { ... }` — no extra exports, no helpers re-exported. - **PascalCase class name** in source; **kebab-case** for the URL name (e.g. `ChatRoom` ↔ `chat-room`). - File size: ≤ 5 MB. Total of all DO classes per app: ≤ 10 MB compressed. - ≤ 5 DO classes per app (v1). - **No service bindings yet.** Functions reach DOs ...