Durable Objects

import { DurableObject } from "cloudflare:workers";
import type { Env } from "./worker";
 
export class Counter extends DurableObject<Env> {
  // Public methods are callable over RPC from the stub.
  async increment(by = 1): Promise<number> {
    const kv = this.ctx.storage.kv; // synchronous, SQLite
    const n = (kv.get<number>("n") ?? 0) + by;
    kv.put("n", n);
    return n; // held until the write is durable
  }
 
  async current(): Promise<number> {
    return this.ctx.storage.kv.get<number>("n") ?? 0;
  }
}

import { Counter } from "../counter";
 
export { Counter }; // every DO class is exported from main
 
export interface Env {
  COUNTER: DurableObjectNamespace<Counter>;
}
 
export default {
  async fetch(req, env): Promise<Response> {
    const name = new URL(req.url).searchParams.get("c");
    if (!name) return new Response("?c=", { status: 400 });
    // Same name -> same object, from any Worker, anywhere.
    const counter = env.COUNTER.getByName(name);
    const n = await counter.increment(); // RPC: always await
    return Response.json({ name, n });
  },
} satisfies ExportedHandler<Env>;

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "chat",
  "main": "src/worker.ts",
  "compatibility_date": "2026-09-01",
  "durable_objects": {
    "bindings": [
      { "name": "CHAT", "class_name": "ChatRoom" }
    ]
  },
  // Declarative class lifecycle (replaces "migrations").
  "exports": {
    "ChatRoom": {
      "type": "durable-object",
      "storage": "sqlite"
    }
  }
}

{
  // ...name, main, compatibility_date, durable_objects
  // Append a new tagged entry per change; never edit one.
  "migrations": [
    { "tag": "v1", "new_sqlite_classes": ["ChatRoom"] },
    { "tag": "v2", "new_sqlite_classes": ["Limiter"] }
  ]
}

import { DurableObject } from "cloudflare:workers";
import type { Env } from "./worker";
 
type Note = { id: number; body: string; at: number };
 
// Schema migrations, append-only, applied in order.
const MIGRATIONS = [
  `CREATE TABLE notes (
     id INTEGER PRIMARY KEY,
     body TEXT NOT NULL,
     at INTEGER NOT NULL)`,
  "CREATE INDEX notes_at ON notes (at)",
];
 
export class Notes extends DurableObject<Env> {
  sql: SqlStorage;
 
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    this.sql = ctx.storage.sql;
    const kv = ctx.storage.kv;
    const done = kv.get<number>("schema") ?? 0;
    // Synchronous, so no request can run in between.
    ctx.storage.transactionSync(() => {
      for (const m of MIGRATIONS.slice(done)) {
        this.sql.exec(m);
      }
      kv.put("schema", MIGRATIONS.length);
    });
  }
 
  async add(body: string): Promise<number> {
    return this.sql.exec<{ id: number }>(
      `INSERT INTO notes (body, at) VALUES (?, ?)
       RETURNING id`,
      body,
      Date.now(),
    ).one().id; // one() throws unless exactly one row
  }
 
  async recent(limit: number): Promise<Note[]> {
    return this.sql.exec<Note>(
      "SELECT * FROM notes ORDER BY id DESC LIMIT ?",
      limit,
    ).toArray(); // consume the cursor before any await
  }
 
  async stats() {
    const c = this.sql.exec<{ n: number }>(
      "SELECT COUNT(*) AS n FROM notes",
    );
    const { n } = c.one();
    const rows = [
      ...this.sql.exec("SELECT id, body FROM notes").raw(),
    ]; // [[1, "hello"], ...]
    return {
      n,
      first: rows[0],
      rowsRead: c.rowsRead, // billed
      bytes: this.sql.databaseSize,
    };
  }
}

import { DurableObject } from "cloudflare:workers";
import type { Env } from "./worker";
 
type Job = { id: number; what: string; due: number };
 
// One alarm per object: keep a queue in SQL and always
// arm the alarm for the earliest job.
export class Reminders extends DurableObject<Env> {
  sql: SqlStorage;
 
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    this.sql = ctx.storage.sql;
    this.sql.exec(`CREATE TABLE IF NOT EXISTS jobs (
      id INTEGER PRIMARY KEY, what TEXT, due INTEGER)`);
  }
 
  async schedule(what: string, due: number) {
    this.sql.exec(
      "INSERT INTO jobs (what, due) VALUES (?, ?)",
      what,
      due,
    );
    await this.arm();
  }
 
  async pending(): Promise<Job[]> {
    return this.sql
      .exec<Job>("SELECT * FROM jobs ORDER BY due")
      .toArray();
  }
 
  async alarm(info?: AlarmInvocationInfo) {
    const due = this.sql.exec<Job>(
      "SELECT * FROM jobs WHERE due <= ?",
      Date.now(),
    ).toArray();
    for (const job of due) {
      // At-least-once: must be safe to run twice.
      console.info("run", job.what, info?.retryCount);
      this.sql.exec("DELETE FROM jobs WHERE id = ?", job.id);
    }
    await this.arm();
  }
 
  private async arm() {
    const { due } = this.sql.exec<{ due: number | null }>(
      "SELECT MIN(due) AS due FROM jobs",
    ).one();
    if (due === null) await this.ctx.storage.deleteAlarm();
    else await this.ctx.storage.setAlarm(due);
  }
}

import { DurableObject } from "cloudflare:workers";
import type { Env } from "./worker";
 
type Att = { user: string; joinedAt: number };
 
