fetch-stream-reader

一个轻量级的客户端，基于 fetch() 与 ReadableStream，用于处理流式 HTTP 响应数据。

✨ 功能特点

基于原生 fetch 和 ReadableStream 构建
支持分块 HTTP 响应处理（如 SSE、AI Token 流、JSON 行）
简洁的事件驱动 API（支持 on / off / emit 方法）
类型安全、可扩展、零依赖
适用于实时应用、后台任务进度、服务器推送、AI 流式响应等场景

📦 安装

# 使用 pnpm
pnpm add fetch-stream-reader

# 使用 npm
npm install fetch-stream-reader

# 使用 yarn
yarn add fetch-stream-reader

🔧 使用示例

import FetchStreamReader from 'fetch-stream-reader'

const client = new FetchStreamReader('https://api.example.com/stream', {
  Authorization: 'Bearer token'
})

client.on('stream-start', () => {
  console.log('开始建立连接和读取流')
})

client.on('stream-message', ({ detail }) => {
  console.log('收到数据:', detail)
})

client.on('stream-error', ({ detail }) => {
  console.log('流错误:', detail.error)
})

client.on('stream-end', () => {
  console.log('流已结束')
})

client.on('stream-abort', () => {
  console.log('流已被中止')
})

// 发送请求并建立流连接。
await client.start({ prompt: 'Hello' })

🧩 支持的事件

事件名称	描述
`stream-start`	已成功建立连接并开始读取流数据时触发
`stream-message`	每接收到一条完整且可解析的数据时触发（通常为 JSON 对象）
`stream-error`	请求失败或数据解析错误时触发，`detail` 包含原始数据和错误信息
`stream-end`	流被服务端正常关闭时触发
`stream-abort`	客户端主动调用 `stop()` 手动中止连接时触发

🧪 示例场景

📈 实时图表：将服务端推送的数据直接展示在前端图表中
⏱️ 长任务进度追踪：从后端持续接收处理进度
🧠 AI 模型输出：读取如 OpenAI API 的增量响应文本流
📣 即时通知：基于服务端推送事件（SSE）构建通知系统
🔄 数据同步：接收远程更新事件并应用本地变更

🛠️ API 文档

`new FetchStreamReader(url: string, headers?: Record<string, string>)`

创建流式读取器实例。

参数	类型	描述
`url`	`string`	接口地址（必须为 POST 请求地址）
`headers`	`Record<string, string>`	可选的请求头（如认证）

`start(payload: object): Promise<void>`

发送请求并建立流连接。

`on(eventName: string, handler: (event: CustomEvent) => void)`

注册事件监听器。

`off(eventName: string, handler?: (event: CustomEvent) => void)`

移除事件监听器。

`stop(): void`

中止当前流连接，并清理相关资源。

🧠 最后

如果你正好在构建一个流式通信的 Web 项目，希望 fetch-stream-reader 能帮你少写点重复代码，多专注于用户体验。

如果你在使用过程中遇到问题，或者对 fetch-stream-reader 感兴趣，欢迎一起交流探讨。