stream-axios 1.1.0 → 1.2.1

package/README.md

@@ -22,7 +22,9 @@ npm install stream-axios
 ### 1. Basic Request (Same as axios)
 
 ```javascript
-import request from "stream-axios";
+import { createInstance } from "stream-axios";
+
+const request = createInstance();
 
 // GET request
 request
@@ -50,10 +52,12 @@ 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 request from "stream-axios";
+import { createInstance } from "stream-axios";
+
+const request = createInstance();
 
 const cancel = await request.stream(
   {
@@ -75,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";
@@ -96,49 +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 request, { parseSSEChunk } from "stream-axios";
+import axios from "axios";
+import { attachStream } from "stream-axios";
 
-request.stream({ url: "/sse-endpoint", method: "GET" }, (chunk) => {
-  // Parse SSE data
-  parseSSEChunk(chunk, (content) => {
-    console.log("SSE Message:", content);
-  });
-});
+const instance = axios.create({ baseURL: "https://api.example.com" });
+attachStream(instance);
+
+// instance.stream() is now available
+const cancel = await instance.stream({ url: "/api/stream" }, onChunk, onComplete, onError);
 ```
 
-### 5. Use with Existing Axios Instance
+### 5. Helper Functions
 
-If you already have a configured axios instance in your project, you can attach the stream method to it:
+#### `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 axios from "axios";
-import { attachStream } from "stream-axios";
+import { createInstance, createSSEParser } from "stream-axios";
+
+const request = createInstance();
 
