Choose a coordination atom

A Durable Object is a tiny server that exists exactly once per name. It has its own memory, its own little database, and it handles one event at a time. Every request for the same name goes through that one instance.

That last part is the magic. Because there’s only one of each, and it processes events one after another, two requests never step on each other. No race conditions, no distributed locks.

Think of a chat room. You want exactly one place that holds the messages and the list of who’s online. A Durable Object named after the room is that place.

The name is an architectural choice

The object name decides what gets coordinated together. The same name always reaches the same instance:

const id = env.ROOMS.idFromName('team-standup')
const room = env.ROOMS.get(id)

Every request that names team-standup meets at that one instance. A different name is a different object, with separate state and its own queue of events.

So the design question is: what is the unit that needs serialized state changes? One object per room, per booking calendar, per game, per tenant. A rate limiter gets one object per user. A collaborative document gets one object per document.

Pick the atom too big and you build a bottleneck. One global object for the whole application means every request in the world queues behind a single instance:

// every request in the app serializes through this one instance
const id = env.APP.idFromName('global')

Pick the atom too small and there’s nothing to coordinate. Two objects can’t guard one invariant. If seat 12A and seat 12B must never be double-booked on the same flight, the flight is the atom, not the seat.

Practice on a real shape

Draw the objects for a collaborative notes app. Which requests must meet at the same instance?

My answer: one object per note. Concurrent edits to one note must serialize. Edits to different notes are independent and should scale out.

The list of a user’s notes doesn’t need an object at all. That’s a query, and a plain database serves it fine. Coordination is a scarce, expensive thing. Spend it only where two requests fight over the same state.