realtime-client

轻量、零依赖的匿名 SSE 实时订阅客户端，用于订阅服务端推送的自定义消息。

内置连接状态机：连接排队与合并、超时检测、自动重连、订阅队列合并与去重、乐观更新、自动取消旧订阅请求。

安装

当前并未发布到npm，请直接下载源码拷贝到项目中使用。

用法

import { RealtimeClient } from 'realtime-client'

const realtime = new RealtimeClient('http://localhost:8090')

// 订阅消息（topic 可为通配/记录 id/任意自定义主题）
await realtime.subscribe('orders/*', (data) => {
    console.log(data)
})

// 取消订阅（移除该 topic 的所有回调；不传 topic 移除全部）
await realtime.unsubscribe('orders/*')

// 连接状态与钩子
console.log(realtime.isConnected)
realtime.onDisconnect = (activeSubscriptions) => {
    console.log('disconnected:', activeSubscriptions)
}

API

成员	说明
new RealtimeClient(baseURL)	创建实例，baseURL 为服务端基础地址
subscribe(topic, callback)	订阅消息，返回 Promise<void>；同一 topic 允许多个回调
unsubscribe(topic?)	取消订阅；不传 topic 时移除全部
isConnected	连接是否已建立（只读）
onDisconnect	断连钩子，参数为当前订阅 topic 数组
clientId	当前连接 id（空字符串表示未连接）

协议约定

与服务端建立 SSE 连接时需要遵循以下握手约定（这些是服务端协议约束，不可更改）：

• GET /api/realtime 建立 SSE 连接
• 服务端连接建立后发送 PB_CONNECT 事件，其 SSE id 字段为 clientId
• POST /api/realtime，body 为 { "clientId": "...", "subscriptions": ["..."] } 提交/更新订阅
• 服务端断连后需重新建立连接并重新提交全部订阅（客户端已自动处理）

环境要求

浏览器原生支持 EventSource、fetch、AbortController、queueMicrotask，无运行时依赖。 在 Node.js 中使用时需要为 EventSource 提供 polyfill。

License

MIT