-// Your existing axios instance
-const myAxios = axios.create({
-  baseURL: "https://api.myproject.com",
-  headers: { "X-Custom-Header": "foobar" },
+const parser = createSSEParser((event) => {
+  // event: { event?: string, data?: string, id?: string, retry?: number }
+  if (event.data) {
+    console.log("SSE Data:", event.data);
+  }
 });
 
-// Attach stream method
-attachStream(myAxios);
+await request.stream(
+  { url: "/api/sse-stream" },
+  (chunk) => parser(chunk),
+);
+```
+
+#### `parseSSEChunk` (stateless, full chunks only)
+
+Use when you have a complete SSE text chunk and only need the data content. Callback receives each message's data string:
 
-// Now you can use .stream() on your instance
-myAxios.stream({ url: "/chat" }, (chunk) => {
-  console.log(chunk);
+```javascript
+import { parseSSEChunk } from "stream-axios";
+
+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

@@ -22,7 +22,9 @@ npm install stream-axios
 ### 1. 基础请求 (同 axios)
 
 ```javascript
-import request from "stream-axios";
+import { createInstance } from "stream-axios";
+
+const request = createInstance();
 
 // GET 请求
 request
@@ -50,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(
   {
@@ -75,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";
@@ -96,53 +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 request, { parseSSEChunk } from "stream-axios";
+import axios from "axios";
+import { attachStream } from "stream-axios";
 
-request.stream({ url: "/sse-endpoint", method: "GET" }, (chunk) => {
-  // 解析 SSE 数据
-  parseSSEChunk(chunk, (content) => {
-    console.log("SSE Message:", content);
-  });
-});
+const instance = axios.create({ baseURL: "https://api.example.com" });
+attachStream(instance);
+
+// instance.stream() 现已可用
+const cancel = await instance.stream({ url: "/api/stream" }, onChunk, onComplete, onError);
 ```
 
-### 5. 使用现有的 Axios 实例
+### 5. 辅助函数
 
-如果你项目中已经有了配置好的 axios 实例，你可以将 stream 方法挂载到该实例上：
+#### `createSSEParser`（有状态，可处理分片）
+
+当 SSE 数据可能被拆成多段时，用此解析器更稳妥。回调会收到完整事件对象：
 
 ```javascript
-import axios from "axios";
-import { attachStream } from "stream-axios";
+import { createInstance, createSSEParser } from "stream-axios";
+
+const request = createInstance();
 
-// 你现有的 axios 实例
-const myAxios = axios.create({
-  baseURL: "https://api.myproject.com",
-  headers: { "X-Custom-Header": "foobar" },
+const parser = createSSEParser((event) => {
+  // event: { event?: string, data?: string, id?: string, retry?: number }
+  if (event.data) {
+    console.log("SSE Data:", event.data);
+  }
 });
 
-// 挂载 stream 方法
-attachStream(myAxios);
+await request.stream(
+  { url: "/api/sse-stream" },
+  (chunk) => parser(chunk),
+);
+```
+
+#### `parseSSEChunk`（无状态，仅完整块）
+
+当已有完整的一段 SSE 文本且只需取出 data 内容时使用。回调仅接收每条消息的 data 字符串：
 
-// 现在你可以在实例上使用 .stream() 方法了
-myAxios.stream({ url: "/chat" }, (chunk) => {
-  console.log(chunk);
+```javascript
+import { parseSSEChunk } from "stream-axios";
+
+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/dist/index.cjs

@@ -1,7 +1,5 @@
 'use strict';
 
-Object.defineProperty(exports, '__esModule', { value: true });
-
 var axios = require('axios');
 
 const defaultConfig = {
@@ -12,23 +10,79 @@ const defaultConfig = {
 };
 
 /**
- * Parse SSE data chunk
- * @param {string} sseText
- * @param {Function} onMessage
+ * Parse a single SSE event block
+ * @param {string} eventBlock - A single SSE event (lines separated by \n)
+ * @returns {{ event?: string, data?: string, id?: string, retry?: number } | null}
+ */
+function parseSSEEvent(eventBlock) {
+  const lines = eventBlock.split("\n");
+  const result = {};
+  const dataLines = [];
+
+  for (const line of lines) {
+    if (line.startsWith("data:")) {
+      // Support both "data: content" and "data:content"
+      const content = line.slice(5);
+      dataLines.push(content.startsWith(" ") ? content.slice(1) : content);
+    } else if (line.startsWith("event:")) {
+      result.event = line.slice(6).trim();
+    } else if (line.startsWith("id:")) {
+      result.id = line.slice(3).trim();
+    } else if (line.startsWith("retry:")) {
+      const retry = parseInt(line.slice(6).trim(), 10);
+      if (!isNaN(retry)) result.retry = retry;
+    }
+    // Ignore comments (lines starting with :) and unknown fields
+  }
+
+  // Join multiple data lines with newline (per SSE spec)
+  if (dataLines.length > 0) {
+    result.data = dataLines.join("\n");
+  }
+
+  return Object.keys(result).length > 0 ? result : null;
+}
+
+/**
+ * Parse SSE data chunk (simple, stateless version)
+ * @param {string} sseText - Raw SSE text chunk
+ * @param {Function} onMessage - Callback receiving data content string
  */
 function parseSSEChunk(sseText, onMessage) {
-  const sseLines = sseText.split("\n\n").filter(Boolean);
-  for (const line of sseLines) {
-    const dataPrefix = "data: ";
-    if (line.startsWith(dataPrefix)) {
-      const validContent = line.slice(dataPrefix.length).trim();
-      if (validContent) {
-        onMessage(validContent);
-      }
+  const events = sseText.split("\n\n").filter(Boolean);
+  for (const eventBlock of events) {
+    const parsed = parseSSEEvent(eventBlock);
+    if (parsed?.data) {
+      onMessage(parsed.data);
     }
   }
 }
 
+/**
+ * Create a stateful SSE parser with buffer for handling chunks that may be split
+ * @param {Function} onMessage - Callback receiving parsed SSE event object { event?, data?, id?, retry? }
+ * @returns {Function} Parser function that accepts raw chunk string
+ */
+function createSSEParser(onMessage) {
+  let buffer = "";
+
+  return (chunk) => {
+    buffer += chunk;
+    // Split by double newline (SSE event separator)
+    const parts = buffer.split("\n\n");
+    // Keep the last incomplete part in buffer
+    buffer = parts.pop() || "";
+
+    for (const eventBlock of parts) {
+      if (!eventBlock.trim()) continue;
+      const parsed = parseSSEEvent(eventBlock);
+      if (parsed) {
+        onMessage(parsed);
+      }
+    }
+  };
+}
+
 /**
  * Create a stream request function bound to an axios instance
  * @param {import('axios').AxiosInstance} instance
@@ -37,9 +91,28 @@ const createStreamRequest = (instance) => {
   return async (options = {}, onChunk, onComplete, onError) => {
     const controller = new AbortController();
     let reader = null;
+    let externalSignalHandler = null;
+
+    // Handle external signal
+    if (options.signal) {
+      if (options.signal.aborted) {
+        controller.abort();
+      } else {
+        externalSignalHandler = () => controller.abort();
+        options.signal.addEventListener("abort", externalSignalHandler);
+      }
+    }
+
+    const cleanup = () => {
+      if (options.signal && externalSignalHandler) {
+        options.signal.removeEventListener("abort", externalSignalHandler);
+        externalSignalHandler = null;
+      }
+    };
 
     const cancelRequest = () => {
       try {
+        cleanup();
         controller.abort();
         reader?.releaseLock();
         if (onError) onError("Stream request cancelled manually");
@@ -79,6 +152,7 @@ const createStreamRequest = (instance) => {
         try {
           const { done, value } = await reader.read();
           if (done) {
+            cleanup();
             if (onComplete) onComplete();
             return;
           }
@@ -87,6 +161,7 @@ const createStreamRequest = (instance) => {
           if (onChunk) onChunk(chunk);
           await readStreamChunk();
         } catch (err) {
+          cleanup();
           if (err.name === "AbortError") return;
           if (onError) onError(`Read stream failed: ${err.message}`);
         }
@@ -122,9 +197,6 @@ const createInstance = (config = {}) => {
   return instance;
 };
 
-// Create a default instance
-const service = createInstance();
-
 /**
  * Attach stream method to an existing axios instance
  * @param {import('axios').AxiosInstance} instance
@@ -137,6 +209,5 @@ const attachStream = (instance) => {
 
 exports.attachStream = attachStream;
 exports.createInstance = createInstance;
-exports.createStreamRequest = createStreamRequest;
-exports.default = service;
+exports.createSSEParser = createSSEParser;
 exports.parseSSEChunk = parseSSEChunk;

package/dist/index.js

@@ -8,23 +8,79 @@ const defaultConfig = {
 };
 
 /**
- * Parse SSE data chunk
- * @param {string} sseText
- * @param {Function} onMessage
+ * Parse a single SSE event block
+ * @param {string} eventBlock - A single SSE event (lines separated by \n)
+ * @returns {{ event?: string, data?: string, id?: string, retry?: number } | null}
+ */
+function parseSSEEvent(eventBlock) {
+  const lines = eventBlock.split("\n");
+  const result = {};
+  const dataLines = [];
+
+  for (const line of lines) {
+    if (line.startsWith("data:")) {
+      // Support both "data: content" and "data:content"
+      const content = line.slice(5);
+      dataLines.push(content.startsWith(" ") ? content.slice(1) : content);
+    } else if (line.startsWith("event:")) {
+      result.event = line.slice(6).trim();
+    } else if (line.startsWith("id:")) {
+      result.id = line.slice(3).trim();
+    } else if (line.startsWith("retry:")) {
+      const retry = parseInt(line.slice(6).trim(), 10);
+      if (!isNaN(retry)) result.retry = retry;
+    }
+    // Ignore comments (lines starting with :) and unknown fields
+  }
+
+  // Join multiple data lines with newline (per SSE spec)
+  if (dataLines.length > 0) {
+    result.data = dataLines.join("\n");
+  }
+
+  return Object.keys(result).length > 0 ? result : null;
+}
+
+/**
+ * Parse SSE data chunk (simple, stateless version)
+ * @param {string} sseText - Raw SSE text chunk
+ * @param {Function} onMessage - Callback receiving data content string
  */
 function parseSSEChunk(sseText, onMessage) {
-  const sseLines = sseText.split("\n\n").filter(Boolean);
-  for (const line of sseLines) {
-    const dataPrefix = "data: ";
-    if (line.startsWith(dataPrefix)) {
-      const validContent = line.slice(dataPrefix.length).trim();
-      if (validContent) {
-        onMessage(validContent);
-      }
+  const events = sseText.split("\n\n").filter(Boolean);
+  for (const eventBlock of events) {
+    const parsed = parseSSEEvent(eventBlock);
+    if (parsed?.data) {
+      onMessage(parsed.data);
     }
   }
 }
 
+/**
+ * Create a stateful SSE parser with buffer for handling chunks that may be split
+ * @param {Function} onMessage - Callback receiving parsed SSE event object { event?, data?, id?, retry? }
+ * @returns {Function} Parser function that accepts raw chunk string
+ */
+function createSSEParser(onMessage) {
+  let buffer = "";
+
+  return (chunk) => {
+    buffer += chunk;
+    // Split by double newline (SSE event separator)
+    const parts = buffer.split("\n\n");
+    // Keep the last incomplete part in buffer
+    buffer = parts.pop() || "";
+
+    for (const eventBlock of parts) {
+      if (!eventBlock.trim()) continue;
+      const parsed = parseSSEEvent(eventBlock);
+      if (parsed) {
+        onMessage(parsed);
+      }
+    }
+  };
+}
+
 /**
  * Create a stream request function bound to an axios instance
  * @param {import('axios').AxiosInstance} instance
@@ -33,9 +89,28 @@ const createStreamRequest = (instance) => {
   return async (options = {}, onChunk, onComplete, onError) => {
     const controller = new AbortController();
     let reader = null;
+    let externalSignalHandler = null;
+
+    // Handle external signal
+    if (options.signal) {
+      if (options.signal.aborted) {
+        controller.abort();
+      } else {
+        externalSignalHandler = () => controller.abort();
+        options.signal.addEventListener("abort", externalSignalHandler);
+      }
+    }
+
+    const cleanup = () => {
+      if (options.signal && externalSignalHandler) {
+        options.signal.removeEventListener("abort", externalSignalHandler);
+        externalSignalHandler = null;
+      }
+    };
 
     const cancelRequest = () => {
       try {
+        cleanup();
         controller.abort();
         reader?.releaseLock();
         if (onError) onError("Stream request cancelled manually");
@@ -75,6 +150,7 @@ const createStreamRequest = (instance) => {
         try {
           const { done, value } = await reader.read();
           if (done) {
+            cleanup();
             if (onComplete) onComplete();
             return;
           }
@@ -83,6 +159,7 @@ const createStreamRequest = (instance) => {
           if (onChunk) onChunk(chunk);
           await readStreamChunk();
         } catch (err) {
+          cleanup();
           if (err.name === "AbortError") return;
           if (onError) onError(`Read stream failed: ${err.message}`);
         }
@@ -118,9 +195,6 @@ const createInstance = (config = {}) => {
   return instance;
 };
 
-// Create a default instance
-const service = createInstance();
-
 /**
  * Attach stream method to an existing axios instance
  * @param {import('axios').AxiosInstance} instance
@@ -131,4 +205,4 @@ const attachStream = (instance) => {
   return instance;
 };
 
-export { attachStream, createInstance, createStreamRequest, service as default, parseSSEChunk };
+export { attachStream, createInstance, createSSEParser, parseSSEChunk };

package/package.json

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