@ahoo-wang/fetcher-eventstream 0.1.5 → 0.2.0

package/README.md

@@ -15,8 +15,6 @@ Support for text/event-stream in Fetcher, enabling Server-Sent Events (SSE) func
 - **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
-- **Event ID Tracking**: Maintains last event ID for automatic reconnection
-- **Retry Management**: Handles retry timeout values for connection reattempts
 - **TypeScript Support**: Complete TypeScript type definitions
 
 ## Installation
@@ -66,11 +64,11 @@ if (response.eventStream) {
 ### Manual Conversion
 
 ```typescript
-import { EventStreamConverter } from '@ahoo-wang/fetcher-eventstream';
+import { toServerSentEventStream } from '@ahoo-wang/fetcher-eventstream';
 
 // Convert a Response object manually
 const response = await fetch('/events');
-const eventStream = EventStreamConverter.toEventStream(response);
+const eventStream = toServerSentEventStream(response);
 
 // Read events from the stream
 const reader = eventStream.getReader();
@@ -122,7 +120,7 @@ if (response.eventStream) {
 
 A utility class for converting `text/event-stream` responses to readable streams.
 
-#### `toEventStream(response: Response): ServerEventStream`
+#### `toServerSentEventStream(response: Response): ServerEventStream`
 
 Converts a Response object with a `text/event-stream` body to a readable stream of ServerSentEvent objects.
 

package/README.zh-CN.md

@@ -0,0 +1,258 @@
+# @ahoo-wang/fetcher-eventstream
+
+[![npm version](https://img.shields.io/npm/v/@ahoo-wang/fetcher-eventstream.svg)](https://www.npmjs.com/package/@ahoo-wang/fetcher-eventstream)
+[![Build Status](https://github.com/Ahoo-Wang/fetcher/actions/workflows/ci.yml/badge.svg)](https://github.com/Ahoo-Wang/fetcher/actions)
+[![codecov](https://codecov.io/gh/Ahoo-Wang/Fetcher/graph/badge.svg?token=CUPgk8DmH5)](https://codecov.io/gh/Ahoo-Wang/Fetcher)
+[![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）功能。
+
+## 特性
+
+- **事件流转换**：将 `text/event-stream` 响应转换为 `ServerSentEvent` 对象的异步生成器
+- **拦截器集成**：自动为 `text/event-stream` 内容类型的响应添加 `eventStream()` 方法
+- **SSE 解析**：根据规范解析服务器发送事件，包括数据、事件、ID 和重试字段
+- **流支持**：正确处理分块数据和多行事件
+- **注释处理**：正确忽略注释行（以 `:` 开头的行）
+- **TypeScript 支持**：完整的 TypeScript 类型定义
+
+## 安装
+
+使用 pnpm：
+
+```bash
+pnpm add @ahoo-wang/fetcher-eventstream
+```
+
+使用 npm：
+
+```bash
+npm install @ahoo-wang/fetcher-eventstream
+```
+
+使用 yarn：
+
+```bash
+yarn add @ahoo-wang/fetcher-eventstream
+```
+
+## 使用
+
+### 带拦截器的基本用法
+
+```typescript
+import { Fetcher } from '@ahoo-wang/fetcher';
+import { EventStreamInterceptor } from '@ahoo-wang/fetcher-eventstream';
+
+const fetcher = new Fetcher({
+  baseURL: 'https://api.example.com',
+});
+
+// 添加事件流拦截器
+fetcher.interceptors.response.use(new EventStreamInterceptor());
+
+// 在响应中使用 eventStream 方法处理 text/event-stream 内容类型
+const response = await fetcher.get('/events');
+if (response.eventStream) {
+  for await (const event of response.eventStream()) {
+    console.log('收到事件:', event);
+  }
+}
+```
+
+### 手动转换
+
+```typescript
+import { toServerSentEventStream } from '@ahoo-wang/fetcher-eventstream';
+
+// 手动转换 Response 对象
+const response = await fetch('/events');
+const eventStream = toServerSentEventStream(response);
+
+// 从流中读取事件
+const reader = eventStream.getReader();
+try {
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    console.log('收到事件:', value);
+  }
+} finally {
+  reader.releaseLock();
+}
+```
+
+### 异步迭代器用法
+
+```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);
+    }
+  }
+}
+```
+
+## API 参考
+
+### EventStreamConverter
+
+用于将 `text/event-stream` 响应转换为可读流的工具类。
+
+#### `toServerSentEventStream(response: Response): ServerEventStream`
+
+将带有 `text/event-stream` 主体的 Response 对象转换为 ServerSentEvent 对象的可读流。
+
+**参数：**
+
+- `response`：带有 `text/event-stream` 内容类型的 HTTP 响应
+
+**返回：**
+
+- `ServerEventStream`：ServerSentEvent 对象的可读流
+
+### EventStreamInterceptor
+
+响应拦截器，自动为 `text/event-stream` 内容类型的响应添加 `eventStream()` 方法。
+
+#### `intercept(response: Response): Response`
+
+拦截响应，如果内容类型是 `text/event-stream` 则添加 `eventStream()` 方法。
+
+**参数：**
+
+- `response`：要拦截的 HTTP 响应
+
+**返回：**
+
+- `Response`：添加了 `eventStream()` 方法的拦截响应
+
+### ServerSentEvent
+
+定义服务器发送事件结构的接口。
+
+```typescript
+interface ServerSentEvent {
+  data: string; // 事件数据（必需）
+  event?: string; // 事件类型（可选，默认为 'message'）
+  id?: string; // 事件 ID（可选）
+  retry?: number; // 以毫秒为单位的重试超时（可选）
+}
+```
+
+### ServerSentEventStream
+
+ServerSentEvent 对象的可读流的类型别名。
+
+```typescript
+type ServerSentEventStream = ReadableStream<ServerSentEvent>;
+```
+
+## 服务器发送事件规范合规性
+
+此包完全实现了 [服务器发送事件规范](https://html.spec.whatwg.org/multipage/server-sent-events.html)：
+
+- **数据字段**：支持多行数据字段
+- **事件字段**：自定义事件类型
+- **ID 字段**：最后事件 ID 跟踪
+- **重试字段**：自动重连超时
+- **注释行**：忽略以 `:` 开头的行
+- **事件分发**：正确的事件分发，默认事件类型为 'message'
+
+## 示例
+
+### 实时通知
+
+```typescript
+import { Fetcher } from '@ahoo-wang/fetcher';
+import { EventStreamInterceptor } from '@ahoo-wang/fetcher-eventstream';
+
+const fetcher = new Fetcher({
+  baseURL: 'https://api.example.com',
+});
+fetcher.interceptors.response.use(new EventStreamInterceptor());
+
+// 监听实时通知
+const response = await fetcher.get('/notifications');
+if (response.eventStream) {
+  for await (const event of response.eventStream()) {
+    switch (event.event) {
+      case 'message':
+        showNotification('消息', event.data);
+        break;
+      case 'alert':
+        showAlert('警报', event.data);
+        break;
+      case 'update':
+        handleUpdate(JSON.parse(event.data));
+        break;
+    }
+  }
+}
+```
+
+### 进度更新
+
+```typescript
+import { Fetcher } from '@ahoo-wang/fetcher';
+import { EventStreamInterceptor } from '@ahoo-wang/fetcher-eventstream';
+
+const fetcher = new Fetcher({
+  baseURL: 'https://api.example.com',
+});
+fetcher.interceptors.response.use(new EventStreamInterceptor());
+
+// 跟踪长时间运行的任务进度
+const response = await fetcher.get('/tasks/123/progress');
+if (response.eventStream) {
+  for await (const event of response.eventStream()) {
+    if (event.event === 'progress') {
+      const progress = JSON.parse(event.data);
+      updateProgressBar(progress.percentage);
+    } else if (event.event === 'complete') {
+      showCompletionMessage(event.data);
+      break;
+    }
+  }
+}
+```
+
+## 测试
+
+运行此包的测试：
+
+```bash
+pnpm test
+```
+
+测试套件包括：
+
+- 事件流转换测试
+- 拦截器功能测试
+- 边界情况处理（畸形事件、分块数据等）
+- 大事件流的性能测试
+
+## 许可证
+
+本项目采用 [Apache-2.0 许可证](../../LICENSE)。

package/dist/eventStreamConverter.d.ts

@@ -3,17 +3,5 @@ import { ServerSentEvent } from './serverSentEventTransformStream';
  * ServerSentEventStream is a ReadableStream of ServerSentEvent objects
  */
 export type ServerSentEventStream = ReadableStream<ServerSentEvent>;
-/**
- * Responsible for handling event stream responses, including converting Response to event stream (ReadableStream<ServerSentEvent>).
- */
-export declare class EventStreamConverter {
-    /**
-     * Convert HTTP response to server-sent event stream
-     *
-     * @param response - HTTP response object, should contain text/event-stream formatted data
-     * @returns ServerSentEventStream - Server event stream, can be used to read events sent by the server
-     * @throws Error - Throws error when response body is null
-     */
-    static toEventStream(response: Response): ServerSentEventStream;
-}
+export declare function toServerSentEventStream(response: Response): ServerSentEventStream;
 //# sourceMappingURL=eventStreamConverter.d.ts.map

package/dist/eventStreamConverter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"eventStreamConverter.d.ts","sourceRoot":"","sources":["../src/eventStreamConverter.ts"],"names":[],"mappings":"AACA,OAAO,EACL,eAAe,EAEhB,MAAM,kCAAkC,CAAC;AAE1C;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,cAAc,CAAC,eAAe,CAAC,CAAC;AAEpE;;GAEG;AACH,qBAAa,oBAAoB;IAC/B;;;;;;OAMG;IACH,MAAM,CAAC,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,qBAAqB;CAchE"}
+{"version":3,"file":"eventStreamConverter.d.ts","sourceRoot":"","sources":["../src/eventStreamConverter.ts"],"names":[],"mappings":"AACA,OAAO,EACL,eAAe,EAEhB,MAAM,kCAAkC,CAAC;AAE1C;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,cAAc,CAAC,eAAe,CAAC,CAAC;AAEpE,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,GAAG,qBAAqB,CAajF"}

package/dist/index.es.js

@@ -3,46 +3,46 @@ class d {
   constructor() {
     this.buffer = "";
   }
-  transform(r, t) {
+  transform(t, r) {
     try {
-      this.buffer += r;
+      this.buffer += t;
       const e = this.buffer.split(`
 `);
       this.buffer = e.pop() || "";
-      for (const n of e)
-        t.enqueue(n);
+      for (const s of e)
+        r.enqueue(s);
     } catch (e) {
-      t.error(e);
+      r.error(e);
     }
   }
-  flush(r) {
+  flush(t) {
     try {
-      this.buffer && r.enqueue(this.buffer);
-    } catch (t) {
-      r.error(t);
+      this.buffer && t.enqueue(this.buffer);
+    } catch (r) {
+      t.error(r);
     }
   }
 }
-class c extends TransformStream {
+class u extends TransformStream {
   constructor() {
     super(new d());
   }
 }
-var u = /* @__PURE__ */ ((a) => (a.ID = "id", a.RETRY = "retry", a.EVENT = "event", a.DATA = "data", a))(u || {});
-function m(a, r, t) {
-  switch (a) {
+var c = /* @__PURE__ */ ((n) => (n.ID = "id", n.RETRY = "retry", n.EVENT = "event", n.DATA = "data", n))(c || {});
+function m(n, t, r) {
+  switch (n) {
     case "event":
-      t.event = r;
+      r.event = t;
       break;
     case "data":
-      t.data.push(r);
+      r.data.push(t);
       break;
     case "id":
-      t.id = r;
+      r.id = t;
       break;
     case "retry":
-      const e = parseInt(r, 10);
-      isNaN(e) || (t.retry = e);
+      const e = parseInt(t, 10);
+      isNaN(e) || (r.retry = e);
       break;
   }
 }
@@ -60,11 +60,11 @@ class h {
    * @param chunk Input string chunk
    * @param controller Controller for controlling the transform stream
    */
-  transform(r, t) {
+  transform(t, r) {
     let e = this.currentEvent;
     try {
-      if (r.trim() === "") {
-        e.data.length > 0 && (t.enqueue({
+      if (t.trim() === "") {
+        e.data.length > 0 && (r.enqueue({
           event: e.event || "message",
           data: e.data.join(`
 `),
@@ -73,14 +73,14 @@ class h {
         }), e.event = "message", e.id = e.id, e.retry = e.retry, e.data = []);
         return;
       }
-      if (r.startsWith(":"))
+      if (t.startsWith(":"))
         return;
-      const n = r.indexOf(":");
-      let i, s;
-      n === -1 ? (i = r.toLowerCase(), s = "") : (i = r.substring(0, n).toLowerCase(), s = r.substring(n + 1), s.startsWith(" ") && (s = s.substring(1))), i = i.trim(), s = s.trim(), m(i, s, e);
-    } catch (n) {
-      t.error(
-        n instanceof Error ? n : new Error(String(n))
+      const s = t.indexOf(":");
+      let i, a;
+      s === -1 ? (i = t.toLowerCase(), a = "") : (i = t.substring(0, s).toLowerCase(), a = t.substring(s + 1), a.startsWith(" ") && (a = a.substring(1))), i = i.trim(), a = a.trim(), m(i, a, e);
+    } catch (s) {
+      r.error(
+        s instanceof Error ? s : new Error(String(s))
       ), e.event = "message", e.id = void 0, e.retry = void 0, e.data = [];
     }
   }
@@ -88,22 +88,22 @@ class h {
    * Called when the stream ends, used to process remaining data
    * @param controller Controller for controlling the transform stream
    */
-  flush(r) {
-    let t = this.currentEvent;
+  flush(t) {
+    let r = this.currentEvent;
     try {
-      t.data.length > 0 && r.enqueue({
-        event: t.event || "message",
-        data: t.data.join(`
+      r.data.length > 0 && t.enqueue({
+        event: r.event || "message",
+        data: r.data.join(`
 `),
-        id: t.id || "",
-        retry: t.retry
+        id: r.id || "",
+        retry: r.retry
       });
     } catch (e) {
-      r.error(
+      t.error(
         e instanceof Error ? e : new Error(String(e))
       );
     } finally {
-      t.event = "message", t.id = void 0, t.retry = void 0, t.data = [];
+      r.event = "message", r.id = void 0, r.retry = void 0, r.data = [];
     }
   }
 }
