chat-state-cloudflare-do

Cloudflare Durable Objects state adapter for Chat SDK. Uses a SQLite-backed Durable Object for persistent subscriptions, distributed locking, and caching — with zero external dependencies beyond the Workers runtime.

Installation

npm install chat chat-state-cloudflare-do

Usage

import { Chat } from "chat";import { createSlackAdapter } from "@chat-adapter/slack";import { createCloudflareState, ChatStateDO } from "chat-state-cloudflare-do";// Re-export the Durable Object class so Cloudflare can find itexport { ChatStateDO };export default {  async fetch(request: Request, env: Env) {    const bot = new Chat({      userName: "my-bot",      adapters: { slack: createSlackAdapter() },      state: createCloudflareState({ namespace: env.CHAT_STATE }),    });    return bot.webhooks.slack(request);  },};

Wrangler configuration

Add the Durable Object binding and migration to your wrangler.jsonc (recommended) or wrangler.toml:

wrangler.jsonc (recommended)

{  "durable_objects": {    "bindings": [      { "name": "CHAT_STATE", "class_name": "ChatStateDO" }  },  "migrations": [    { "tag": "v1", "new_sqlite_classes": ["ChatStateDO"] }}

wrangler.toml

[durable_objects]bindings = [  { name = "CHAT_STATE", class_name = "ChatStateDO" }[[migrations]]tag = "v1"new_sqlite_classes = ["ChatStateDO"]

Environment type

import type { ChatStateDO } from "chat-state-cloudflare-do";interface Env {  CHAT_STATE: DurableObjectNamespace<ChatStateDO>;}

Configuration

Sharding

A single Durable Object handles approximately 500-1,000 requests per second. For high-traffic bots, use shardKey to distribute load across multiple DO instances:

const state = createCloudflareState({  namespace: env.CHAT_STATE,  shardKey: (threadId) => threadId.split(":")[0], // One DO per platform});

Locks and subscriptions are per-thread, so sharding by any prefix of the thread ID is safe. Cache operations (get/set/delete) always route to the default shard since their keys are not thread-scoped.

Architecture

The adapter uses a single Durable Object class (ChatStateDO) with three SQLite tables:

• subscriptions — thread IDs the bot is subscribed to
• locks — distributed locks with token-based ownership and TTL
• cache — key-value pairs with optional TTL

All operations are single-threaded within a DO instance, providing distributed locking via DO atomicity rather than Lua scripts. Expired entries are cleaned up automatically via the Alarms API.

Each method call creates a fresh DO stub. Stubs are cheap (just a JS object) and the Cloudflare docs recommend creating new stubs rather than reusing them after errors.

Features

• Persistent subscriptions across deployments
• Distributed locking via single-threaded DO atomicity
• Key-value caching with TTL
• Automatic TTL cleanup via Alarms
• Optional sharding for high-traffic bots
• Location hints for latency optimization
• Zero external dependencies (no Redis, no database)

Production recommendations

• Use Smart Placement to co-locate your Worker with the DO
• Monitor DO metrics in the Cloudflare dashboard
• Enable sharding if you expect >500 req/s to a single DO instance
• Use locationHint to place the DO near your primary user base

Documentation

• npm package
• Chat SDK docs
• State adapters overview
• Cloudflare Durable Objects

License

MIT