chat-state-cloudflare-kv

Cloudflare Workers KV state adapter for Chat SDK.

Warning: This adapter is primarily for development and testing. It can be more durable than pure in-memory state because KV persists data, but KV consistency and locking semantics are still best-effort and not ideal for strict production concurrency guarantees.

Installation

npm install chat chat-state-cloudflare-kv

Usage

import { Chat } from "chat";
import { createCloudflareKVState, WorkerKvClient } from "chat-state-cloudflare-kv";

const kv = new WorkerKvClient({
  accountId: CF_ACCOUNT_ID,
  apiToken: CF_API_TOKEN,
  namespaceId: CF_KV_NAMESPACE_ID
});

const bot = new Chat({
  userName: "my-bot",
  adapters: {
    // your platform adapters here
  },
  state: createCloudflareKVState({ kv })
});

Configuration

createCloudflareKVState accepts:

• kv (KVNamespace-compatible object, required): Cloudflare Worker KV binding
• keyPrefix (string, optional, default: "chat-sdk"): key namespace prefix
• ttlMinutes (number, optional, default: 360): default TTL in minutes used for cache writes (set and setIfNotExists) when no per-call TTL is provided
• logger (Logger, optional): custom logger

Features

| Feature | Supported | | --- | --- | | Persistence | Yes (Cloudflare KV-backed) | | Multi-instance | Yes (eventual consistency) | | Subscriptions | Yes (persistent via KV) | | Locking | Yes (best-effort, KV semantics) | | Queue/debounce primitives | Yes | | List-backed message history | Yes | | Key-value caching | Yes (get / set / delete / setIfNotExists) |

Recommended usage

• Local development
• Integration testing
• Prototyping and low-contention workloads

Notes on KV semantics

Cloudflare KV does not support strict atomic compare-and-set operations. This adapter preserves the Chat SDK state adapter API and uses best-effort ownership verification for locks and conditional writes.

For stricter lock guarantees under heavy concurrent write contention, use a production state adapter.

Development

npm run test
npm run build