@mt-utils/mt-sse

@mt-utils/mt-sse 是一个用于处理服务器发送事件（Server-Sent Events，SSE）的 TypeScript 库，它提供了一个简单易用的接口来管理和监听来自服务器的事件。

特点

• 支持服务器发送事件（SSE）的客户端实现。
• 提供了详细的错误处理和状态码管理。
• 支持自定义请求头、请求方法和事件监听。
• 错误回调中包含错误代码，方便问题定位。

安装

使用 pnpm 安装：

pnpm install @mt-utils/mt-sse

使用方法

基本使用

import SSEClient from '@mt-utils/mt-sse'
import type { SSEClientOptions } from '@mt-utils/mt-sse'

/**
 * 配置选项，所有配置项都是可选的，并且有默认值
 */
const options: SSEClientOptions = {
  /**
   *  请求头,默认参数为{cache-control:no-cache,Connection:keep-alive,content-type:application/json,Language:zh}
   */
  headers: {
    /**
     * 指定请求和响应遵循的缓存机制,默认为no-cache
     */
    'cache-control': 'no-cache',
    /**
     * 指定连接是否应该在此次请求之后保持打开状态,默认为keep-alive
     */
    Connection: 'keep-alive',
    /**
     * 描述了主体部分的内容类型,默认为application/json
     */
    'content-type': 'application/json',
    /**
     * 用来指示资源的内容所用的语言,默认为ZH
     */
    Language: 'zh'
  },
  /**
   * 请求方法，默认为 POST
   * @default POST
   * @type string
   */
  method: 'POST'
}

/**
 * 创建一个 SSE 客户端实例
 */
const client = new SSEClient('https://yourserver.com/sse', options)

/**
 * 监听连接打开，SSE连接打开并且成功连接到服务器后触发；
 * 开始连接,回调参数为连接成功后的response
 */
client.on('start', (response) => {
  console.log('SSE connection opened', response)
})

/**
 * 监听接收消息
 * 接收到服务器返回的消息（返回对象type为112时触发）,回调参数为返回的数据对象
 */
client.on('message', (data) => {
  console.log('Received message:', data)
})

/**
 * 监听连接结束
 * 接收到最后一条数据（返回对象type为114时触发）,回调参数为返回的数据对象
 */
client.on('end', (data) => {
  console.log('SSE connection ended:', data)
})

/**
 * 监听连接异常
 * 连接错误,回调参数为SSEError对象
 */
client.on('error', (error) => {
  console.error(`SSE error: ${error.message}`)
})

/**
 * 连接关闭,每次正常连接完毕都会触发,无回调参数
 */
client.on('close', () => {
  console.log('SSE connection closed')
})

// 发送消息
client.send({ key: 'value' })

// 主动关闭 SSE 连接
client.closeSSE()

Options 配置

SSEClient 构造函数接受一个可选的 options 对象，允许你自定义连接的行为。所有配置项都是可选的，并且有默认值：

• headers: 自定义请求头，包含默认值，可以覆盖或扩展默认值。默认值：

  {
    'cache-control': 'no-cache',
    Connection: 'keep-alive',
    'content-type': 'application/json',
    Language: 'zh'
  }

• method: 请求方法，默认为 'POST'，可选 'GET', 'DELETE', 'PUT'。

事件监听

• start: 当SSE连接打开时触发。
• message: 当接收到消息时触发。
• end: 当接收到结束标记（状态码 114）时触发。
• error: 当发生错误时触发，错误对象包含 message 属性。
• close: 当SSE连接关闭时触发。

状态码

• NORMAL: 正常消息，状态码 112。
• BAN: 用户被禁用，状态码 100。
• END: 连接结束，状态码 114。

错误处理

错误处理通过 SSEError 类实现，它提供了不同的错误代码来表示不同的错误类型：

| 错误代码 | 描述 | | -------- | ---------------- | | 4001 | 浏览器不支持 SSE | | 4002 | SSE 执行错误 | | 4003 | SSE 连接错误 | | 4004 | 未知错误 | | 4005 | 用户被停用 |

注意

本库为内部工具库，仅供特定用途使用。在使用前，请确保你了解其用途和限制，并在遇到问题时寻求适当的支持。