fetch-stream-reader/README.md

A lightweight client for reading streaming HTTP responses using Fetch and ReadableStream.

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

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

## 📦 安装
```bash
# 使用 pnpm
pnpm add fetch-stream-reader

# 使用 npm
npm install fetch-stream-reader

# 使用 yarn
yarn add fetch-stream-reader
```

## 🔧 使用示例
```ts
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**