Holly SSE

一个基于 Fetch API 和 ReadableStream 的 Server-Sent Events (SSE) 客户端库，使用 holly-fsm 进行状态管理。

特性

• ✅ 状态管理: 使用 holly-fsm 实现完善的连接状态管理
• ✅ TypeScript 支持: 完整的类型定义
• ✅ fetch + ReadableStream: 基于现代浏览器 API 的流式数据处理
• ✅ SSE 协议解析: 完整支持 data, event, id, retry 字段
• ✅ 事件驱动: 支持自定义事件监听和回调
• ✅ 自动重连: 支持配置重连策略和断点续传
• ✅ Last-Event-ID: 支持断线重连时恢复消息

安装

npm install holly-sse

快速开始

import { HollySSE, SSEState } from 'holly-sse';

// 创建 SSE 客户端实例
const sse = new HollySSE('http://localhost:3000/events', {
  // 自动重连配置
  autoReconnect: true,
  reconnectInterval: 3000,
  maxRetries: 5,
  
  // 状态变化回调
  onStateChange: (event) => {
    console.log(`状态变化: ${event.from} -> ${event.to}`);
  },
  
  // 连接成功
  onOpen: () => {
    console.log('连接已建立');
  },
  
  // 接收消息
  onMessage: (event) => {
    console.log('收到消息:', event.data);
  },
  
  // 错误处理
  onError: (event) => {
    console.error('连接错误:', event.error);
    console.log('是否重连:', event.willRetry);
  },
  
  // 连接关闭
  onClose: () => {
    console.log('连接已关闭');
  },
});

// 开始连接
await sse.start();

// 获取当前状态
console.log('当前状态:', sse.getState()); // SSEState.IDLE | SSEState.CONNECTING | SSEState.CONNECTED | SSEState.DISCONNECTING | SSEState.ERROR

// 停止连接
await sse.stop();

API

构造函数

new HollySSE(url: string, options?: HollySSEOptions)

HollySSEOptions

| 参数 | 类型 | 默认值 | 描述 | |------|------|--------|------| | headers | Record<string, any> | {} | 自定义请求头 | | method | string | 'GET' | HTTP 方法 | | payload | string | - | 请求体 | | withCredentials | boolean | false | 是否携带凭证 | | autoReconnect | boolean | true | 是否自动重连 | | reconnectInterval | number | 3000 | 重连间隔（毫秒）| | maxRetries | number | 5 | 最大重连次数 | | onStateChange | (event: SSEStateChangeEvent) => void | - | 状态变化回调 | | onMessage | (event: SSEMessageEvent) => void | - | 消息接收回调 | | onError | (event: SSEErrorEvent) => void | - | 错误回调 | | onOpen | () => void | - | 连接成功回调 | | onClose | () => void | - | 连接关闭回调 |

方法

start(): Promise<void>

开始 SSE 连接。

stop(): Promise<void>

停止 SSE 连接。

getState(): SSEStateValue

获取当前连接状态。

返回值: SSEState.IDLE | SSEState.CONNECTING | SSEState.CONNECTED | SSEState.DISCONNECTING | SSEState.ERROR

或字符串字面量: 'idle' | 'connecting' | 'connected' | 'disconnecting' | 'error'

状态机

Holly SSE 使用 holly-fsm 管理连接状态，支持以下状态转换：

idle ──connect──> connecting ──success──> connected
                      │                      │
                      │                      │
                     fail                 error
                      │                      │
                      └──> error <───────────┘
                            │
                         retry/abort
                            │
                           idle

状态说明

• idle: 初始状态，未连接
• connecting: 正在建立连接
• connected: 已成功连接，可以接收消息
• disconnecting: 正在断开连接
• error: 连接错误，可能会自动重连

事件类型

SSEStateChangeEvent

interface SSEStateChangeEvent {
  from: SSEState | SSEStateValue;  // 前一个状态
  to: SSEState | SSEStateValue;    // 当前状态
  action: string;                   // 触发状态变化的动作
  meta?: any;                       // 附加信息
}

SSEMessageEvent

interface SSEMessageEvent {
  data: string;    // 消息数据
  event?: string;  // 事件类型
  id?: string;     // 消息 ID
  retry?: number;  // 重连间隔
}

SSEErrorEvent

interface SSEErrorEvent {
  error: Error;      // 错误对象
  willRetry: boolean; // 是否会自动重连
}

快速测试

启动测试服务器

node examples/sse-server.js

运行客户端测试

npx ts-node examples/test-sse-client.ts

使用 curl 测试

curl -N http://localhost:3000/events

开发路线图

• [x] 基于 holly-fsm 的状态管理
• [x] 完整的 TypeScript 类型定义
• [x] 状态变化事件监听
• [x] 基于 Fetch + ReadableStream 的连接实现
• [x] SSE 消息解析（data, event, id, retry）
• [x] Last-Event-ID 断点续传支持
• [x] 自动重连机制
• [ ] 单元测试覆盖
• [ ] 浏览器兼容性测试

许可证

MIT

相关项目

• holly-fsm - 有限状态机库
• holly-emitter - 事件发射器库