stream-axios 1.2.0 → 1.2.1

package/README.md

@@ -52,7 +52,7 @@ request
 
 ### 2. Streaming Request
 
-Suitable for scenarios like receiving large files or AI conversation streams.
+Suitable for scenarios like receiving large files or AI conversation streams. The `stream` method returns a **cancel function** that you can call to abort the request.
 
 ```javascript
 import { createInstance } from "stream-axios";
@@ -79,13 +79,26 @@ const cancel = await request.stream(
   },
 );
 
-// If you need to cancel the request
-// cancel();
+// Cancel the stream manually when needed
+cancel();
+```
+
+**Optional: use `AbortSignal`** to cancel from outside (e.g. React cleanup):
+
+```javascript
+const controller = new AbortController();
+await request.stream(
+  { url: "/api/chat", signal: controller.signal },
+  onChunk,
+  onComplete,
+  onError,
+);
+// controller.abort(); // cancels the request
 ```
 
 ### 3. Custom Instance
 
-If you need independent configuration or interceptors:
+`createInstance` merges your config with the default (timeout 15s, `Content-Type: application/json;charset=utf-8`). Override as needed:
 
 ```javascript
 import { createInstance } from "stream-axios";
@@ -100,102 +113,59 @@ myRequest.interceptors.request.use((config) => {
   config.headers["Authorization"] = "Bearer token";
   return config;
 });
-
-// Use stream method
-myRequest.stream({ url: "/stream" }, (chunk) => console.log(chunk));
 ```
 
-### 4. SSE Parsing Helper
+### 4. Attach Stream to Existing Axios Instance
 
-If you are handling SSE (Server-Sent Events) format data:
+If you already have an axios instance, use `attachStream` to add the `stream` method without creating a new instance:
 
 ```javascript
-import { createInstance, parseSSEChunk } from "stream-axios";
+import axios from "axios";
+import { attachStream } from "stream-axios";
 
-const request = createInstance();
+const instance = axios.create({ baseURL: "https://api.example.com" });
+attachStream(instance);
 
-// Simple usage - parse data field only
-request.stream({ url: "/sse-endpoint", method: "GET" }, (chunk) => {
-  parseSSEChunk(chunk, (content) => {
-    console.log("SSE Message:", content);
-  });
-});
+// instance.stream() is now available
+const cancel = await instance.stream({ url: "/api/stream" }, onChunk, onComplete, onError);
 ```
 
-For production environments, use `createSSEParser` which handles chunks that may be split across multiple packets:
+### 5. Helper Functions
+
+#### `createSSEParser` (stateful, handles split chunks)
+
+Use for robust SSE parsing when chunks may be split across reads. Callback receives the full event object:
 
 ```javascript
 import { createInstance, createSSEParser } from "stream-axios";
 
 const request = createInstance();
 
-// Create a stateful parser with buffer
 const parser = createSSEParser((event) => {
-  // event object contains: { event?, data?, id?, retry? }
-  console.log("Event type:", event.event);
-  console.log("Data:", event.data);
-  console.log("ID:", event.id);
+  // event: { event?: string, data?: string, id?: string, retry?: number }
+  if (event.data) {
+    console.log("SSE Data:", event.data);
+  }
 });
 
-request.stream(
-  { url: "/sse-endpoint", method: "GET" },
-  parser,
-  () => console.log("Completed"),
-  (error) => console.error("Error:", error),
+await request.stream(
+  { url: "/api/sse-stream" },
+  (chunk) => parser(chunk),
 );
 ```
 
-### 5. Cancel with External AbortSignal
+#### `parseSSEChunk` (stateless, full chunks only)
 
-You can pass an external `AbortSignal` to control the stream request:
+Use when you have a complete SSE text chunk and only need the data content. Callback receives each message's data string:
 
 ```javascript
-import { createInstance } from "stream-axios";
+import { parseSSEChunk } from "stream-axios";
 
-const request = createInstance();
-const controller = new AbortController();
-
-request.stream(
-  {
-    url: "/api/chat",
-    method: "POST",
-    data: { message: "Hello" },
-    signal: controller.signal, // Pass external signal
-  },
-  (chunk) => console.log(chunk),
-  () => console.log("Completed"),
-  (error) => console.error(error),
-);
-
-// Cancel from external controller
-setTimeout(() => {
-  controller.abort();
-}, 5000);
-```
-
-### 6. Use with Existing Axios Instance
-
-If you already have a configured axios instance in your project, you can attach the stream method to it:
-
-```javascript
-import axios from "axios";
-import { attachStream } from "stream-axios";
-
-// Your existing axios instance
-const myAxios = axios.create({
-  baseURL: "https://api.myproject.com",
-  headers: { "X-Custom-Header": "foobar" },
-});
-
-// Attach stream method
-attachStream(myAxios);
-
-// Now you can use .stream() on your instance
-myAxios.stream({ url: "/chat" }, (chunk) => {
-  console.log(chunk);
+const sseText = "data: hello\n\ndata: world\n\n";
+parseSSEChunk(sseText, (data) => {
+  console.log("Message:", data); // "hello", then "world"
 });
 ```
-
 ## License
 
 MIT

package/README.zh-CN.md

@@ -52,10 +52,12 @@ request
 
 ### 2. 流式请求 (Streaming)
 