@@ -112,32 +112,23 @@ class y extends TransformStream {
     super(new h());
   }
 }
-class v {
-  /**
-   * Convert HTTP response to server-sent event stream
-   *
-   * @param response - HTTP response object, should contain text/event-stream formatted data
-   * @returns ServerSentEventStream - Server event stream, can be used to read events sent by the server
-   * @throws Error - Throws error when response body is null
-   */
-  static toEventStream(r) {
-    if (!r.body)
-      throw new Error("Response body is null");
-    return r.body.pipeThrough(new TextDecoderStream("utf-8")).pipeThrough(new c()).pipeThrough(new y());
-  }
+function T(n) {
+  if (!n.body)
+    throw new Error("Response body is null");
+  return n.body.pipeThrough(new TextDecoderStream("utf-8")).pipeThrough(new u()).pipeThrough(new y());
 }
 class p {
-  intercept(r) {
-    const t = r.headers.get(o);
-    return t && t.includes(f.TEXT_EVENT_STREAM) && (r.eventStream = () => v.toEventStream(r)), r;
+  intercept(t) {
+    const r = t.headers.get(o);
+    return r && r.includes(f.TEXT_EVENT_STREAM) && (t.eventStream = () => T(t)), t;
   }
 }
 export {
-  v as EventStreamConverter,
   p as EventStreamInterceptor,
-  u as ServerSentEventField,
+  c as ServerSentEventField,
   y as ServerSentEventTransformStream,
   h as ServerSentEventTransformer,
-  c as TextLineTransformStream,
-  d as TextLineTransformer
+  u as TextLineTransformStream,
+  d as TextLineTransformer,
+  T as toServerSentEventStream
 };

package/dist/index.umd.js

@@ -1,4 +1,4 @@
-(function(n,o){typeof exports=="object"&&typeof module<"u"?o(exports,require("@ahoo-wang/fetcher")):typeof define=="function"&&define.amd?define(["exports","@ahoo-wang/fetcher"],o):(n=typeof globalThis<"u"?globalThis:n||self,o(n.FetcherEventStream={},n.Fetcher))})(this,(function(n,o){"use strict";class d{constructor(){this.buffer=""}transform(r,t){try{this.buffer+=r;const e=this.buffer.split(`
-`);this.buffer=e.pop()||"";for(const s of e)t.enqueue(s)}catch(e){t.error(e)}}flush(r){try{this.buffer&&r.enqueue(this.buffer)}catch(t){r.error(t)}}}class u extends TransformStream{constructor(){super(new d)}}var c=(a=>(a.ID="id",a.RETRY="retry",a.EVENT="event",a.DATA="data",a))(c||{});function T(a,r,t){switch(a){case"event":t.event=r;break;case"data":t.data.push(r);break;case"id":t.id=r;break;case"retry":const e=parseInt(r,10);isNaN(e)||(t.retry=e);break}}class m{constructor(){this.currentEvent={event:"message",id:void 0,retry:void 0,data:[]}}transform(r,t){let e=this.currentEvent;try{if(r.trim()===""){e.data.length>0&&(t.enqueue({event:e.event||"message",data:e.data.join(`
-`),id:e.id||"",retry:e.retry}),e.event="message",e.id=e.id,e.retry=e.retry,e.data=[]);return}if(r.startsWith(":"))return;const s=r.indexOf(":");let f,i;s===-1?(f=r.toLowerCase(),i=""):(f=r.substring(0,s).toLowerCase(),i=r.substring(s+1),i.startsWith(" ")&&(i=i.substring(1))),f=f.trim(),i=i.trim(),T(f,i,e)}catch(s){t.error(s instanceof Error?s:new Error(String(s))),e.event="message",e.id=void 0,e.retry=void 0,e.data=[]}}flush(r){let t=this.currentEvent;try{t.data.length>0&&r.enqueue({event:t.event||"message",data:t.data.join(`
-`),id:t.id||"",retry:t.retry})}catch(e){r.error(e instanceof Error?e:new Error(String(e)))}finally{t.event="message",t.id=void 0,t.retry=void 0,t.data=[]}}}class v extends TransformStream{constructor(){super(new m)}}class h{static toEventStream(r){if(!r.body)throw new Error("Response body is null");return r.body.pipeThrough(new TextDecoderStream("utf-8")).pipeThrough(new u).pipeThrough(new v)}}class y{intercept(r){const t=r.headers.get(o.ContentTypeHeader);return t&&t.includes(o.ContentTypeValues.TEXT_EVENT_STREAM)&&(r.eventStream=()=>h.toEventStream(r)),r}}n.EventStreamConverter=h,n.EventStreamInterceptor=y,n.ServerSentEventField=c,n.ServerSentEventTransformStream=v,n.ServerSentEventTransformer=m,n.TextLineTransformStream=u,n.TextLineTransformer=d,Object.defineProperty(n,Symbol.toStringTag,{value:"Module"})}));
+(function(a,o){typeof exports=="object"&&typeof module<"u"?o(exports,require("@ahoo-wang/fetcher")):typeof define=="function"&&define.amd?define(["exports","@ahoo-wang/fetcher"],o):(a=typeof globalThis<"u"?globalThis:a||self,o(a.FetcherEventStream={},a.Fetcher))})(this,(function(a,o){"use strict";class d{constructor(){this.buffer=""}transform(t,r){try{this.buffer+=t;const e=this.buffer.split(`
+`);this.buffer=e.pop()||"";for(const i of e)r.enqueue(i)}catch(e){r.error(e)}}flush(t){try{this.buffer&&t.enqueue(this.buffer)}catch(r){t.error(r)}}}class u extends TransformStream{constructor(){super(new d)}}var c=(n=>(n.ID="id",n.RETRY="retry",n.EVENT="event",n.DATA="data",n))(c||{});function T(n,t,r){switch(n){case"event":r.event=t;break;case"data":r.data.push(t);break;case"id":r.id=t;break;case"retry":const e=parseInt(t,10);isNaN(e)||(r.retry=e);break}}class m{constructor(){this.currentEvent={event:"message",id:void 0,retry:void 0,data:[]}}transform(t,r){let e=this.currentEvent;try{if(t.trim()===""){e.data.length>0&&(r.enqueue({event:e.event||"message",data:e.data.join(`
+`),id:e.id||"",retry:e.retry}),e.event="message",e.id=e.id,e.retry=e.retry,e.data=[]);return}if(t.startsWith(":"))return;const i=t.indexOf(":");let f,s;i===-1?(f=t.toLowerCase(),s=""):(f=t.substring(0,i).toLowerCase(),s=t.substring(i+1),s.startsWith(" ")&&(s=s.substring(1))),f=f.trim(),s=s.trim(),T(f,s,e)}catch(i){r.error(i instanceof Error?i:new Error(String(i))),e.event="message",e.id=void 0,e.retry=void 0,e.data=[]}}flush(t){let r=this.currentEvent;try{r.data.length>0&&t.enqueue({event:r.event||"message",data:r.data.join(`
+`),id:r.id||"",retry:r.retry})}catch(e){t.error(e instanceof Error?e:new Error(String(e)))}finally{r.event="message",r.id=void 0,r.retry=void 0,r.data=[]}}}class h extends TransformStream{constructor(){super(new m)}}function v(n){if(!n.body)throw new Error("Response body is null");return n.body.pipeThrough(new TextDecoderStream("utf-8")).pipeThrough(new u).pipeThrough(new h)}class y{intercept(t){const r=t.headers.get(o.ContentTypeHeader);return r&&r.includes(o.ContentTypeValues.TEXT_EVENT_STREAM)&&(t.eventStream=()=>v(t)),t}}a.EventStreamInterceptor=y,a.ServerSentEventField=c,a.ServerSentEventTransformStream=h,a.ServerSentEventTransformer=m,a.TextLineTransformStream=u,a.TextLineTransformer=d,a.toServerSentEventStream=v,Object.defineProperty(a,Symbol.toStringTag,{value:"Module"})}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahoo-wang/fetcher-eventstream",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Support for text/event-stream in Fetcher",
   "keywords": [
     "fetch",
@@ -24,16 +24,16 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.es.js",
-      "require": "./dist/index.umd.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.umd.js"
     }
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@ahoo-wang/fetcher": "0.1.5"
+    "@ahoo-wang/fetcher": "0.2.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^3.2.4",