// Hibernation API: the runtime owns the sockets, so the
// object can leave memory while clients stay connected.
export class Presence extends DurableObject<Env> {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env); // re-runs after every wake: keep cheap
    ctx.setWebSocketAutoResponse(
      new WebSocketRequestResponsePair("ping", "pong"),
    );
  }
 
  async fetch(req: Request): Promise<Response> {
    const url = new URL(req.url);
    const user = url.searchParams.get("user"); // demo only
    if (!user) return new Response("user?", { status: 400 });
    const { 0: client, 1: server } = new WebSocketPair();
    this.ctx.acceptWebSocket(server, [`user:${user}`]);
    const att: Att = { user, joinedAt: Date.now() };
    server.serializeAttachment(att); // survives hibernation
    this.broadcast(`+${user}`);
    return new Response(null, {
      status: 101,
      webSocket: client,
    });
  }
 
  async webSocketMessage(
    ws: WebSocket,
    msg: string | ArrayBuffer,
  ) {
    if (typeof msg !== "string") return;
    const { user } = ws.deserializeAttachment() as Att;
    const dm = /^@(\S+) (.+)$/.exec(msg);
    if (!dm) return this.broadcast(`${user}: ${msg}`);
    // A tag finds one user's sockets (all their tabs).
    const to = this.ctx.getWebSockets(`user:${dm[1]}`);
    for (const s of to) s.send(`${user} (dm): ${dm[2]}`);
  }
 
  async webSocketClose(ws: WebSocket, code: number) {
    const { user } = ws.deserializeAttachment() as Att;
    this.broadcast(`-${user}`, ws);
  }
 
  private broadcast(text: string, skip?: WebSocket) {
    for (const s of this.ctx.getWebSockets()) {
      if (s !== skip) s.send(text);
    }
  }
}

import {
  Server,
  type Connection,
  type ConnectionContext,
  type WSMessage,
} from "partyserver";
import type { Env } from "./worker";
 
// PartyServer: Durable Object + rooms + hooks. Binding
// PARTY is reachable at /parties/party/:room.
export class Party extends Server<Env> {
  static options = { hibernate: true };
 
  onStart() {
    this.sql`CREATE TABLE IF NOT EXISTS log (msg TEXT)`;
  }
 
  onConnect(conn: Connection, ctx: ConnectionContext) {
    const n = [...this.getConnections()].length;
    conn.send(`welcome to ${this.name}, ${n} here`);
  }
 
  onMessage(conn: Connection, message: WSMessage) {
    if (typeof message !== "string") return;
    this.sql`INSERT INTO log (msg) VALUES (${message})`;
    this.broadcast(message, [conn.id]); // all but sender
  }
}

import { PartySocket } from "partysocket";
 
async function getToken(): Promise<string> {
  const r = await fetch("/api/chat-token", {
    method: "POST",
  });
  return ((await r.json()) as { token: string }).token;
}
 
// Reconnects with backoff and buffers sends while offline.
const socket = new PartySocket({
  host: "party.example.workers.dev", // default: page host
  party: "party", // binding PARTY, kebab-cased
  room: "lobby", // -> /parties/party/lobby
  query: async () => ({ token: await getToken() }),
});
 
socket.addEventListener("message", (e: MessageEvent) => {
  console.info(e.data);
});
socket.send("hello");

import { DurableObject } from "cloudflare:workers";
import type { Env } from "./worker";
 
const RATE = 5; // tokens per second
const BURST = 20;
 
// One object per user id: the limit is exact, and no
// single object sees every request.
export class Limiter extends DurableObject<Env> {
  async take(cost = 1): Promise<boolean> {
    const kv = this.ctx.storage.kv;
    const now = Date.now();
    const b = kv.get<{ tokens: number; at: number }>("b")
      ?? { tokens: BURST, at: now };
    const refill = ((now - b.at) / 1000) * RATE;
    const tokens = Math.min(BURST, b.tokens + refill);
    const ok = tokens >= cost;
    const left = ok ? tokens - cost : tokens;
    kv.put("b", { tokens: left, at: now });
    return ok;
  }
}

import { DurableObject } from "cloudflare:workers";
import type { Env } from "./worker";
 
const IDLE_MS = 7 * 24 * 60 * 60 * 1000;
 
// Rooms nobody visits for a week delete themselves.
export class Scratch extends DurableObject<Env> {
  async touch(): Promise<void> {
    // Each visit pushes the deadline back.
    await this.ctx.storage.setAlarm(Date.now() + IDLE_MS);
  }
 
  async alarm() {
    await this.ctx.storage.deleteAll(); // data + alarm
  }
 
  // Point-in-time recovery (SQLite-backed, last 30 days,
  // not in local dev): restore, then restart the object.
  async restore(msAgo: number): Promise<string> {
    const s = this.ctx.storage;
    const t = Date.now() - msAgo;
    const at = await s.getBookmarkForTime(t);
    const undo = await s.onNextSessionRestoreBookmark(at);
    this.ctx.abort("restoring"); // resets now
    return undo; // restore to this to roll back
  }
}

const url = "ws://localhost:8787/presence/lobby?user=";
const open = (user: string) =>
  new Promise<WebSocket>((resolve) => {
    const ws = new WebSocket(url + user);
    ws.onmessage = (e) => console.info(user, "<-", e.data);
    ws.onopen = () => resolve(ws);
  });
 
const ann = await open("ann");
const ben = await open("ben");
ann.send("ping"); // auto-response: never wakes the object
ann.send("hello all");
ann.send("@ben just you");
await Bun.sleep(300);
ben.close();
ann.close();