@blocksight/chat-state-convex

A Convex component that backs the Vercel Chat SDK's StateAdapter with a Convex table — key-value entries, lists, distributed locks, per-thread queues, and subscriptions, all in one isolated chat_state table.

Install

npm install @blocksight/chat-state-convex

convex (^1.24.8) and chat (^4.0.0) are peer dependencies.

Setup

Register the component in convex/convex.config.ts:

import chatStateConvex from "@blocksight/chat-state-convex/convex.config.js";
import { defineApp } from "convex/server";

const app = defineApp();
app.use(chatStateConvex);

export default app;

Usage

Construct ConvexStateAdapter inside a Convex action, passing the action context and the components.chatStateConvex handle:

import { ConvexStateAdapter } from "@blocksight/chat-state-convex";
import { components } from "./_generated/api";
import { action } from "./_generated/server";

export const handleMessage = action({
  handler: async (ctx) => {
    const adapter = new ConvexStateAdapter(ctx, components.chatStateConvex);
    // pass `adapter` to the Chat SDK
  },
});

Expiry sweep

Convex has no native TTL. Entries written with a ttlMs are filtered out on read, but expired rows must be deleted by a cron.

First, add an internal mutation that delegates to the component's sweepExpired. In convex/chatStateSweep.ts:

import { components } from "./_generated/api";
import { internalMutation } from "./_generated/server";

export const run = internalMutation({
  args: {},
  handler: async (ctx) => {
    await ctx.runMutation(components.chatStateConvex.store.sweepExpired, {});
  },
});

Then schedule it in convex/crons.ts:

import { cronJobs } from "convex/server";
import { internal } from "./_generated/api";

const crons = cronJobs();
crons.interval(
  "chat-state-sweep",
  { minutes: 15 },
  internal.chatStateSweep.run
);

export default crons;

API

All functions live under components.chatStateConvex.store:

| Function | Purpose | | --- | --- | | getValue / setValue / deleteValue | key-value entries | | setValueIfAbsent | conditional write | | appendValue / listValue | append-only lists | | acquireLock / releaseLock / extendLock / forceReleaseLock | per-thread distributed locks | | enqueue / dequeue / queueDepth | per-thread queues | | subscribeThread / unsubscribeThread / threadSubscribed | thread subscriptions | | sweepExpired | delete expired rows (cron target) |

License

MIT