Durable Objects: Class, Object ID, Live Instance, Storage

A lot of confusion around Durable Objects comes from collapsing four different things into one: the class, the object ID, the currently running instance, and the durable storage. Keeping those separate makes the runtime model much cleaner.

Class vs Object

A Durable Object class is the blueprint. Cloudflare can create many named objects from that one class.

Counter class
├── counter:abc
├── counter:xyz
└── counter:tenant-123

So the right statement is not "there can be only one instance of the class." The right statement is: for a given object ID, only one active instance runs at a time.

The Clean Model

Class       = code / behavior
Object ID   = identity
Live object = currently running instance
Storage     = durable private state

Those are related, but they are not the same thing.

What Actually Persists

Counter class
  -> counter:abc object ID
  -> currently active JS instance
  -> private SQLite-backed storage

The live JavaScript instance can sleep, restart, or be evicted. The identity and durable storage remain.

Memory Is Cache

This is the important correction to make early: a Durable Object is durable because its identity and storage survive. The in-memory object is not guaranteed to live forever.

memory  = cache
storage = source of truth

Why This Matters

Once you separate class, ID, instance, and storage, the rest of the model gets easier to reason about. You can see why many counters can come from one class, why one named counter can have only one active owner, and why restarts do not destroy identity.

The Runtime Shape

One class
many object IDs
one active instance per ID
durable storage behind each ID

That is the runtime contract you design against.

Memory Line

A Durable Object is not "one class, one object." It is one class that can define many named objects, each with its own identity, storage, and at most one active live instance at a time.

Part 2 of 3