Primitives

Events

Typed publishes, stored before they're delivered, replayed exactly after a drop.

An event is a name and JSON data, published to a channel. Every event gets the channel's next sequence number and is stored before anyone receives it, so delivery is in order, and a client that reconnects gets exactly what it missed, once.

Define a schema

One schema types your events (and presence) on the server and in the browser. Any Standard Schema library works: Zod, Valibot, ArkType. Without a schema, data is typed as JSON.

schema.ts
typescript
import { defineSchema } from "@anishroy/pulse"import { z } from "zod"
export const STEPS = ["placed", "preparing", "shipped", "delivered"] as const
export const schema = defineSchema({ events: { "order.status": z.object({ orderId: z.string(), status: z.enum(STEPS) }), "chat.message": z.object({ text: z.string().max(2000) }), },})

Publish from your server

server.ts
typescript
import { Pulse } from "@anishroy/pulse/server"import { schema } from "./schema"
const rt = new Pulse({ schema })
// Validated against the schema before it leaves your serverconst { seq } = await rt.publish("orders:42", "order.status", { orderId: "42", status: "shipped",})
// Several in one call, stored and delivered togetherawait rt.publish("orders:42", [ { name: "order.status", data: { orderId: "42", status: "delivered" } }, { name: "chat.message", data: { text: "Enjoy!" } },])

Or over HTTP, from anything that can send a request:

Terminal
bash
curl -X POST $PULSE_URL/v1/channels/orders:42/events \  -H "Authorization: Bearer $PULSE_SECRET_KEY" \  -H "Content-Type: application/json" \  -d '{ "name": "order.status", "data": { "orderId": "42", "status": "shipped" } }'
# Several at once: { "events": [{ "name": …, "data": … }, …] }

Read in the browser

order.tsx
tsx
import { useEvent } from "@anishroy/pulse/react"
function OrderStatus({ id }: { id: string }) { // The latest data, typed by the schema; undefined until the first event const order = useEvent(`orders:${id}`, "order.status")
// Or act on every event, replayed ones included useEvent(`orders:${id}`, "order.status", (data, meta) => { if (!meta.replay) toast(`Order ${data.status}`) })
return <p>{order?.status ?? "Waiting…"}</p>}

meta has the event's seq, its time ts, the publishing user (absent for server publishes) and replay, true while catching up. Without React, the client has the same thing:

anywhere.ts
typescript
import { createClient } from "@anishroy/pulse/client"
const client = createClient({ url: PULSE_URL, auth: "/api/pulse/token", schema })const orders = client.channel("orders:42", { history: true })
const stop = orders.on("order.status", (data, meta) => { console.log(meta.seq, data.status)})

Publish from the browser

A browser can publish to channels its token lists under `publish`. When the client has the schema, data is validated before it is sent; publishes made while offline are queued.

chat.tsx
tsx
const { status, publish } = useChannel(`chat:${room}`)
await publish("chat.message", { text }) // needs `publish` in the token

History and replay

  • Live by default: a client receives events from the moment it joins.
  • history: true replays everything the channel still keeps, then goes live. A number resumes after that sequence number.
  • A client that drops resumes from its last sequence number on its own, whether it was gone for three seconds or three hours.

Channels keep 24 hours of events by default. Set retention per channel, up to 7 days and 100,000 events, from your server or the dashboard:

server.ts
typescript
await rt.configure("orders:42", {  retention: { maxAgeSeconds: 7 * 86400, maxEvents: 50_000 },})

Gaps

If a client was away longer than the channel keeps, it gets an explicit gap, never partial history, so your app can reload its state instead of showing a hole:

order.tsx
tsx
useChannel(`orders:${id}`, { onGap: () => reloadOrder(id) })

Your server can read history the same way. gap is true when since is older than what's kept; pass next as since to read on.

server.ts
typescript
const { events, next, gap } = await rt.read("orders:42", { since: 120 })

Limits

  • Up to 1 MB of JSON per event.
  • Event names use letters, digits and _ - : ., like order.status.