sse-line-parser 0.0.1 → 0.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +188 -49
- package/README.zh-CN.md +137 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,21 +1,160 @@
|
|
|
1
1
|
# SSE Stream Parser
|
|
2
2
|
|
|
3
|
+
A **lightweight, pure, production-ready SSE (Server-Sent Events) stream parser**, implemented based on the standard SSE protocol. It is independent of specific application scenarios and can be widely used in various SSE data stream parsing tasks. It does not involve request management or connection interruption, focusing solely on doing one thing: **parsing streams cleanly**.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## ✨ Features
|
|
8
|
+
|
|
9
|
+
- ✅ **Pure SSE stream parsing**, no concern for request lifecycle
|
|
10
|
+
- ✅ Supports standard `data:` protocol format, compatible with all SSE-based services
|
|
11
|
+
- ✅ Built-in `[DONE]` early identification and quick skipping
|
|
12
|
+
- ✅ Low GC pressure, avoiding unnecessary object creation
|
|
13
|
+
- ✅ Runs on **Node.js ≥ 18** (native `fetch` + `ReadableStream`)
|
|
14
|
+
- ✅ Native TypeScript support with clear types
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## 📦 Installation
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
pnpm add sse-stream-parser
|
|
22
|
+
# or
|
|
23
|
+
npm install sse-stream-parser
|
|
24
|
+
# or
|
|
25
|
+
yarn add sse-stream-parser
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 🧠 Design Philosophy
|
|
31
|
+
|
|
32
|
+
> **Parse streams only, no control logic**
|
|
33
|
+
|
|
34
|
+
This plugin will **NOT**:
|
|
35
|
+
|
|
36
|
+
- ❌ Manage request interruption/abort
|
|
37
|
+
- ❌ Wrap fetch
|
|
38
|
+
- ❌ Maintain connection status
|
|
39
|
+
- ❌ Introduce EventEmitter/Rx/class abstractions
|
|
40
|
+
|
|
41
|
+
This plugin is **only responsible for**:
|
|
42
|
+
|
|
43
|
+
- ✔ Parse `ReadableStreamDefaultReader<Uint8Array<ArrayBuffer>>`
|
|
44
|
+
- ✔ Split SSE lines
|
|
45
|
+
- ✔ Parse `data:` content
|
|
46
|
+
- ✔ Identify `[DONE]`
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## 🚀 Basic Usage
|
|
51
|
+
|
|
52
|
+
### 1️⃣ Basic Example (Node.js / Edge)
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
import { parseSSEStream } from "sse-stream-parser";
|
|
56
|
+
|
|
57
|
+
const res = await fetch(url, options);
|
|
58
|
+
|
|
59
|
+
if (!res.body) return;
|
|
60
|
+
|
|
61
|
+
const reader = res.body.getReader();
|
|
62
|
+
|
|
63
|
+
await parseSSEStream({
|
|
64
|
+
renderStream: reader,
|
|
65
|
+
options: {
|
|
66
|
+
onMessage(data) {
|
|
67
|
+
// data is the parsed SSE message
|
|
68
|
+
console.log(data);
|
|
69
|
+
},
|
|
70
|
+
onDone() {
|
|
71
|
+
console.log("stream finished");
|
|
72
|
+
},
|
|
73
|
+
onError(err) {
|
|
74
|
+
console.error("Error reading stream:", err);
|
|
75
|
+
},
|
|
76
|
+
},
|
|
77
|
+
});
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## 🔍 `[DONE]` Processing Logic
|
|
83
|
+
|
|
84
|
+
Plugin internally optimizes for the following case:
|
|
85
|
+
|
|
86
|
+
```txt
|
|
87
|
+
data: [DONE]
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
- Early identification of `[DONE]`
|
|
91
|
+
- **Skip JSON.parse**
|
|
92
|
+
- Immediately trigger `onDone`
|
|
93
|
+
- Subsequent data is skipped directly
|
|
94
|
+
|
|
95
|
+
Avoid meaningless parsing and exception catching.
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## ⚙️ API Documentation
|
|
100
|
+
|
|
101
|
+
### `parseSSEStream(options)`
|
|
102
|
+
|
|
103
|
+
#### Parameters
|
|
104
|
+
|
|
105
|
+
| Parameter | Type | Description |
|
|
106
|
+
| ------------------- | ----------------------------------------- | ----------------------------------------- |
|
|
107
|
+
| `renderStream` | `ReadableStreamDefaultReader<Uint8Array>` | Reader for SSE response body |
|
|
108
|
+
| `options` | `StreamOptions` | Options object containing callbacks |
|
|
109
|
+
| `options.onMessage` | `(data: T) => void` | Callback for each message |
|
|
110
|
+
| `options.onDone` | `() => void` | Triggered when `[DONE]` is received (optional) |
|
|
111
|
+
| `options.onError` | `(err: Error) => void` | Parsing error callback (optional) |
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
## 🌍 Runtime Environment
|
|
116
|
+
|
|
117
|
+
- Node.js **>= 18**
|
|
118
|
+
- Bun / Deno / Edge Runtime
|
|
119
|
+
- Browser (requires `ReadableStream` support)
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## 🧱 Use Cases
|
|
124
|
+
|
|
125
|
+
- SSE for AI services like OpenAI/Claude/Gemini
|
|
126
|
+
- Real-time data push services
|
|
127
|
+
- Real-time updates for stock quotes, weather data, etc.
|
|
128
|
+
- Real-time log stream monitoring
|
|
129
|
+
- Custom SSE services
|
|
130
|
+
- Streaming consumption on Web/Node/Edge
|
|
131
|
+
- Infrastructure / SDK / Middleware layers
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## 📜 License
|
|
136
|
+
|
|
137
|
+
MIT
|
|
138
|
+
# SSE Stream Parser
|
|
139
|
+
|
|
3
140
|
一个**轻量、纯粹、可用于生产环境的 SSE（Server-Sent Events）流解析工具**，基于标准的 SSE 协议实现，与具体应用场景无关，可广泛应用于各类 SSE 数据流解析，不掺杂请求管理、不中断连接、只做一件事：**把流解析干净**。
|
|
4
141
|
|
|
142
|
+
A **lightweight, pure, production-ready SSE (Server-Sent Events) stream parser**, implemented based on the standard SSE protocol. It is independent of specific application scenarios and can be widely used in various SSE data stream parsing tasks. It does not involve request management or connection interruption, focusing solely on doing one thing: **parsing streams cleanly**.
|
|
143
|
+
|
|
5
144
|
---
|
|
6
145
|
|
|
7
|
-
## ✨ 特性亮点
|
|
146
|
+
## ✨ 特性亮点 / Features
|
|
8
147
|
|
|
9
|
-
- ✅ **纯 SSE 流解析**，不关心请求生命周期
|
|
10
|
-
- ✅ 支持标准 `data:` 协议格式，兼容所有基于 SSE 的服务
|
|
11
|
-
- ✅ 内置 `[DONE]` 提前识别与快速跳过
|
|
12
|
-
- ✅ 低 GC 压力，避免不必要对象创建
|
|
13
|
-
- ✅ 可运行于 **Node.js ≥ 18**（原生 `fetch` + `ReadableStream
|
|
14
|
-
- ✅ TypeScript 原生支持，类型清晰
|
|
148
|
+
- ✅ **纯 SSE 流解析**，不关心请求生命周期 / Pure SSE stream parsing, no concern for request lifecycle
|
|
149
|
+
- ✅ 支持标准 `data:` 协议格式，兼容所有基于 SSE 的服务 / Supports standard `data:` protocol format, compatible with all SSE-based services
|
|
150
|
+
- ✅ 内置 `[DONE]` 提前识别与快速跳过 / Built-in `[DONE]` early identification and quick skipping
|
|
151
|
+
- ✅ 低 GC 压力，避免不必要对象创建 / Low GC pressure, avoiding unnecessary object creation
|
|
152
|
+
- ✅ 可运行于 **Node.js ≥ 18**（原生 `fetch` + `ReadableStream`）/ Runs on **Node.js ≥ 18** (native `fetch` + `ReadableStream`)
|
|
153
|
+
- ✅ TypeScript 原生支持，类型清晰 / Native TypeScript support with clear types
|
|
15
154
|
|
|
16
155
|
---
|
|
17
156
|
|
|
18
|
-
## 📦 安装
|
|
157
|
+
## 📦 安装 / Installation
|
|
19
158
|
|
|
20
159
|
```bash
|
|
21
160
|
pnpm add sse-stream-parser
|
|
@@ -27,29 +166,29 @@ yarn add sse-stream-parser
|
|
|
27
166
|
|
|
28
167
|
---
|
|
29
168
|
|
|
30
|
-
## 🧠 设计理念
|
|
169
|
+
## 🧠 设计理念 / Design Philosophy
|
|
31
170
|
|
|
32
|
-
> **只做流解析，不做控制逻辑**
|
|
171
|
+
> **只做流解析，不做控制逻辑** / Parse streams only, no control logic
|
|
33
172
|
|
|
34
|
-
|
|
173
|
+
本插件**不会** / This plugin will **NOT**:
|
|
35
174
|
|
|
36
|
-
- ❌ 管理请求中断 / abort
|
|
37
|
-
- ❌ 包装 fetch
|
|
38
|
-
- ❌ 维护连接状态
|
|
39
|
-
- ❌ 引入 EventEmitter / Rx / class 抽象
|
|
175
|
+
- ❌ 管理请求中断 / abort / Manage request interruption/abort
|
|
176
|
+
- ❌ 包装 fetch / Wrap fetch
|
|
177
|
+
- ❌ 维护连接状态 / Maintain connection status
|
|
178
|
+
- ❌ 引入 EventEmitter / Rx / class 抽象 / Introduce EventEmitter/Rx/class abstractions
|
|
40
179
|
|
|
41
|
-
|
|
180
|
+
本插件**只负责** / This plugin is **only responsible for**:
|
|
42
181
|
|
|
43
182
|
- ✔ 解析 `ReadableStreamDefaultReader<Uint8Array<ArrayBuffer>>`
|
|
44
|
-
- ✔ 拆分 SSE 行
|
|
45
|
-
- ✔ 解析 `data:` 内容
|
|
46
|
-
- ✔ 识别 `[DONE]`
|
|
183
|
+
- ✔ 拆分 SSE 行 / Split SSE lines
|
|
184
|
+
- ✔ 解析 `data:` 内容 / Parse `data:` content
|
|
185
|
+
- ✔ 识别 `[DONE]` / Identify `[DONE]`
|
|
47
186
|
|
|
48
187
|
---
|
|
49
188
|
|
|
50
|
-
## 🚀 基本用法
|
|
189
|
+
## 🚀 基本用法 / Basic Usage
|
|
51
190
|
|
|
52
|
-
### 1️⃣ 基础示例（Node.js / Edge
|
|
191
|
+
### 1️⃣ 基础示例（Node.js / Edge）/ Basic Example (Node.js / Edge)
|
|
53
192
|
|
|
54
193
|
```ts
|
|
55
194
|
import { parseSSEStream } from "sse-stream-parser";
|
|
@@ -64,7 +203,7 @@ await parseSSEStream({
|
|
|
64
203
|
renderStream: reader,
|
|
65
204
|
options: {
|
|
66
205
|
onMessage(data) {
|
|
67
|
-
// data 是解析后的 SSE 消息
|
|
206
|
+
// data 是解析后的 SSE 消息 / data is the parsed SSE message
|
|
68
207
|
console.log(data);
|
|
69
208
|
},
|
|
70
209
|
onDone() {
|
|
@@ -79,59 +218,59 @@ await parseSSEStream({
|
|
|
79
218
|
|
|
80
219
|
---
|
|
81
220
|
|
|
82
|
-
## 🔍 `[DONE]` 的处理逻辑
|
|
221
|
+
## 🔍 `[DONE]` 的处理逻辑 / `[DONE]` Processing Logic
|
|
83
222
|
|
|
84
|
-
|
|
223
|
+
插件内部对以下情况做了优化 / Plugin internally optimizes for the following case:
|
|
85
224
|
|
|
86
225
|
```txt
|
|
87
226
|
data: [DONE]
|
|
88
227
|
```
|
|
89
228
|
|
|
90
|
-
- 提前识别 `[DONE]`
|
|
91
|
-
- **不再进入 JSON.parse**
|
|
92
|
-
- 立即触发 `onDone`
|
|
93
|
-
- 后续数据直接跳过
|
|
229
|
+
- 提前识别 `[DONE]` / Early identification of `[DONE]`
|
|
230
|
+
- **不再进入 JSON.parse** / **Skip JSON.parse**
|
|
231
|
+
- 立即触发 `onDone` / Immediately trigger `onDone`
|
|
232
|
+
- 后续数据直接跳过 / Subsequent data is skipped directly
|
|
94
233
|
|
|
95
|
-
|
|
234
|
+
避免无意义的解析和异常捕获 / Avoid meaningless parsing and exception catching.
|
|
96
235
|
|
|
97
236
|
---
|
|
98
237
|
|
|
99
|
-
## ⚙️ API 说明
|
|
238
|
+
## ⚙️ API 说明 / API Documentation
|
|
100
239
|
|
|
101
240
|
### `parseSSEStream(options)`
|
|
102
241
|
|
|
103
|
-
#### 参数
|
|
242
|
+
#### 参数 / Parameters
|
|
104
243
|
|
|
105
|
-
| 参数
|
|
106
|
-
|
|
|
107
|
-
| `renderStream`
|
|
108
|
-
| `options`
|
|
109
|
-
| `options.onMessage`
|
|
110
|
-
| `options.onDone`
|
|
111
|
-
| `options.onError`
|
|
244
|
+
| 参数 / Parameter | 类型 / Type | 说明 / Description |
|
|
245
|
+
| --------------------- | ----------------------------------------- | --------------------------------------- |
|
|
246
|
+
| `renderStream` | `ReadableStreamDefaultReader<Uint8Array>` | SSE 响应体的 Reader / Reader for SSE response body |
|
|
247
|
+
| `options` | `StreamOptions` | 包含回调函数的选项对象 / Options object containing callbacks |
|
|
248
|
+
| `options.onMessage` | `(data: T) => void` | 每条消息回调 / Callback for each message |
|
|
249
|
+
| `options.onDone` | `() => void` | 收到 `[DONE]` 时触发（可选）/ Triggered when `[DONE]` is received (optional) |
|
|
250
|
+
| `options.onError` | `(err: Error) => void` | 解析错误回调（可选）/ Parsing error callback (optional) |
|
|
112
251
|
|
|
113
252
|
---
|
|
114
253
|
|
|
115
|
-
## 🌍 运行环境
|
|
254
|
+
## 🌍 运行环境 / Runtime Environment
|
|
116
255
|
|
|
117
256
|
- Node.js **>= 18**
|
|
118
257
|
- Bun / Deno / Edge Runtime
|
|
119
|
-
-
|
|
258
|
+
- Browser (requires `ReadableStream` support)
|
|
120
259
|
|
|
121
260
|
---
|
|
122
261
|
|
|
123
|
-
## 🧱 适用场景
|
|
262
|
+
## 🧱 适用场景 / Use Cases
|
|
124
263
|
|
|
125
|
-
- OpenAI / Claude / Gemini 等 AI 服务 SSE
|
|
126
|
-
- 实时数据推送服务
|
|
127
|
-
- 股票行情、天气数据等实时更新
|
|
128
|
-
- 日志流实时监控
|
|
129
|
-
- 自定义 SSE 服务
|
|
130
|
-
- Web / Node / Edge 流式消费
|
|
131
|
-
-
|
|
264
|
+
- OpenAI / Claude / Gemini 等 AI 服务 SSE / SSE for AI services like OpenAI/Claude/Gemini
|
|
265
|
+
- 实时数据推送服务 / Real-time data push services
|
|
266
|
+
- 股票行情、天气数据等实时更新 / Real-time updates for stock quotes, weather data, etc.
|
|
267
|
+
- 日志流实时监控 / Real-time log stream monitoring
|
|
268
|
+
- 自定义 SSE 服务 / Custom SSE services
|
|
269
|
+
- Web / Node / Edge 流式消费 / Streaming consumption on Web/Node/Edge
|
|
270
|
+
- Infrastructure / SDK / Middleware layers
|
|
132
271
|
|
|
133
272
|
---
|
|
134
273
|
|
|
135
274
|
## 📜 License
|
|
136
275
|
|
|
137
|
-
MIT
|
|
276
|
+
MIT
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# SSE Stream Parser
|
|
2
|
+
|
|
3
|
+
一个**轻量、纯粹、可用于生产环境的 SSE（Server-Sent Events）流解析工具**，基于标准的 SSE 协议实现，与具体应用场景无关，可广泛应用于各类 SSE 数据流解析，不掺杂请求管理、不中断连接、只做一件事：**把流解析干净**。
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## ✨ 特性亮点
|
|
8
|
+
|
|
9
|
+
- ✅ **纯 SSE 流解析**，不关心请求生命周期
|
|
10
|
+
- ✅ 支持标准 `data:` 协议格式，兼容所有基于 SSE 的服务
|
|
11
|
+
- ✅ 内置 `[DONE]` 提前识别与快速跳过
|
|
12
|
+
- ✅ 低 GC 压力，避免不必要对象创建
|
|
13
|
+
- ✅ 可运行于 **Node.js ≥ 18**（原生 `fetch` + `ReadableStream`）
|
|
14
|
+
- ✅ TypeScript 原生支持，类型清晰
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## 📦 安装
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
pnpm add sse-stream-parser
|
|
22
|
+
# or
|
|
23
|
+
npm install sse-stream-parser
|
|
24
|
+
# or
|
|
25
|
+
yarn add sse-stream-parser
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 🧠 设计理念
|
|
31
|
+
|
|
32
|
+
> **只做流解析，不做控制逻辑**
|
|
33
|
+
|
|
34
|
+
本插件**不会**：
|
|
35
|
+
|
|
36
|
+
- ❌ 管理请求中断 / abort
|
|
37
|
+
- ❌ 包装 fetch
|
|
38
|
+
- ❌ 维护连接状态
|
|
39
|
+
- ❌ 引入 EventEmitter / Rx / class 抽象
|
|
40
|
+
|
|
41
|
+
本插件**只负责**：
|
|
42
|
+
|
|
43
|
+
- ✔ 解析 `ReadableStreamDefaultReader<Uint8Array<ArrayBuffer>>`
|
|
44
|
+
- ✔ 拆分 SSE 行
|
|
45
|
+
- ✔ 解析 `data:` 内容
|
|
46
|
+
- ✔ 识别 `[DONE]`
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## 🚀 基本用法
|
|
51
|
+
|
|
52
|
+
### 1️⃣ 基础示例（Node.js / Edge）
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
import { parseSSEStream } from "sse-stream-parser";
|
|
56
|
+
|
|
57
|
+
const res = await fetch(url, options);
|
|
58
|
+
|
|
59
|
+
if (!res.body) return;
|
|
60
|
+
|
|
61
|
+
const reader = res.body.getReader();
|
|
62
|
+
|
|
63
|
+
await parseSSEStream({
|
|
64
|
+
renderStream: reader,
|
|
65
|
+
options: {
|
|
66
|
+
onMessage(data) {
|
|
67
|
+
// data 是解析后的 SSE 消息
|
|
68
|
+
console.log(data);
|
|
69
|
+
},
|
|
70
|
+
onDone() {
|
|
71
|
+
console.log("stream finished");
|
|
72
|
+
},
|
|
73
|
+
onError(err) {
|
|
74
|
+
console.error("Error reading stream:", err);
|
|
75
|
+
},
|
|
76
|
+
},
|
|
77
|
+
});
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## 🔍 `[DONE]` 的处理逻辑
|
|
83
|
+
|
|
84
|
+
插件内部对以下情况做了优化：
|
|
85
|
+
|
|
86
|
+
```txt
|
|
87
|
+
data: [DONE]
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
- 提前识别 `[DONE]`
|
|
91
|
+
- **不再进入 JSON.parse**
|
|
92
|
+
- 立即触发 `onDone`
|
|
93
|
+
- 后续数据直接跳过
|
|
94
|
+
|
|
95
|
+
避免无意义的解析和异常捕获。
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## ⚙️ API 说明
|
|
100
|
+
|
|
101
|
+
### `parseSSEStream(options)`
|
|
102
|
+
|
|
103
|
+
#### 参数
|
|
104
|
+
|
|
105
|
+
| 参数 | 类型 | 说明 |
|
|
106
|
+
| ------------------- | ----------------------------------------- | ---------------------------- |
|
|
107
|
+
| `renderStream` | `ReadableStreamDefaultReader<Uint8Array>` | SSE 响应体的 Reader |
|
|
108
|
+
| `options` | `StreamOptions` | 包含回调函数的选项对象 |
|
|
109
|
+
| `options.onMessage` | `(data: T) => void` | 每条消息回调 |
|
|
110
|
+
| `options.onDone` | `() => void` | 收到 `[DONE]` 时触发（可选） |
|
|
111
|
+
| `options.onError` | `(err: Error) => void` | 解析错误回调（可选） |
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
## 🌍 运行环境
|
|
116
|
+
|
|
117
|
+
- Node.js **>= 18**
|
|
118
|
+
- Bun / Deno / Edge Runtime
|
|
119
|
+
- 浏览器（需要支持 `ReadableStream`）
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## 🧱 适用场景
|
|
124
|
+
|
|
125
|
+
- OpenAI / Claude / Gemini 等 AI 服务 SSE
|
|
126
|
+
- 实时数据推送服务
|
|
127
|
+
- 股票行情、天气数据等实时更新
|
|
128
|
+
- 日志流实时监控
|
|
129
|
+
- 自定义 SSE 服务
|
|
130
|
+
- Web / Node / Edge 流式消费
|
|
131
|
+
- Infra / SDK / 中间层
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## 📜 License
|
|
136
|
+
|
|
137
|
+
MIT
|