-适用于接收大文件或 AI 对话流等场景。
+适用于接收大文件或 AI 对话流等场景。`stream` 方法会返回一个**取消函数**，调用即可中止请求。
 
 ```javascript
-import request from "stream-axios";
+import { createInstance } from "stream-axios";
+
+const request = createInstance();
 
 const cancel = await request.stream(
   {
@@ -77,13 +79,26 @@ const cancel = await request.stream(
   },
 );
 
-// 如果需要取消请求
-// cancel();
+// 需要时手动取消流
+cancel();
+```
+
+**可选：使用 `AbortSignal`** 从外部取消（例如 React 清理时）：
+
+```javascript
+const controller = new AbortController();
+await request.stream(
+  { url: "/api/chat", signal: controller.signal },
+  onChunk,
+  onComplete,
+  onError,
+);
+// controller.abort(); // 取消请求
 ```
 
 ### 3. 自定义实例
 
-如果你需要独立的配置或拦截器：
+`createInstance` 会将你的配置与默认配置（超时 15 秒、`Content-Type: application/json;charset=utf-8`）合并，可按需覆盖：
 
 ```javascript
 import { createInstance } from "stream-axios";
@@ -98,106 +113,63 @@ myRequest.interceptors.request.use((config) => {
   config.headers["Authorization"] = "Bearer token";
   return config;
 });
-
-// 使用流式方法
-myRequest.stream({ url: "/stream" }, (chunk) => console.log(chunk));
 ```
 
-### 4. SSE 解析助手
+### 4. 为已有 axios 实例挂载 stream
 
-如果你处理的是 SSE (Server-Sent Events) 格式的数据：
+若已有 axios 实例，可用 `attachStream` 为其添加 `stream` 方法，无需新建实例：
 
 ```javascript
-import { createInstance, parseSSEChunk } from "stream-axios";
+import axios from "axios";
+import { attachStream } from "stream-axios";
 
-const request = createInstance();
+const instance = axios.create({ baseURL: "https://api.example.com" });
+attachStream(instance);
 
-// 简单用法 - 仅解析 data 字段
-request.stream({ url: "/sse-endpoint", method: "GET" }, (chunk) => {
-  parseSSEChunk(chunk, (content) => {
-    console.log("SSE Message:", content);
-  });
-});
+// instance.stream() 现已可用
+const cancel = await instance.stream({ url: "/api/stream" }, onChunk, onComplete, onError);
 ```
 
-对于生产环境，建议使用 `createSSEParser`，它可以处理跨数据包拆分的 chunk：
+### 5. 辅助函数
+
+#### `createSSEParser`（有状态，可处理分片）
+
+当 SSE 数据可能被拆成多段时，用此解析器更稳妥。回调会收到完整事件对象：
 
 ```javascript
 import { createInstance, createSSEParser } from "stream-axios";
 
 const request = createInstance();
 
-// 创建带缓冲区的有状态解析器
 const parser = createSSEParser((event) => {
-  // event 对象包含: { event?, data?, id?, retry? }
-  console.log("事件类型:", event.event);
-  console.log("数据:", event.data);
-  console.log("ID:", event.id);
+  // event: { event?: string, data?: string, id?: string, retry?: number }
+  if (event.data) {
+    console.log("SSE Data:", event.data);
+  }
 });
 
-request.stream(
-  { url: "/sse-endpoint", method: "GET" },
-  parser,
-  () => console.log("完成"),
-  (error) => console.error("错误:", error),
-);
-```
-
-### 5. 使用外部 AbortSignal 取消请求
-
-你可以传入外部的 `AbortSignal` 来控制流式请求：
-
-```javascript
-import { createInstance } from "stream-axios";
-
-const request = createInstance();
-const controller = new AbortController();
-
-request.stream(
-  {
-    url: "/api/chat",
-    method: "POST",
-    data: { message: "Hello" },
-    signal: controller.signal, // 传入外部信号
-  },
-  (chunk) => console.log(chunk),
-  () => console.log("完成"),
-  (error) => console.error(error),
+await request.stream(
+  { url: "/api/sse-stream" },
+  (chunk) => parser(chunk),
 );
-
-// 从外部控制器取消请求
-setTimeout(() => {
-  controller.abort();
-}, 5000);
 ```
 
-### 6. 使用现有的 Axios 实例
+#### `parseSSEChunk`（无状态，仅完整块）
 
-如果你项目中已经有了配置好的 axios 实例，你可以将 stream 方法挂载到该实例上：
+当已有完整的一段 SSE 文本且只需取出 data 内容时使用。回调仅接收每条消息的 data 字符串：
 
 ```javascript
-import axios from "axios";
-import { attachStream } from "stream-axios";
+import { parseSSEChunk } from "stream-axios";
 
-// 你现有的 axios 实例
-const myAxios = axios.create({
-  baseURL: "https://api.myproject.com",
-  headers: { "X-Custom-Header": "foobar" },
-});
-
-// 挂载 stream 方法
-attachStream(myAxios);
-
-// 现在你可以在实例上使用 .stream() 方法了
-myAxios.stream({ url: "/chat" }, (chunk) => {
-  console.log(chunk);
+const sseText = "data: hello\n\ndata: world\n\n";
+parseSSEChunk(sseText, (data) => {
+  console.log("Message:", data); // "hello", 然后 "world"
 });
 ```
-
 ## License
 
 MIT
 
 ## 致谢
 
-本项目基于 [Axios](https://github.com/axios/axios) 开发。
+本项目基于 [Axios](https://github.com/axios/axios) 开发

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stream-axios",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "二次封装 axios，保留原始配置，提供流式接口，提升开发效率",
   "type": "module",
   "main": "dist/index.cjs",