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 感兴趣，欢迎一起交流探讨。

📬 可加微信（备注 “npm + 昵称”）：g_adiu