DurableObjectNamespace

Source: src/Cloudflare/Workers/DurableObjectNamespace.ts

A Cloudflare Durable Object namespace that manages globally unique, stateful instances with WebSocket hibernation support.

A Durable Object uses a two-phase pattern with two nested Effect.gen blocks. The outer Effect resolves shared dependencies (other DOs, containers, etc.). The inner Effect runs once per instance and returns the object’s public methods and WebSocket handlers.

Effect.gen(function* () {
  // Phase 1: resolve shared dependencies
  const db = yield* Cloudflare.D1Connection.bind(MyDB);

  return Effect.gen(function* () {
    // Phase 2: per-instance setup and public API
    const state = yield* Cloudflare.DurableObjectState;

    return {
      save: (data: string) => db.exec("INSERT ..."),
      fetch: Effect.gen(function* () { ... }),
      webSocketMessage: Effect.fnUntraced(function* (ws, msg) { ... }),
    };
  });
})

There are two ways to define a Durable Object. See the {@link https://alchemy.run/concepts/platform | Platform concept} page for the full explanation.

• Inline — Effect implementation passed directly, single file.
• Modular — class and implementation in separate files for tree-shaking.

Inline Durable Objects

Pass the Effect implementation as the second argument. This is the simplest approach — everything lives in one file. Convenient when the DO doesn’t need to be referenced by other Workers or DOs that would pull in its runtime dependencies.

export default class Counter extends Cloudflare.DurableObjectNamespace<Counter>()(
  "Counter",
  Effect.gen(function* () {
    // init: bind resources
    const db = yield* Cloudflare.D1Connection.bind(MyDB);

    return Effect.gen(function* () {
      const state = yield* Cloudflare.DurableObjectState;
      const count = (yield* state.storage.get<number>("count")) ?? 0;

      return {
        // runtime: use them
        increment: () =>
          Effect.gen(function* () {
            const next = count + 1;
            yield* state.storage.put("count", next);
            return next;
          }),
        get: () => Effect.succeed(count),
      };
    });
  }),
) {}

Modular Durable Objects

When a Worker and a DO reference each other, or multiple Workers bind the same DO, define the class separately from its .make() call. The class is a lightweight identifier; .make() provides the runtime implementation as an export default. Rolldown treats .make() as pure, so the bundler tree-shakes it and all its runtime dependencies out of any consumer’s bundle.

The class and .make() can live in the same file. This is the same pattern used by Worker and Container.

Modular Durable Object (class + .make() in one file)

src/Counter.ts

export class Counter extends Cloudflare.DurableObjectNamespace<Counter>()(
  "Counter",
) {}

export default Counter.make(
  Effect.gen(function* () {
    // init: bind resources
    const db = yield* Cloudflare.D1Connection.bind(MyDB);

    return Effect.gen(function* () {
      const state = yield* Cloudflare.DurableObjectState;
      const count = (yield* state.storage.get<number>("count")) ?? 0;

      return {
        // runtime: use them
        increment: () =>
          Effect.gen(function* () {
            const next = count + 1;
            yield* state.storage.put("count", next);
            yield* db.prepare("INSERT INTO logs (count) VALUES (?)").bind(next).run();
            return next;
          }),
        get: () => Effect.succeed(count),
      };
    });
  }),
);

Binding a modular DO from a Worker

// imports Counter; bundler tree-shakes .make()
import Counter from "./Counter.ts";

// init
const counters = yield* Counter;

return {
  fetch: Effect.gen(function* () {
    const counter = counters.getByName("user-123");
    return HttpServerResponse.text(String(yield* counter.get()));
  }),
};

Cross-Worker Binding

A Durable Object is hosted by exactly one Worker, but any number of other Workers can bind to the same DO. This is how you share state across Workers: one Worker hosts the DO, every other Worker addresses it by scriptName and gets a typed stub.

To make this type-safe, the host Worker must declare the DO as part of its public contract via the third type argument to Cloudflare.Worker<Self, Bindings, Deps>(). Deps is the set of DO classes (or other Workers) the script exposes for other scripts to bind to.

Host Worker declares the DO in its contract

// workerA.ts — hosts Counter
import { Counter, CounterLive } from "./object.ts";

//                                       ^^^^^^^ declared as part of WorkerA's public contract
export class WorkerA extends Cloudflare.Worker<WorkerA, {}, Counter>()(
  "WorkerA",
  { main: import.meta.filename },
) {}

// WorkerA's Layer also provides the DO's Live implementation.
export default WorkerA.make(
  Effect.gen(function* () {
    const counter = yield* Counter;
    return { fetch: Effect.gen(function* () { ... }) };
  }).pipe(Effect.provide(CounterLive)),
);

Consumer Worker binds the DO via Counter.from(WorkerA)

// workerB.ts — binds to the same Counter, hosted by WorkerA
import { Counter } from "./object.ts";
import { WorkerA } from "./workerA.ts";

export default class WorkerB extends Cloudflare.Worker<WorkerB>()(
  "WorkerB",
  { main: import.meta.filename },
  Effect.gen(function* () {
    //              ^^^^^^^^^^^^ scriptName-bound stub of WorkerA's Counter
    const counter = yield* Counter.from(WorkerA);
    return {
      fetch: Effect.gen(function* () {
        const value = yield* counter.getByName("shared").get();
        return HttpServerResponse.text(String(value));
      }),
    };
  }),
) {}

Tip

The , Counter in Worker<WorkerA, {}, Counter> is what makes Counter.from(WorkerA) type-check. You can still bind across scripts without it (the runtime works either way), but consumers will get a TypeScript error because WorkerA doesn’t declare Counter as part of its public contract.

Only the host Worker’s Stack provides CounterLive — the consumer Worker just imports the Counter class as a typed identifier. Rolldown tree-shakes CounterLive (and its dependencies) out of WorkerB’s bundle.

Using .from(Self) Inside the Host

Inside the host Worker, yield* Counter and yield* Counter.from(Self) resolve to the same local namespace. The .from(Self) form is preferred — especially in code that may be extracted into a reusable Layer — because it makes the scriptName explicit and lets the same Layer shape work whether the consumer is the host or another script.

Counter.from(WorkerA) inside WorkerA itself

// workerA.ts — host uses `.from(Self)` instead of bare `yield* Counter`
export default WorkerA.make(
  Effect.gen(function* () {
    const counter = yield* Counter.from(WorkerA); // same as `yield* Counter`
    return { fetch: Effect.gen(function* () { ... }) };
  }).pipe(Effect.provide(CounterLive)),
);

A Worker can also host its own isolated namespace this way. If a second host Worker declares Counter in its contract and provides CounterLive, the DO instances under that script are separate from the original host’s — same class, two namespaces.

Two hosts, two isolated namespaces

// workerC.ts — another host of Counter, isolated from WorkerA
export class WorkerC extends Cloudflare.Worker<WorkerC, {}, Counter>()(
  "WorkerC",
  { main: import.meta.filename },
) {}

export default WorkerC.make(
  Effect.gen(function* () {
    // .from(WorkerC) binds to WorkerC's own Counter namespace —
    // writes here are NOT visible from WorkerA's Counter.
    const counter = yield* Counter.from(WorkerC);
    return { fetch: Effect.gen(function* () { ... }) };
  }).pipe(Effect.provide(CounterLive)),
);

RPC Methods

Any function you return from the inner Effect becomes an RPC method that Workers can call through a stub. Methods must return an Effect. The caller gets a fully typed stub — if your DO returns increment and get, the stub exposes counter.increment() and counter.get().

return {
  increment: () => Effect.succeed(++count),
  get: () => Effect.succeed(count),
  reset: () => Effect.sync(() => { count = 0; }),
};

Returning Streams from RPC

RPC methods can return an Effect Stream and the caller will see the chunks as they’re produced. Combine with Stream.schedule to pace emission, or with Stream.fromQueue to bridge an inbound subscription.

Streaming sequential numbers

import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";

return {
  tick: (n: number) =>
    Stream.iterate(0, (i) => i + 1).pipe(
      Stream.take(n),
      Stream.schedule(Schedule.spaced("100 millis")),
    ),
};

Forwarding the stream as a chunked HTTP response

// in a Worker fetch handler
const counter = counters.getByName("tick");
const stream = counter.tick(5).pipe(
  Stream.map((i) => `${i}\n`),
  Stream.encodeText,
);
return HttpServerResponse.stream(stream, {
  headers: { "content-type": "text/plain" },
});

Worker → DO HTTP forwarding

In addition to RPC methods, the typed stub exposes a fetch method that forwards an HttpServerRequest straight to the DO. The DO’s own fetch Effect produces the response — useful for WebSocket upgrades and other request-shaped interactions.

const room = rooms.getByName(roomId);
return yield* room.fetch(request);

Accessing Instance State

Each Durable Object instance has its own transactional key-value storage via Cloudflare.DurableObjectState. Use storage.get and storage.put inside the inner Effect to persist data across requests and restarts.

const state = yield* Cloudflare.DurableObjectState;

yield* state.storage.put("counter", 42);
const value = yield* state.storage.get("counter");

WebSocket Hibernation

Durable Objects support WebSocket hibernation — the runtime can evict the object from memory while keeping connections open. Use Cloudflare.upgrade() to accept a connection, and return webSocketMessage / webSocketClose handlers to process events when the object wakes back up.

Accepting a WebSocket connection

return {
  fetch: Effect.gen(function* () {
    const [response, socket] = yield* Cloudflare.upgrade();
    socket.serializeAttachment({ id: crypto.randomUUID() });
    return response;
  }),
};

Handling messages and close events

return {
  webSocketMessage: Effect.fnUntraced(function* (
    socket: Cloudflare.DurableWebSocket,
    message: string | Uint8Array,
  ) {
    const text = typeof message === "string"
      ? message
      : new TextDecoder().decode(message);
    // process the message
  }),
  webSocketClose: Effect.fnUntraced(function* (
    ws: Cloudflare.DurableWebSocket,
    code: number,
    reason: string,
  ) {
    yield* ws.close(code, reason);
  }),
};

Recovering sessions after hibernation

Place the rehydration loop inside the inner Effect.gen so it runs every time the DO instance is reconstructed (including after Cloudflare wakes the DO from hibernation).

return Effect.gen(function* () {
  const state = yield* Cloudflare.DurableObjectState;
  const sessions = new Map<string, Cloudflare.DurableWebSocket>();

  // Rehydrate the in-memory session map after hibernation.
  for (const socket of yield* state.getWebSockets()) {
    const data = socket.deserializeAttachment<{ id: string }>();
    if (data) sessions.set(data.id, socket);
  }

  return {
    fetch: Effect.gen(function* () {
      const [response, socket] = yield* Cloudflare.upgrade();
      const id = crypto.randomUUID();
      socket.serializeAttachment({ id });
      sessions.set(id, socket);
      return response;
    }),
    webSocketMessage: Effect.fnUntraced(function* (socket, message) {
      const text =
        typeof message === "string" ? message : new TextDecoder().decode(message);
      for (const peer of sessions.values()) {
        yield* peer.send(text);
      }
    }),
  };
});

Scheduled Alarms

Each Durable Object can have a single alarm timestamp. Alchemy layers a small SQLite-backed scheduler on top via Cloudflare.scheduleEvent and Cloudflare.processScheduledEvents, so you can register many named events with arbitrary payloads and fire them from a single alarm handler.

// schedule from a request or message handler
yield* Cloudflare.scheduleEvent(
  "reminder-1",
  new Date(Date.now() + 60_000),
  { message: "your meeting starts in a minute" },
);

return {
  alarm: () =>
    Effect.gen(function* () {
      const fired = yield* Cloudflare.processScheduledEvents;
      for (const event of fired) {
        const payload = event.payload as { message: string };
        // dispatch / broadcast / persist...
      }
    }),
};

Using from a Worker

Yield the DO class in your Worker’s init phase to get a namespace handle. Call getByName or getById to get a typed stub, then call any RPC method or forward an HTTP request with fetch.

Calling RPC methods

// init
const counters = yield* Counter;

return {
  fetch: Effect.gen(function* () {
    const counter = counters.getByName("user-123");
    yield* counter.increment();
    const value = yield* counter.get();
    return HttpServerResponse.text(String(value));
  }),
};

Forwarding an HTTP request

// init
const rooms = yield* Room;

return {
  fetch: Effect.gen(function* () {
    const request = yield* HttpServerRequest;
    const room = rooms.getByName(roomId);
    return yield* room.fetch(request);
  }),
};

Binding in an Async Worker

When using an Async Worker (plain async fetch handler, no Effect runtime), declare Durable Objects in the bindings prop of the Worker resource. Pass a DurableObjectNamespace reference with a className matching the exported DurableObject subclass in your worker source file. If className is omitted, it defaults to the namespace name. Use Cloudflare.InferEnv to get a fully typed env object that includes the namespace.

Declaring a DO binding in the stack

alchemy.run.ts

import type { Counter } from "./src/worker.ts";

export type WorkerEnv = Cloudflare.InferEnv<typeof Worker>;

export const Worker = Cloudflare.Worker("Worker", {
  main: "./src/worker.ts",
  bindings: {
    Counter: Cloudflare.DurableObjectNamespace<Counter>("Counter"),
  },
});

Using the DO from a plain async handler

src/worker.ts

import { DurableObject } from "cloudflare:workers";
import type { WorkerEnv } from "../alchemy.run.ts";

export default {
  async fetch(request: Request, env: WorkerEnv) {
    const counter = env.Counter.getByName("my-counter");
    const count = await counter.increment();
    return new Response(JSON.stringify({ count }));
  },
};

export class Counter extends DurableObject {
  private counter = 0;
  async increment() {
    return ++this.counter;
  }
}

Cross-Script Binding in an Async Worker

Async Workers can also bind to a Durable Object hosted by another Worker script. The host Worker declares and exports the DO class. The consumer Worker declares a DurableObjectNamespace with scriptName set to the host Worker’s script name.

Cross-script async bindings are references only: the consumer uploads the binding metadata, but Alchemy does not drive class migrations for the foreign class. Deploy the host first so Cloudflare can verify that the target script exports the requested class.

Host Worker owns the Durable Object class

const host = yield* Cloudflare.Worker("Host", {
  main: "./src/host.ts",
  bindings: {
    Counter: Cloudflare.DurableObjectNamespace<Counter>("Counter"),
  },
});

Consumer Worker binds to the host script

const consumer = yield* Cloudflare.Worker("Consumer", {
  main: "./src/consumer.ts",
  bindings: {
    Counter: Cloudflare.DurableObjectNamespace<Counter>("Counter", {
      scriptName: host.workerName,
    }),
  },
});

Binding to a different exported class name

const consumer = yield* Cloudflare.Worker("Consumer", {
  main: "./src/consumer.ts",
  bindings: {
    Counter: Cloudflare.DurableObjectNamespace<Counter>("Counter", {
      className: "CounterV2",
      scriptName: host.workerName,
    }),
  },
});