Skip to content

Realtime SSE

Server-sent events — live updates without F5.

  • Entity writes that fan out over SSE
  • Client subscription shape for live lists
  • Presence: createPresenceFeature({ entities: ["message"] }) answers who else has a message open; the heartbeat is a write, the others get an SSE frame addressed to their user id (no names inside)

Feature entry point: src/feature.ts.

Needs the Postgres from the repo root’s docker-compose.yml (docker compose up -d); TEST_DATABASE_URL defaults to postgresql://kumiko:kumiko@localhost:15432/kumiko_test.

Terminal window
cd samples/recipes/realtime-sse
bun test

The feature entry point — embedded straight from the source file, so the code here is exactly what runs. Multi-file samples keep their remaining files next to it on GitHub (link below):

import { createPresenceFeature } from "@cosmicdrift/kumiko-bundled-features/presence";
import {
createEntity,
createTextField,
defineEntityDeleteHandler,
defineFeature,
} from "@cosmicdrift/kumiko-framework/engine";
export const messageEntity = createEntity({
name: "message",
table: "read_sample_messages",
fields: {
channel: createTextField({ personal: false, reason: "is_business_data", required: true }),
text: createTextField({ personal: { of: "id" }, find: "none", required: true }),
author: createTextField({ personal: { of: "id" }, find: "none" }),
},
softDelete: true,
});
const userWrite = { access: { roles: ["Admin", "User"] } } as const;
const adminWrite = { access: { roles: ["Admin"] } } as const;
export const chatFeature = defineFeature("chat", (r) => {
r.crud(messageEntity, {
write: userWrite,
verbs: { list: false, detail: false, restore: false, delete: false },
});
r.writeHandler(defineEntityDeleteHandler("message", messageEntity, adminWrite));
});
// Who else has a message open. The heartbeat is an ordinary write; the others learn about a
// change through an SSE frame addressed to them (`presence:event:changed`, no names inside),
// then refetch with `usePresence` / `usePresenceList` on the client.
export const presenceFeature = createPresenceFeature({
entities: ["message"],
roles: ["Admin", "User"],
});

📄 On GitHub: samples/recipes/realtime-sse/src/feature.ts