@ahoo-wang/fetcher-eventstream 0.3.8 → 0.5.0

package/README.md

@@ -6,39 +6,35 @@
 [![License](https://img.shields.io/npm/l/@ahoo-wang/fetcher-eventstream.svg)](https://github.com/Ahoo-Wang/fetcher/blob/main/LICENSE)
 [![npm downloads](https://img.shields.io/npm/dm/@ahoo-wang/fetcher-eventstream.svg)](https://www.npmjs.com/package/@ahoo-wang/fetcher-eventstream)
 
-Support for text/event-stream in Fetcher, enabling Server-Sent Events (SSE) functionality.
+Support for text/event-stream in Fetcher, enabling Server-Sent Events (SSE) functionality for real-time data streaming.
 
-## Features
+## 🌟 Features
 
-- **Event Stream Conversion**: Converts `text/event-stream` responses to async generators of `ServerSentEvent` objects
-- **Interceptor Integration**: Automatically adds `eventStream()` method to responses with `text/event-stream` content type
-- **SSE Parsing**: Parses Server-Sent Events according to the specification, including data, event, id, and retry fields
-- **Streaming Support**: Handles chunked data and multi-line events correctly
-- **Comment Handling**: Properly ignores comment lines (lines starting with `:`) as per SSE specification
-- **TypeScript Support**: Complete TypeScript type definitions
+- **📡 Event Stream Conversion**: Converts `text/event-stream` responses to async generators of `ServerSentEvent` objects
+- **🔌 Interceptor Integration**: Automatically adds `eventStream()` method to responses with `text/event-stream` content
+  type
+- **📋 SSE Parsing**: Parses Server-Sent Events according to the specification, including data, event, id, and retry
+  fields
+- **🔄 Streaming Support**: Handles chunked data and multi-line events correctly
+- **💬 Comment Handling**: Properly ignores comment lines (lines starting with `:`) as per SSE specification
+- **🛡️ TypeScript Support**: Complete TypeScript type definitions
+- **⚡ Performance Optimized**: Efficient parsing and streaming for high-performance applications
 
-## Installation
+## 🚀 Quick Start
 
-Using pnpm:
-
-```bash
-pnpm add @ahoo-wang/fetcher-eventstream
-```
-
-Using npm:
+### Installation
 
 ```bash
+# Using npm
 npm install @ahoo-wang/fetcher-eventstream
-```
 
-Using yarn:
+# Using pnpm
+pnpm add @ahoo-wang/fetcher-eventstream
 
-```bash
+# Using yarn
 yarn add @ahoo-wang/fetcher-eventstream
 ```
 
-## Usage
-
 ### Basic Usage with Interceptor
 
 ```typescript
@@ -83,70 +79,36 @@ try {
 }
 ```
 
-### Async Iterator Usage
-
-```typescript
-import { Fetcher } from '@ahoo-wang/fetcher';
-import { EventStreamInterceptor } from '@ahoo-wang/fetcher-eventstream';
-
-const fetcher = new Fetcher({
-  baseURL: 'https://api.example.com',
-  interceptors: {
-    response: [new EventStreamInterceptor()],
-  },
-});
+## 📚 API Reference
 
-// Using async iteration
-const response = await fetcher.get('/events');
-if (response.eventStream) {
-  for await (const event of response.eventStream()) {
-    switch (event.event) {
-      case 'message':
-        console.log('Message:', event.data);
-        break;
-      case 'notification':
-        console.log('Notification:', event.data);
-        break;
-      default:
-        console.log('Unknown event:', event);
-    }
-  }
-}
-```
+### EventStreamInterceptor
 
-## API Reference
+A response interceptor that automatically adds an `eventStream()` method to responses with `text/event-stream` content
+type.
 
-### EventStreamConverter
+#### Usage
 
-A utility class for converting `text/event-stream` responses to readable streams.
+```typescript
+fetcher.interceptors.response.use(new EventStreamInterceptor());
+```
 
-#### `toServerSentEventStream(response: Response): ServerEventStream`
+### toServerSentEventStream
 
 Converts a Response object with a `text/event-stream` body to a readable stream of ServerSentEvent objects.
 
-**Parameters:**
-
-- `response`: The HTTP response with `text/event-stream` content type
-
-**Returns:**
-
-- `ServerEventStream`: A readable stream of ServerSentEvent objects
+#### Signature
 
-### EventStreamInterceptor
-
-A response interceptor that automatically adds an `eventStream()` method to responses with `text/event-stream` content type.
-
-#### `intercept(exchange: FetchExchange): FetchExchange`
-
-Intercepts a response and adds the `eventStream()` method if the content type is `text/event-stream`.
+```typescript
+function toServerSentEventStream(response: Response): ServerSentEventStream;
+```
 
-**Parameters:**
+#### Parameters
 
-- `exchange`: The fetch exchange containing the response to intercept
+- `response`: The HTTP response with `text/event-stream` content type
 
-**Returns:**
+#### Returns
 
-- `FetchExchange`: The intercepted exchange with response potentially modified to include `eventStream()` method
+- `ServerSentEventStream`: A readable stream of ServerSentEvent objects
 
 ### ServerSentEvent
 
@@ -169,18 +131,7 @@ Type alias for a readable stream of ServerSentEvent objects.
 type ServerSentEventStream = ReadableStream<ServerSentEvent>;
 ```
 
-## Server-Sent Events Specification Compliance
-
-This package fully implements the [Server-Sent Events specification](https://html.spec.whatwg.org/multipage/server-sent-events.html):
-
-- **Data field**: Supports multi-line data fields
-- **Event field**: Custom event types
-- **ID field**: Last event ID tracking
-- **Retry field**: Automatic reconnection timeout
-- **Comment lines**: Lines starting with `:` are ignored
-- **Event dispatching**: Proper event dispatching with default event type 'message'
-
-## Examples
+## 🛠️ Examples
 
 ### Real-time Notifications
 
@@ -207,6 +158,8 @@ if (response.eventStream) {
       case 'update':
         handleUpdate(JSON.parse(event.data));
         break;
+      default:
+        console.log('Unknown event:', event);
     }
   }
 }
@@ -238,12 +191,41 @@ if (response.eventStream) {
 }
 ```
 
-## Testing
+### Chat Application
+
+```typescript
+import { Fetcher } from '@ahoo-wang/fetcher';
+import { EventStreamInterceptor } from '@ahoo-wang/fetcher-eventstream';
+
+const fetcher = new Fetcher({
+  baseURL: 'https://chat-api.example.com',
+});
+fetcher.interceptors.response.use(new EventStreamInterceptor());
+
+// Real-time chat messages
+const response = await fetcher.get('/rooms/123/messages');
+if (response.eventStream) {
+  for await (const event of response.eventStream()) {
+    if (event.event === 'message') {
+      const message = JSON.parse(event.data);
+      displayMessage(message);
+    } else if (event.event === 'user-joined') {
+      showUserJoined(event.data);
+    } else if (event.event === 'user-left') {
+      showUserLeft(event.data);
+    }
+  }
+}
+```
 
-To run tests for this package:
+## 🧪 Testing
 
 ```bash
+# Run tests
 pnpm test
+
+# Run tests with coverage
+pnpm test --coverage
 ```
 
 The test suite includes:
@@ -253,6 +235,29 @@ The test suite includes:
 - Edge case handling (malformed events, chunked data, etc.)
 - Performance tests for large event streams
 
-## License
+## 📋 Server-Sent Events Specification Compliance
+
+This package fully implements
+the [Server-Sent Events specification](https://html.spec.whatwg.org/multipage/server-sent-events.html):
+
+- **Data field**: Supports multi-line data fields
+- **Event field**: Custom event types
+- **ID field**: Last event ID tracking
+- **Retry field**: Automatic reconnection timeout
+- **Comment lines**: Lines starting with `:` are ignored
+- **Event dispatching**: Proper event dispatching with default event type 'message'
+
+## 🤝 Contributing
+
+Contributions are welcome! Please see
+the [contributing guide](https://github.com/Ahoo-Wang/fetcher/blob/main/CONTRIBUTING.md) for more details.
+
+## 📄 License
 
 This project is licensed under the [Apache-2.0 License](../../LICENSE).
+
+---
+
+<p align="center">
+  Part of the <a href="https://github.com/Ahoo-Wang/fetcher">Fetcher</a> ecosystem
+</p>

package/README.zh-CN.md

@@ -6,39 +6,33 @@
 [![License](https://img.shields.io/npm/l/@ahoo-wang/fetcher-eventstream.svg)](https://github.com/Ahoo-Wang/fetcher/blob/main/LICENSE)
 [![npm downloads](https://img.shields.io/npm/dm/@ahoo-wang/fetcher-eventstream.svg)](https://www.npmjs.com/package/@ahoo-wang/fetcher-eventstream)
 
-为 Fetcher 提供 text/event-stream 支持，实现服务器发送事件（SSE）功能。
+为 Fetcher 提供 text/event-stream 支持，实现服务器发送事件（SSE）功能，用于实时数据流。
 
-## 特性
+## 🌟 特性
 
-- **事件流转换**：将 `text/event-stream` 响应转换为 `ServerSentEvent` 对象的异步生成器
-- **拦截器集成**：自动为 `text/event-stream` 内容类型的响应添加 `eventStream()` 方法
-- **SSE 解析**：根据规范解析服务器发送事件，包括数据、事件、ID 和重试字段
-- **流支持**：正确处理分块数据和多行事件
-- **注释处理**：正确忽略注释行（以 `:` 开头的行）
-- **TypeScript 支持**：完整的 TypeScript 类型定义
+- **📡 事件流转换**：将 `text/event-stream` 响应转换为 `ServerSentEvent` 对象的异步生成器
+- **🔌 拦截器集成**：自动为 `text/event-stream` 内容类型的响应添加 `eventStream()` 方法
+- **📋 SSE 解析**：根据规范解析服务器发送事件，包括数据、事件、ID 和重试字段
+- **🔄 流支持**：正确处理分块数据和多行事件
+- **💬 注释处理**：正确忽略注释行（以 `:` 开头的行）
+- **🛡️ TypeScript 支持**：完整的 TypeScript 类型定义
+- **⚡ 性能优化**：高效的解析和流处理，适用于高性能应用
 
-## 安装
+## 🚀 快速开始
 
-使用 pnpm：
-
-```bash
-pnpm add @ahoo-wang/fetcher-eventstream
-```
-
-使用 npm：
+### 安装
 
 ```bash
+# 使用 npm
 npm install @ahoo-wang/fetcher-eventstream
-```
 
-使用 yarn：
+# 使用 pnpm
+pnpm add @ahoo-wang/fetcher-eventstream
 
-```bash
+# 使用 yarn
 yarn add @ahoo-wang/fetcher-eventstream
 ```
 
-## 使用
-
 ### 带拦截器的基本用法
 
 ```typescript
@@ -83,70 +77,35 @@ try {
 }
 ```
 
-### 异步迭代器用法
+## 📚 API 参考
 
-```typescript
-import { Fetcher } from '@ahoo-wang/fetcher';
-import { EventStreamInterceptor } from '@ahoo-wang/fetcher-eventstream';
-
-const fetcher = new Fetcher({
-  baseURL: 'https://api.example.com',
-  interceptors: {
-    response: [new EventStreamInterceptor()],
-  },
-});
-
-// 使用异步迭代
-const response = await fetcher.get('/events');
-if (response.eventStream) {
-  for await (const event of response.eventStream()) {
-    switch (event.event) {
-      case 'message':
-        console.log('消息:', event.data);
-        break;
-      case 'notification':
-        console.log('通知:', event.data);
-        break;
-      default:
-        console.log('未知事件:', event);
-    }
-  }
-}
-```
+### EventStreamInterceptor
 
-## API 参考
+响应拦截器，自动为 `text/event-stream` 内容类型的响应添加 `eventStream()` 方法。
 
-### EventStreamConverter
+#### 用法
 
-用于将 `text/event-stream` 响应转换为可读流的工具类。
+```typescript
+fetcher.interceptors.response.use(new EventStreamInterceptor());
+```
 
-#### `toServerSentEventStream(response: Response): ServerEventStream`
+### toServerSentEventStream
 
 将带有 `text/event-stream` 主体的 Response 对象转换为 ServerSentEvent 对象的可读流。
 
-**参数：**
-
-- `response`：带有 `text/event-stream` 内容类型的 HTTP 响应
-
-**返回：**
-
-- `ServerEventStream`：ServerSentEvent 对象的可读流
+#### 签名
 
-### EventStreamInterceptor
-
-响应拦截器，自动为 `text/event-stream` 内容类型的响应添加 `eventStream()` 方法。
-
-#### `intercept(exchange: FetchExchange): FetchExchange`
-
-拦截响应，如果内容类型是 `text/event-stream` 则添加 `eventStream()` 方法。
+```typescript
+function toServerSentEventStream(response: Response): ServerSentEventStream;
+```
 
-**参数：**
+#### 参数
 
-- `exchange`：包含要拦截响应的 fetch exchange
+- `response`：带有 `text/event-stream` 内容类型的 HTTP 响应
 
-**返回：**
+#### 返回
 
-- `FetchExchange`：可能修改了响应以包含 `eventStream()` 方法的拦截 exchange
+- `ServerSentEventStream`：ServerSentEvent 对象的可读流
 
 ### ServerSentEvent
 
@@ -169,18 +128,7 @@ ServerSentEvent 对象的可读流的类型别名。
 type ServerSentEventStream = ReadableStream<ServerSentEvent>;
 ```
 
-## 服务器发送事件规范合规性
-
-此包完全实现了 [服务器发送事件规范](https://html.spec.whatwg.org/multipage/server-sent-events.html)：
-
-- **数据字段**：支持多行数据字段
-- **事件字段**：自定义事件类型
-- **ID 字段**：最后事件 ID 跟踪
-- **重试字段**：自动重连超时
-- **注释行**：忽略以 `:` 开头的行
-- **事件分发**：正确的事件分发，默认事件类型为 'message'
-
-## 示例
+## 🛠️ 示例
 
 ### 实时通知
 
@@ -207,6 +155,8 @@ if (response.eventStream) {
       case 'update':
         handleUpdate(JSON.parse(event.data));
         break;
+      default:
+        console.log('未知事件:', event);
     }
   }
 }
@@ -238,12 +188,41 @@ if (response.eventStream) {
 }
 ```
 
-## 测试
+### 聊天应用
+
+```typescript
+import { Fetcher } from '@ahoo-wang/fetcher';
+import { EventStreamInterceptor } from '@ahoo-wang/fetcher-eventstream';
+
+const fetcher = new Fetcher({
+  baseURL: 'https://chat-api.example.com',
+});
+fetcher.interceptors.response.use(new EventStreamInterceptor());
+
+// 实时聊天消息
+const response = await fetcher.get('/rooms/123/messages');
+if (response.eventStream) {
+  for await (const event of response.eventStream()) {
+    if (event.event === 'message') {
+      const message = JSON.parse(event.data);
+      displayMessage(message);
+    } else if (event.event === 'user-joined') {
+      showUserJoined(event.data);
+    } else if (event.event === 'user-left') {
+      showUserLeft(event.data);
+    }
+  }
+}
+```
 
-运行此包的测试：
+## 🧪 测试
 
 ```bash
+# 运行测试
 pnpm test
+
+# 运行带覆盖率的测试
+pnpm test --coverage
 ```
 
 测试套件包括：
@@ -253,6 +232,27 @@ pnpm test
 - 边界情况处理（畸形事件、分块数据等）
 - 大事件流的性能测试
 
-## 许可证
+## 📋 服务器发送事件规范合规性
+
+此包完全实现了 [服务器发送事件规范](https://html.spec.whatwg.org/multipage/server-sent-events.html)：
+
+- **数据字段**：支持多行数据字段
+- **事件字段**：自定义事件类型
+- **ID 字段**：最后事件 ID 跟踪
+- **重试字段**：自动重连超时
+- **注释行**：忽略以 `:` 开头的行
+- **事件分发**：正确的事件分发，默认事件类型为 'message'
+
+## 🤝 贡献
+
+欢迎贡献！请查看 [贡献指南](https://github.com/Ahoo-Wang/fetcher/blob/main/CONTRIBUTING.md) 了解更多详情。
+
+## 📄 许可证
 
 本项目采用 [Apache-2.0 许可证](../../LICENSE)。
+
+---
+
+<p align="center">
+  Fetcher 生态系统的一部分
+</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahoo-wang/fetcher-eventstream",
-  "version": "0.3.8",
+  "version": "0.5.0",
   "description": "Support for text/event-stream in Fetcher",
   "keywords": [
     "fetch",
@@ -33,7 +33,7 @@
     "dist"
   ],
   "dependencies": {
-    "@ahoo-wang/fetcher": "0.3.8"
+    "@ahoo-wang/fetcher": "0.5.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^3.2.4",